Modo Sandbox (Test)

El modo sandbox permite probar tu integración de forma completamente segura:

• Cero impacto en producción — no se escribe ninguna fila en la base de datos real
• Sin consumo de créditos — las guías creadas en modo test no debitan tu saldo
• Sin efectos operacionales — ningún mensajero ni proceso interno recibe los datos
• Misma URL, mismo formato de respuesta — solo cambia el token que usas

Obtener tu token de pruebas

Cuando generas tokens en el portal de Integraciones, recibes un par al mismo tiempo:

Guárdalos como variables de entorno separadas:

# .env.local
TPC_API_TOKEN=tpc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TPC_API_TOKEN_TEST=tpc_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Guías fixture (determinísticas)

Cinco guías están reservadas con estados predefinidos para que puedas probar cada rama de tu código de forma determinística:

Las guías que crees con POST /guias en modo test reciben un número con prefijo TPCT y se comportan como SIN_RECOLLECTAR.

Quickstart completo

1 · Crear una guía (sandbox)

curl -X POST https://api.tpcxpress.com/api/v1/guias \
  -H "Authorization: Bearer $TPC_API_TOKEN_TEST" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoServicio": "ESTANDAR",
    "ciudadDestino": "Guatemala",
    "nombreDestinatario": "Ana López",
    "telefonoDestinatario": "5555-9876",
    "direccionDestinatario": "4a Avenida 12-34, Zona 10"
  }'

const res = await fetch('https://api.tpcxpress.com/api/v1/guias', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TPC_API_TOKEN_TEST}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tipoServicio: 'ESTANDAR',
    ciudadDestino: 'Guatemala',
    nombreDestinatario: 'Ana López',
    telefonoDestinatario: '5555-9876',
    direccionDestinatario: '4a Avenida 12-34, Zona 10',
  }),
})
const data = await res.json()
// data.data.test === true
// data.data.numeroGuia === "TPCT..."

import httpx
import os
 
client = httpx.Client(
    base_url="https://api.tpcxpress.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['TPC_API_TOKEN_TEST']}"},
)
 
r = client.post("/guias", json={
    "tipoServicio": "ESTANDAR",
    "ciudadDestino": "Guatemala",
    "nombreDestinatario": "Ana López",
    "telefonoDestinatario": "5555-9876",
    "direccionDestinatario": "4a Avenida 12-34, Zona 10",
})
data = r.json()
# data["data"]["test"] is True
# data["data"]["numeroGuia"] starts with "TPCT"

Respuesta:

{
  "success": true,
  "data": {
    "test": true,
    "numeroGuia": "TPCT1234567890",
    "estado": "SIN_RECOLLECTAR",
    "pdfUrl": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "_sandbox": {
      "note": "No se creó ninguna guía real. Usa este numeroGuia en otras rutas sandbox.",
      "fixtures": ["TPCT000000001", "TPCT000000002", "TPCT000000003", "TPCT000000004", "TPCT000000005"]
    }
  }
}

2 · Consultar una guía fixture

curl https://api.tpcxpress.com/api/v1/guias/TPCT000000003 \
  -H "Authorization: Bearer $TPC_API_TOKEN_TEST"

Responde con estado: "ENTREGADO" y todos sus campos simulados.

3 · Probar el estado de error INVALID_STATE

curl -X PATCH https://api.tpcxpress.com/api/v1/guias/TPCT000000002 \
  -H "Authorization: Bearer $TPC_API_TOKEN_TEST" \
  -H "Content-Type: application/json" \
  -d '{"nombreDestinatario": "Nuevo Nombre"}'

Responde 409 INVALID_STATE porque TPCT000000002 está en estado EN_RUTA.

4 · Ver historial de tracking

curl https://api.tpcxpress.com/api/v1/guias/TPCT000000002/tracking \
  -H "Authorization: Bearer $TPC_API_TOKEN_TEST"

Retorna un timeline simulado con eventos CREADA, RECOLECTADA, EN_RUTA.

Qué es real en modo sandbox

Webhooks y sandbox

En modo sandbox los endpoints de gestión de webhooks (POST, PATCH, DELETE /webhooks) están bloqueados — retornan 403 SANDBOX_NOT_ALLOWED. Esto evita que un token de prueba modifique la configuración de integraciones de producción.

GET /webhooks (lectura) sí funciona en sandbox, devolviendo los webhooks reales configurados.

Anular una guía sandbox

curl -X DELETE https://api.tpcxpress.com/api/v1/guias/TPCT000000001 \
  -H "Authorization: Bearer $TPC_API_TOKEN_TEST"

Solo funciona en guías con estado SIN_RECOLLECTAR. La guía fixture TPCT000000002 (EN_RUTA) retorna 409.

Rate limits en sandbox

El sandbox usa contadores separados del modo live:

• El límite diario de guías (500/día por empresa) tiene un contador independiente — las pruebas no consumen tu cuota de producción
• El límite por minuto por token (rate limit general) sí se aplica para proteger la infraestructura

Diferencias con producción