01 / Guía
Qué cambia entre prueba y producción
SendIt usa la misma API para ambos modos. La llave determina el entorno: sk_test_ trabaja con recursos de prueba y sk_live_ con la operación real. No necesitas cambiar de host ni agregar un parámetro para activar el sandbox.
Los recursos de prueba permanecen separados de los reales. Una llave de prueba no puede leer ni modificar un envío de producción, aunque conozca su identificador.
| Elemento | Modo de prueba | Producción |
|---|---|---|
| Llave | Comienza con sk_test_ | Comienza con sk_live_ |
| Saldo | $10,000 MXN virtuales, sin tarjeta | Saldo real de la cuenta |
| Guías y rastreo | Documentos y números identificables como prueba | Operación real del envío |
| Datos | Aislados de los recursos reales | Pedidos y envíos reales |
| Webhooks | Incluyen livemode: false | Incluyen livemode: true |
02 / Guía
Diseña los casos antes de escribir pruebas
Convierte el recorrido del pedido en escenarios observables. Cada caso debe tener una entrada conocida, una respuesta esperada y una condición clara para decidir si pasó o falló.
Camino principal: cotizar, elegir, comprar la guía y guardar el rastreo.
Datos inválidos: dirección o paquete incompleto sin crear un pedido inconsistente.
Reintento: repetir una compra interrumpida sin generar una segunda guía.
Seguimiento: recorrer los estados que ve el cliente hasta la entrega.
Excepciones: recibir una falla o un retorno sin marcar el pedido como entregado.
Webhook: verificar firma, duplicados, modo y estado antes de actualizar tu sistema.
03 / Guía
Separa las credenciales, los datos y sus efectos
Guarda las llaves de prueba y producción en secretos distintos y úsalas únicamente desde tu servidor. No incluyas una llave en el navegador, una aplicación móvil, un repositorio o una captura de pantalla.
Haz que tu integración lea livemode y el modo del recurso antes de actualizar un pedido. Esa comprobación impide que una prueba de rastreo cambie el estado, inventario o comunicación de una venta real.
Variables de entorno distintas para sk_test_ y sk_live_.
Pedidos de prueba reconocibles en tu propio sistema.
Webhooks de prueba sin efectos comerciales reales.
Registro del shipmentId, trackingNumber y referencia del pedido en el mismo modo.
04 / Guía
Recorre el ciclo completo, no solo la compra
Empieza con el tutorial de la primera guía para crear el envío, recibir rates[] y comprar con POST /v1/shipments/:id/label. Después avanza el envío de prueba una etapa por solicitud.
POST /v1/shipments/:id/test/advance-status funciona únicamente con un envío de prueba. Cada llamada devuelve el nuevo estado y produce el evento correspondiente para que puedas revisar tu interfaz y automatizaciones.
- 01
Guía comprada
Confirma documento, total, shipmentId y trackingNumber.
- 02
Lista para recolección
Muestra que el paquete está preparado para continuar.
- 03
Recolectado
Registra que el paquete inició su recorrido.
- 04
En tránsito
Actualiza el pedido sin asumir que ya se entregó.
- 05
En reparto
Presenta la etapa final con lenguaje claro para el cliente.
- 06
Entregado
Cierra el seguimiento una sola vez y conserva el historial.
POST /v1/shipments/:id/test/advance-status
X-API-Key: sk_test_...05 / Guía
Prueba una falla y un retorno de forma deliberada
En modo de prueba puedes elegir el desenlace desde el nombre de contacto del destinatario. Estos marcadores son exclusivos del sandbox y sirven para comprobar que tu sistema no trata todas las rutas como entregas exitosas.
| Escenario | Dato de prueba | Resultado que debes verificar |
|---|---|---|
| Entrega | Nombre de contacto normal | El pedido llega a DELIVERED y cierra una sola vez. |
| Falla | El nombre contiene SENDIT_FAIL | El pedido llega a FAILED y solicita intervención. |
| Retorno | El nombre contiene SENDIT_RETURN | El pedido llega a RETURNED sin registrarse como entrega. |
06 / Guía
Valida el webhook con el mismo cuidado que la guía
Los eventos de envíos de prueba incluyen livemode: false. Verifica ese valor, la firma y el identificador del evento antes de procesar data.object.status. Tu receptor debe tolerar entregas repetidas sin aplicar dos veces la misma transición.
Responde con éxito después de aceptar el evento y procesa el trabajo de tu negocio sin bloquear la recepción. Conserva el identificador para conciliar un cambio con el envío y el pedido correctos.
{
"id": "evt_...",
"type": "shipment.tracking.updated",
"livemode": false,
"data": {
"object": {
"id": "shp_...",
"mode": "TEST",
"status": "IN_TRANSIT"
}
}
}07 / Guía
Incluye redes lentas, respuestas parciales y límites
Una integración real debe decidir qué repetir y qué corregir. Usa Idempotency-Key de forma opcional en compras que puedan reintentarse, conserva el mismo valor para la misma operación y genera uno nuevo cuando la intención cambie.
Si recibes 429, respeta Retry-After. Para otros errores, registra el código público, el requestId cuando exista y el shipmentId relacionado; no guardes la llave ni datos personales completos en tus logs.
Reintenta fallas temporales con espera creciente.
No reintentes datos inválidos sin corregir la solicitud.
No construyas rateId ni otros identificadores opacos.
Vuelve a cotizar cuando una opción haya vencido después de 24 horas.
Revisa el historial de solicitudes para relacionar estado, ruta y requestId.
08 / Guía
Una puerta de salida clara hacia producción
Los valores y documentos del sandbox validan el contrato y tu comportamiento, no prometen disponibilidad, total o tiempo de un envío real. Antes de activar sk_live_, cotiza de nuevo con datos reales y revisa el resultado que recibes en producción.
09 / Guía
Prueba el mismo contrato que llevarás a producción
SendIt incluye el acceso completo a la API en todos los planes, también en Free. El modo de prueba comienza con $10,000 MXN virtuales y no solicita tarjeta para recorrer cotización, compra, rastreo y webhooks.
La plataforma está en pre-lanzamiento. Puedes preparar y validar tu integración antes de mover saldo real o entregar un paquete a una paquetería.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿SendIt usa una URL distinta para el sandbox?
No. La llave decide el modo: sk_test_ activa recursos de prueba y sk_live_ la operación real. No agregues un parámetro ni cambies el host para alternarlos.
¿Necesito una tarjeta para probar la API?
No. Cada organización tiene $10,000 MXN de saldo virtual para el modo de prueba.
¿Una llave de prueba puede leer un envío real?
No. Los recursos de prueba y producción están aislados, incluso si la llave conoce el identificador de otro modo.
¿Puedo simular una entrega fallida o un retorno?
Sí. En modo de prueba, SENDIT_FAIL y SENDIT_RETURN dentro del nombre de contacto activan esos recorridos para validar tu respuesta.
¿Puedo usar una guía de prueba para un paquete real?
No. Los documentos y números de prueba sirven únicamente para validar la integración y no mueven un paquete real.
¿Cuándo está lista una integración para producción?
Cuando el camino principal, los reintentos, los límites, entrega, falla, retorno y webhooks pasan con datos aislados y el equipo puede conciliar cada resultado con su pedido.