Modo de prueba

Un sandbox aislado con formas de API conocidas, paqueterías simuladas y saldo virtual, sin dinero real.

Toda organización de SendIt incluye un ambiente de prueba aislado. Replica producción sin tocar dinero real ni paqueterías reales. Se activa con una llave sk_test_... y no requiere ninguna otra configuración.

Cómo se determina el modo

Autenticación	Modo
Llave `sk_test_...`	Prueba
Llave `sk_live_...`	Producción
Sesión del dashboard	Producción por defecto; agrega `?livemode=false` para ver datos de prueba

El modo se resuelve una vez por petición y aplica a todas las lecturas y escrituras. Una petición de prueba no puede leer ni modificar datos de producción, ni al revés, aunque conozca el ID exacto del recurso.

Qué simula el modo de prueba

Función	Comportamiento en prueba
Llamadas a paqueterías	Totalmente simuladas — ninguna petición llega a DHL, FedEx ni Estafeta
Números de rastreo	`TEST-{PAQUETERÍA}-{aleatorio}` — imposibles de confundir con reales
URL de la guía	`https://labels.sendit.mx/test/{shipmentId}/{trackingNumber}.pdf`
Cargos al monedero	Se debitan del saldo de prueba virtual (inicia en $10,000 MXN); el saldo real nunca se toca
Webhooks	Se entregan normalmente, con `"livemode": false` en el payload
Avance de estado	Automático (simulación pausada) o manual vía endpoint de prueba
Cuota mensual	No cuenta
Límites de tasa	Cubeta aparte al 25% del límite de tu plan, con piso de 10 peticiones por minuto

El tráfico de prueba nunca consume la cubeta de producción. En el plan FREE, por ejemplo, un límite de cotización de 20/min queda en 10/min para sk_test_.... Las cubetas de lectura, escritura y cotización siguen siendo independientes. Ver límites de tasa.

Ve un envío completo en minutos

Cada paquete rastreado avanza solo, simulando un viaje real anclado al momento en que empezó el rastreo:

LABEL_CREATED (+0 min) → PICKED_UP (~+4) → IN_TRANSIT (~+9) → OUT_FOR_DELIVERY (~+14) → DELIVERED (~+27)

Algunos números de rastreo se entregan directamente desde IN_TRANSIT, igual que en el mundo real. Puedes observar el viaje completo, con los webhooks de cada transición, en menos de media hora y sin llamar nada.

Avanza el estado manualmente

¿No quieres esperar? Avanza un paso por llamada:

curl -X POST https://api.sendit.mx/v1/shipments/{id}/test/advance-status \
  -H "X-API-Key: sk_test_..."

LABEL_PURCHASED → READY_FOR_PICKUP → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED

Cada llamada devuelve el nuevo estado y registra el evento en el historial del envío.

Simula fallas y devoluciones

Incluye una palabra clave en el contactName del destinatario para activar progresiones alternas:

Palabra en contactName	Progresión
`SENDIT_FAIL`	`... IN_TRANSIT → FAILED`
`SENDIT_RETURN`	`... IN_TRANSIT → RETURNED`
(ninguna)	`... → DELIVERED` (por defecto)

{ "contactName": "Cliente Prueba SENDIT_FAIL", "...": "..." }

Úsalo para probar tus flujos de entrega fallida y devolución antes de que ocurran con clientes reales.

Distingue eventos de prueba en tus webhooks

Todo payload de webhook originado en modo de prueba lleva livemode: false:

{
  "id": "evt_...",
  "type": "shipment.tracking.updated",
  "livemode": false,
  "data": { "...": "..." }
}

Tu handler debe revisar livemode para enrutar los eventos correctamente entre tus ambientes de staging y producción.

Restablece el saldo de prueba

Cuando el saldo virtual se agote, restáuralo. Funciona en cualquier organización y no tiene límite:

curl -X POST https://api.sendit.mx/v1/wallet/test/reset \
  -H "Authorization: Bearer <jwt>"

{
  "data": { "balance": 10000, "currency": "MXN" },
  "message": "Test wallet reset to $10,000 MXN"
}

El saldo real nunca se ve afectado por el reset.

Consulta datos de prueba con una sesión del dashboard

Agrega ?livemode=false a los listados para leer datos de prueba con un JWT:

GET /v1/shipments?livemode=false
Authorization: Bearer <jwt>

Solo acepta las cadenas true y false. Cualquier otro valor, incluidos 0, 1, yes o vacío, devuelve 400 VALIDATION_ERROR. Si lo omites, lees producción.

El parámetro no aplica a las llaves de API: el ambiente de la llave manda siempre. Se acepta y se ignora.

Endpoint	Efecto de `?livemode=false`
`GET /v1/shipments`	Envíos de prueba
`GET /v1/trackers`	Rastreadores de prueba
`GET /v1/wallet/transactions`, `GET /v1/wallet/summary`, `GET /v1/wallet/balance`	Movimientos del saldo de prueba
`GET /v1/orders`	Órdenes de prueba
`GET /v1/api-requests`	Registros de peticiones de prueba
`GET /v1/webhook-endpoints/:id/events`	Entregas de prueba
`GET /v1/billing/invoices`, `/v1/products`, `/v1/carrier-services`	Se acepta, pero estos recursos no tienen modo: el resultado es el mismo
`GET /v1/pickups`	Devuelve `400 LIVE_MODE_REQUIRED`

Qué es solo de producción

Algunas operaciones se rechazan en modo de prueba antes de tocar cualquier recurso:

Fondeo del monedero. Las rutas de Stripe, CLABE, tarjeta, PayPal y OXXO devuelven 400 LIVE_MODE_REQUIRED porque crean o exponen recursos de pago reales. Para saldo de prueba usa el reset de arriba.
Recolecciones. Programar, listar, consultar, cancelar y refrescar responden 400 LIVE_MODE_REQUIRED. La única excepción es GET /v1/pickups/carriers, que solo devuelve capacidades y no distingue modo.
Rastreo público. Los tokens de prueba nunca resuelven en la página pública.

Qué se comparte entre modos

Las direcciones, los paquetes guardados y los códigos postales son recursos compartidos. Al crear un envío de prueba puedes usar cualquier dirección guardada, sin importar en qué modo se creó. La configuración de la organización, los miembros y las invitaciones también se comparten.