Rastreadores

Rastrea guías generadas fuera de SendIt con estados normalizados y webhooks, sin importar la paquetería.

Los rastreadores te dan seguimiento de guías que no se generaron en SendIt. Registra el número de rastreo de cualquier paquetería soportada. Obtienes los mismos estados normalizados, el mismo historial de eventos y los mismos webhooks que en un envío de SendIt.

Las guías compradas en SendIt se rastrean automáticamente y sin costo. Los rastreadores son solo para números externos.

Endpoints

Filtros del listado: search (coincidencia parcial del número de rastreo), status, carrier, origin, isFinalized, createdAfter y createdBefore. También acepta livemode y pagina.

isFinalized acepta true o false. Manda isFinalized=false para ver solo los rastreadores que siguen en consulta activa.

Registra un número externo

Parámetros del cuerpo

curl -X POST https://api.sendit.mx/v1/trackers \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1234567890123456",
    "carrier": "DHL",
    "metadata": { "orderId": "ORD-2026-001" }
  }'

{
  "success": true,
  "data": {
    "id": "trk_a1b2c3d4e5f6",
    "trackingNumber": "1234567890123456",
    "carrier": "DHL",
    "status": "UNKNOWN",
    "events": [],
    "metadata": { "orderId": "ORD-2026-001" },
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

• carrier es opcional. SendIt lo infiere solo cuando el formato identifica una paquetería sin ambigüedad. Si el formato es ambiguo, recibes 400 INVALID_INPUT: vuelve a enviar la petición con la pista carrier.
• Una paquetería no soportada devuelve 422 CARRIER_NOT_SUPPORTED; una que requiere credenciales de cuenta devuelve 422 CARRIER_CREDENTIALS_REQUIRED hasta que configures esa integración.
• La respuesta llega con status: "UNKNOWN" y events vacío. La primera consulta a la paquetería ocurre en el primer minuto. A partir de ahí, cada cambio dispara un webhook tracker.updated.
• metadata se devuelve tal cual, nunca se interpreta.

Los duplicados son gratis

Registrar un número que ya tiene un rastreador activo en tu organización devuelve el rastreador existente con meta.deduplicated: true, y jamás se cobra de nuevo. Aplica al mismo número y paquetería dentro de los últimos 3 meses. Los reintentos de tu cliente siempre son seguros: este endpoint no necesita Idempotency-Key, aunque se respeta si lo envías.

Estados

UNKNOWN → PRE_TRANSIT → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED | RETURNED | FAILED

Los escaneos de excepción (retenciones aduanales, intentos de entrega fallidos, daños) aparecen en events[] con isException: true, sin cambiar necesariamente el estado.

Frecuencia de consulta y finalización

La consulta a la paquetería se adapta al estado: ~6 h antes del primer movimiento, ~2 h en tránsito, ~30 min en reparto, y baja a ~12 h tras 5 días sin escaneos nuevos.

Un rastreador finaliza cuando pasa lo siguiente. Al finalizar, isFinalized es true, la consulta se detiene y el registro sigue consultable:

Webhooks

Suscribe tu endpoint a tracker.created, tracker.updated o tracker.expired. Usan las mismas firmas y reintentos que todos los webhooks de SendIt. No hay eventos separados de entrega o excepción: lee data.object.status dentro de tracker.updated.

Precios

• Solo cuentan los registros externos; las guías de SendIt nunca consumen cuota.
• Al exceder la cuota, el excedente se debita del monedero al registrar (402 INSUFFICIENT_BALANCE si no alcanza). No hay tope duro.
• El monto cobrado se devuelve como overageCharged en el rastreador.

En modo de prueba

Los registros con llave sk_test_ nunca cobran excedente ni consumen cuota. Los rastreadores de prueba avanzan solos hasta DELIVERED con datos simulados, y sus webhooks llevan livemode: false.

Errores