01 / Guía
Cuándo necesitas registrar un tracker
Registra un tracker únicamente cuando la guía fue creada fuera de SendIt y quieres incorporarla a tu seguimiento. Las guías compradas en SendIt ya reciben rastreo automáticamente y no consumen la cuota de trackers externos.
Un tracker observa el recorrido de una guía existente. No compra otra guía, no modifica el destino y no reemplaza el envío original.
| Origen de la guía | Cómo empieza el rastreo | Evento de actualización |
|---|---|---|
| Comprada en SendIt | El rastreo se crea automáticamente | shipment.tracking.updated |
| Creada en otro sistema | Registras POST /v1/trackers | tracker.updated |
02 / Guía
Prepara tres datos y evita contexto innecesario
El número de rastreo es obligatorio. carrier funciona como una pista opcional cuando el formato identifica claramente a la paquetería; si el número es ambiguo, debes enviar esa pista de forma explícita.
metadata te permite guardar una referencia como el identificador del pedido. SendIt la devuelve sin interpretarla, por lo que conviene mantenerla pequeña y no incluir datos personales, llaves o información sensible.
trackingNumber: número exacto de la guía externa.
carrier: pista opcional; necesaria cuando el número es ambiguo.
metadata.orderId: referencia de tu sistema para conciliar el pedido.
Una guía de una paquetería no disponible para seguimiento devuelve un error claro.
03 / Guía
Registra la guía externa con la API
POST /v1/trackers crea el seguimiento sin crear un envío nuevo. El ejemplo usa una llave de prueba para validar el contrato sin consumir cuota ni generar un excedente.
El tracker comienza en UNKNOWN con un historial vacío. Cuando llega la primera actualización, el estado y events[] empiezan a reflejar el recorrido disponible.
POST /v1/trackers
X-API-Key: sk_test_...
Content-Type: application/json
{
"trackingNumber": "1234567890123456",
"carrier": "DHL",
"metadata": {
"orderId": "ORD-2026-001"
}
}04 / Guía
Un reintento no debe crear un segundo seguimiento
Si registras el mismo número y paquetería dentro de tu organización y ya existe un tracker activo de los últimos tres meses, SendIt devuelve el existente con meta.deduplicated: true. Ese registro repetido no vuelve a consumir cuota ni genera otro cargo.
Por esa deduplicación, POST /v1/trackers puede reintentarse sin Idempotency-Key. El encabezado sigue siendo opcional y también se respeta si tu integración decide incluirlo.
05 / Guía
Traduce los estados una sola vez
Las paqueterías pueden describir el mismo momento con palabras distintas. El tracker lo presenta mediante un recorrido común para que tu ecommerce aplique una sola regla por etapa.
| Estado | Qué significa | Acción útil |
|---|---|---|
| UNKNOWN | Todavía no existe información suficiente. | Muestra que el seguimiento está pendiente sin inventar una ubicación. |
| PRE_TRANSIT | La guía existe, pero aún no hay movimiento confirmado. | Evita comunicar que la paquetería ya recibió el paquete. |
| IN_TRANSIT | El paquete avanza dentro de la red. | Actualiza el pedido y conserva el último evento. |
| OUT_FOR_DELIVERY | El paquete salió a reparto. | Prepara la comunicación de entrega final. |
| DELIVERED | La entrega terminó correctamente. | Cierra el seguimiento una sola vez. |
| RETURNED | El paquete terminó su recorrido de regreso. | Relaciona el resultado con el proceso de devolución. |
| FAILED | El recorrido terminó sin una entrega correcta. | Envía el caso a revisión operativa. |
06 / Guía
No toda incidencia cambia el estado principal
Un intento fallido, una retención o un daño puede aparecer dentro de events[] con isException: true sin cambiar inmediatamente el estado general. Revisa ambos niveles: el estado responde dónde está el recorrido; el evento explica qué requiere atención.
No marques FAILED por cualquier evento con isException.
Muestra el último evento con lenguaje comprensible.
Conserva occurredAt y la ubicación disponible sin completar datos ausentes.
Define qué excepciones abren una tarea para tu equipo.
07 / Guía
Recibe cambios por webhook y consulta el historial
Suscribe tu endpoint a tracker.created, tracker.updated y tracker.expired. No existe un evento separado para entrega o falla: lee data.object.status dentro de tracker.updated y evita procesar dos veces el mismo id de evento.
GET /v1/trackers/:id devuelve el estado actual y el historial completo. Úsalo para conciliar cuando tu receptor estuvo fuera de línea o una decisión necesita confirmar el dato más reciente.
- 01
Registras
Creas el tracker con número, pista de paquetería y referencia del pedido.
- 02
Se actualiza
SendIt incorpora el nuevo evento y normaliza el estado.
- 03
Recibes el webhook
Tu endpoint verifica firma, modo e identificador.
- 04
Actualizas el pedido
Tu sistema aplica una transición sin duplicar efectos.
- 05
Reconcilias
Consultas el tracker cuando necesitas confirmar el historial actual.
08 / Guía
Cuándo deja de consultarse una guía externa
Un tracker se finaliza cuando llega a DELIVERED, RETURNED o FAILED. También puede expirar después de 45 días sin salir de PRE_TRANSIT o 60 días sin recibir un evento nuevo. El registro permanece disponible para consulta, pero deja de buscar actualizaciones.
DELETE /v1/trackers/:id detiene permanentemente un tracker externo. Esa acción es irreversible y no sirve para anular una guía comprada en SendIt.
09 / Guía
Qué trackers cuentan dentro de tu plan
Solo las guías externas que registras consumen la cuota mensual. Las guías compradas en SendIt incluyen su seguimiento automáticamente, mientras que los trackers creados con una llave sk_test_ no consumen cuota ni generan excedente.
| Plan | Trackers incluidos al mes | Tracker adicional |
|---|---|---|
| Free | 100 | $0.80 MXN |
| Growth | 2,000 | $0.50 MXN |
| Scale | 10,000 | $0.30 MXN |
| Enterprise | Cuota acordada | Según la operación |
10 / Guía
Checklist para incorporar una nueva fuente de guías
Prueba una sola fuente antes de importar todo el historial. Cuando número, paquetería, pedido y eventos se relacionan correctamente, repite el mismo contrato para el siguiente canal.
11 / Guía
Una sola vista aunque la guía nazca en otro lugar
SendIt permite reunir guías propias y externas bajo un seguimiento común, con historial y webhooks para conectar el estado con tu ecommerce o sistema.
La API de trackers está disponible en beta y su contrato puede evolucionar antes de v1 estable. La plataforma está en pre-lanzamiento; puedes validar el flujo con una llave de prueba antes de registrar guías reales.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿Necesito registrar las guías que compro en SendIt?
No. Esas guías reciben rastreo automáticamente y no consumen la cuota de trackers externos.
¿El carrier es obligatorio al registrar un tracker?
No siempre. Es una pista opcional cuando el número identifica una opción sin ambigüedad; si el formato puede pertenecer a más de una paquetería, debes enviarlo.
¿Qué pasa si registro dos veces el mismo número?
Si ya existe un tracker activo del mismo número y paquetería en tu organización dentro de los últimos tres meses, recibes el existente sin volver a consumir cuota ni generar otro cargo.
¿Una incidencia siempre cambia el tracker a FAILED?
No. Un evento puede llevar isException: true sin cambiar el estado principal. FAILED se utiliza cuando el recorrido termina sin una entrega correcta.
¿Cómo sé que una guía externa fue entregada?
Recibes tracker.updated y lees DELIVERED en data.object.status. También puedes consultar GET /v1/trackers/:id para confirmar el estado actual.
¿Puedo probar trackers externos sin consumir la cuota?
Sí. Los trackers creados con una llave sk_test_ no consumen la cuota mensual ni generan excedente.