Documentación del API

Autenticación con X-API-Key

Toda llamada lleva tu key en la cabecera X-API-Key. Cada key va con un plan —Gratuito, Básico, Plus o Premium—. La del Gratuito se emite sola desde la web; las de pago se contratan por correo.

curl -H "X-API-Key: $API_KEY" \
  "https://api.tracking-peru.com/v1/carriers"

La key identifica y contabiliza: no la pongas en un cliente que se descargue al navegador o a una app, porque ahí queda publicada y la gasta cualquiera. Va del lado de tu servidor.

Cupos por plan

Tu key trae el cupo del plan con el que se emitió. El límite por minuto es un guardarraíl contra ráfagas, no una cuota mensual: el tope de consultas al mes se cuenta aparte. La key se entrega en la misma respuesta del alta.

Tu primer llamado al API

GET /v1/carriers es el endpoint de descubrimiento y conviene que sea la primera llamada que escribas: dice qué couriers hay, qué puede cada uno y cuánta evidencia respalda cada integración. Tu código puede leer ese estado en vez de confiar en esta página — que es exactamente lo que recomendamos, porque el API se entera antes.

Convenciones del API

Cinco reglas que valen para todas las respuestas. Ninguna es cosmética: cambian cómo escribes el cliente.

Todo en inglés, snake_case

Nombres de campo y valores. Alguien que no habla español tiene que poder parsear el contrato, y tiene que ser el mismo para los cinco couriers.

La zona horaria va explícita

Cada fecha de un evento lleva su desplazamiento (-05:00). Ningún courier lo manda: lo ponemos nosotros, porque una fecha sin zona es una fecha que cada cliente interpreta distinto.

El literal del courier siempre viaja

Junto al estado canónico va status_raw con la palabra exacta que devolvió el courier. Normalizar no debería significar perder el dato original: si nuestro mapeo te parece mal, tienes con qué discutirlo.

unknown es un valor posible, y tu código tiene que aceptarlo

El vocabulario de estados de un courier no está mapeado al 100 %, y uno puede devolver mañana un código que nunca vimos. En ese caso el estado llega como unknown con el literal original en status_raw — no aproximado al canónico más parecido. Un switch sin rama por defecto se va a romper ahí, y es el único lugar donde lo va a hacer.

Los documentos de identidad no salen nunca

Varios couriers exponen el DNI de quien recibió en endpoints públicos. Ningún carrier lo reenvía —provides.party_documents es false en los cinco— y donde el crudo lo traía se limpia antes de servirse, así que pedirlo con include=raw tampoco lo trae. Los nombres de remitente y destinatario sí llegan en los couriers que ya los publicaban. Consulta provides.parties en GET /v1/carriers antes de asumir, y trátalos como datos personales.

POST/v1/shipments

Crea una guía con el courier. Un cuerpo canónico para todos.

El mismo cuerpo sirve para todos los couriers. Lo que sólo pide uno va en carrier_options, y su esquema se publica en GET /v1/carriers.

{
  "carrier": "olva",
  "service": { "delivery": "agency" },
  "origin": { "agency_id": "hq:12" },
  "destination": { "agency_id": "161" },
  "sender": {
    "name": "Tu Tienda SAC",
    "document": { "type": "ruc", "number": "20xxxxxxxxx" },
    "phone": "999999999"
  },
  "receiver": {
    "name": "Ana Quispe",
    "document": { "type": "dni", "number": "0xxxxxxx" },
    "phone": "988888888"
  },
  "parcels": [
    { "weight_kg": 1.2, "content": { "category": "ropa" }, "declared_value": 120 }
  ],
  "payer": "receiver"
}

{
  "id": "shp_01K...",
  "carrier": "olva",
  "status": "pending_payment",
  "tracking": { "number": "2431838-26" },
  "parcels": [{ "index": 0, "tracking_number": "2431838-26", "url": "…/label" }],
  "payment_instructions": "Se paga en destino al recoger."
}

POST/v1/shipments/quote

Cuánto cuesta antes de crearla. Sin efectos.

Cotizar no crea nada ni consume cupo de órdenes.

{
  "carrier": "olva",
  "service": { "delivery": "agency" },
  "origin": { "ubigeo": "150101" },
  "destination": { "ubigeo": "110101" },
  "parcels": [{ "weight_kg": 1 }]
}

{
  "carrier": "olva",
  "amount": 8.00,
  "currency": "PEN",
  "delivery": "agency"
}

GET/v1/carriers

Qué carriers hay, qué puede cada uno y cuánta evidencia lo respalda.

Es el endpoint de descubrimiento: tu código puede leer el estado en vez de confiar en esta página.

{
  "carriers": [
    {
      "id": "marvisur",
      "name": "Expreso Marvisur",
      "enabled": true,
      "verified": {
        "level": "live",
        "last_probe": "2026-08-03T22:10:23Z",
        "notes": "hit y miss reproducidos byte a byte contra el upstream"
      },
      "id_format": "V###-####### (serie V + 3 dígitos, distinto de V000)",
      "examples": ["V999-9999999"],
      "detection": "strong",
      "requires_code": false,
      "requires_end_user_auth": false,
      "anonymous_timeline": true,
      "provides": {
        "parties": true, "event_location": true,
        "packages": true, "payment_status": true
      }
    }
  ]
}

GET/v1/tracking

Rastreo unificado por número de guía.

Cada evento trae los tres: status (canónico), status_raw (el literal del courier) y carrier_code (su código, si hay) — normalizar no significa perder el dato original. Y para saber si un envío TERMINÓ usa los bools terminal/delivered, no el nombre: available_for_pickup no es entrega, y una devolución también es terminal. Segundo factor: algunos carriers piden además el código de orden — pásalo como &code=<código>. Es OBLIGATORIO en los que declaran requires_code en GET /v1/carriers (hoy Shalom: sin él responde 422) y se ignora en el resto.

{
  "carrier": "marvisur",
  "tracking_number": "V001-0000001",
  "status": "delivered",
  "status_raw": "ENTREGADO",
  "delivered": true,
  "terminal": true,
  "events": [
    {
      "seq": 0,
      "status": "registered",
      "status_raw": "RECEPCION",
      "carrier_code": "0",
      "description": "SU ENVÍO FUÉ RECEPCIONADO EN NUESTRA SEDE",
      "occurred_at": "2023-07-01T07:54:06-05:00",
      "time_precision": "second",
      "location": { "name": "GARCI CARBAJAL", "structured": false }
    }
  ],
  "detail": "full",
  "fetched_at": "2026-08-03T22:10:31Z"
}

GET/v1/tracking/{carrier}/{number}

La misma consulta con el carrier en la ruta.

Idéntica respuesta. Existe porque un carrier explícito en la ruta se cachea y se loguea mejor que un query param.

{
  "carrier": "marvisur",
  "tracking_number": "V001-0000001",
  "status": "delivered",
  "status_raw": "ENTREGADO",
  "delivered": true,
  "terminal": true,
  "events": [
    {
      "seq": 0,
      "status": "registered",
      "status_raw": "RECEPCION",
      "carrier_code": "0",
      "description": "SU ENVÍO FUÉ RECEPCIONADO EN NUESTRA SEDE",
      "occurred_at": "2023-07-01T07:54:06-05:00",
      "time_precision": "second",
      "location": { "name": "GARCI CARBAJAL", "structured": false }
    }
  ],
  "detail": "full",
  "fetched_at": "2026-08-03T22:10:31Z"
}

POST/v1/tracking/batch

Hasta 50 envíos por request, con error por ítem.

Responde 200 aunque haya ítems fallidos: el error va por ítem. Aquí no hay detección automática.

{
  "items": [
    { "custom_id": "a", "carrier": "marvisur", "number": "V001-0000001" },
    { "custom_id": "b", "carrier": "marvisur", "number": "V999-9999999" }
  ]
}

{
  "results": [
    { "custom_id": "a", "carrier": "marvisur",
      "number": "V001-0000001",
      "ok": true, "shipment": { "…": "el Shipment completo" } },
    { "custom_id": "b", "carrier": "marvisur",
      "number": "V999-9999999",
      "ok": false,
      "error": {
        "code": "not_found",
        "message": "no se encontró el envío"
      } }
  ],
  "summary": { "total": 2, "ok": 1, "failed": 1 }
}

GET/v1/agencies

Catálogo de agencias con filtros y paginación.

ubigeo_source es lo que hace auditable el join: "carrier" lo dio el courier, "matched" lo resolvimos por texto y puede fallar.

{
  "agencies": [
    {
      "carrier": "olva",
      "id": "948",
      "name": "AGENTE OLVA MIRAFLORES - BENAVIDES C18",
      "location": {
        "address": "AV ALFREDO BENAVIDES NRO 1851",
        "department": "LIMA", "province": "LIMA",
        "district": "MIRAFLORES",
        "ubigeo": "150122", "structured": true
      },
      "ubigeo_level": "district",
      "ubigeo_source": "carrier",
      "geo": { "lat": -12.1265813, "lng": -77.0132440 },
      "hours": {
        "weekly": [
          { "weekday": 1,
            "spans": [ { "open": "08:00", "close": "20:00" } ] }
        ],
        "structured": true,
        "time_zone": "America/Lima"
      },
      "kind": "agent",
      "services": { "dropoff": true, "pickup": true },
      "synced_at": "2026-08-03T22:10:19Z"
    }
  ],
  "pagination": {
    "page": 1, "per_page": 20, "total": 417, "total_pages": 21
  },
  "meta": { "sources": [ "…frescura por carrier" ] }
}

GET/v1/coverage

Qué carriers tienen agencia en un distrito. Distingue "no cubre" de "no sabemos".

Solo un courier que publica distrito puede recibir un "no cubre". El que da su ubicación como texto libre cae en "unknown", con el motivo escrito.

{
  "ubigeo": "150101",
  "level": "district",
  "carriers": [
    { "carrier": "olva", "count": 5, "kinds": { "agent": 5 } }
  ],
  "not_covered": [],
  "unknown": [
    {
      "carrier": "marvisur",
      "reason": "el catálogo de este carrier no resuelve a nivel
                 district; la consulta pide ese nivel"
    }
  ]
}

GET/v1/agencies/{carrier}/{id}

Detalle de una agencia.

Devuelve la Agency pelada, sin envoltorio. La PK natural es el par (carrier, id).

{
  "carrier": "olva",
  "id": "579",
  "name": "TIENDA CHACHAPOYAS",
  "location": {
    "address": "JR. AMAZONAS 1120",
    "department": "AMAZONAS", "province": "CHACHAPOYAS",
    "district": "CHACHAPOYAS",
    "ubigeo": "010101", "structured": true
  },
  "ubigeo_level": "district",
  "ubigeo_source": "carrier",
  "kind": "office",
  "services": { "dropoff": true, "pickup": true },
  "synced_at": "2026-08-03T22:10:19Z"
}

POST/v1/webhooks

Registra tu endpoint. Devuelve el signing secret una sola vez.

Se guarda deshabilitado y recibe un ping firmado: solo se habilita si devuelves el challenge como cuerpo.

{ "url": "https://tuservicio.com/hooks/tracking" }

{
  "webhook": {
    "id": 11,
    "url": "https://tuservicio.com/hooks/tracking",
    "enabled": true,
    "created_at": "2026-08-04T10:00:00Z"
  },
  "signing_secret": "9f2b…64 hex…c1",
  "verified": true,
  "usage": { "active_subscriptions": 0, "max_subscriptions": 50 }
}

POST/v1/tracking/subscriptions

Suscribe un envío: te avisamos cuando cambie de estado.

carrier es OBLIGATORIO: no hay detección automática. Un rastreo mal detectado se ve en la respuesta; una suscripción mal detectada no la mira nadie durante semanas. El code es el 2º factor (código de orden): obligatorio para los carriers con requires_code como Shalom, opcional para el resto.

{
  "carrier": "marvisur",
  "number": "V001-0000001",
  "code": "2º factor — requerido si el carrier declara requires_code"
}

{
  "subscription": {
    "id": 4821,
    "carrier": "marvisur",
    "tracking_number": "V001-0000001",
    "status": "active",
    "next_poll_at": "2026-08-04T10:16:00Z",
    "created_at": "2026-08-04T10:00:00Z",
    "expires_at": "2026-08-25T10:00:00Z"
  },
  "outcome": "created",
  "usage": { "active_subscriptions": 8, "max_subscriptions": 50 }
}

Los estados que se salen del camino

delayed

Sigue en curso, solo que tarde.

returning

Vuelve al origen. No es terminal: todavía puede entregarse.

returned

Volvió y quedó ahí.

exception

Algo que el courier reporta y no encaja en ningún otro estado.

Carriers y su nivel de verificación

Ninguno de estos APIs es oficial: cada adaptador se construyó leyendo cómo funciona el courier, así que la calidad de la evidencia varía. Cada carrier publica la suya en verified.level, para que distingas «implementado» de «probado contra el sistema real».

live

Verificado en vivo

Respuestas reales capturadas contra el upstream, con hit y miss.

code_derived

Derivado de código

Extraído de una integración que corre en producción, sin captura de tráfico.

contract_only

Solo contrato

El contrato está verificado, pero nunca obtuvimos una respuesta con datos.

none

Sin adaptador

No hay integración escrita.

Tipos de evento de webhook

tracking.updated

El envío cambió de estado y sigue en curso.

tracking.delivered

Se entregó. Es el único terminal con tipo propio: una devolución también es terminal, pero no es una entrega.

tracking.expired

Venció el TTL de la suscripción sin que el envío terminara. Se avisa en vez de callarse: «no pasó nada» y «dejamos de mirar» no son lo mismo.

webhook.ping

Verificación de propiedad al registrar el endpoint.

Verificar la firma

Cada entrega de webhook va firmada con el secreto que te devolvemos una sola vez al registrar el endpoint. Compara usando una función de tiempo constante y sobre el cuerpo crudo: si lo parseas y lo vuelves a serializar antes de firmar, la firma no va a coincidir.

X-Webhook-Signature: t=<unix>,v1=<hex>

v1 = HMAC-SHA256("<t>" + "." + <cuerpo crudo>, signing_secret)

Una entrega real de webhook

POST /hooks/tracking HTTP/1.1
User-Agent: tracking-peru-webhooks/1
X-Webhook-Event: tracking.updated
X-Webhook-Event-Id: evt_4821_tracking.updated_v1-1010100000000
X-Webhook-Attempt: 1
X-Webhook-Signature: t=1785578400,v1=6f1a…

{
  "id": "evt_4821_tracking.updated_v1-1010100000000",
  "event": "tracking.updated",
  "occurred_at": "2026-08-04T14:02:11Z",
  "data": {
    "subscription_id": 4821,
    "carrier": "marvisur",
    "tracking_number": "V001-0000001",
    "status": "at_destination",
    "previous_status": "in_transit",
    "delivered": false,
    "terminal": false,
    "change": { "appeared": ["at_destination"] },
    "shipment": { "…": "el Shipment completo, con su timeline" }
  }
}

Antes de escribir el receptor de webhooks

Recibir webhooks no es sólo exponer un endpoint. Estas no son features: son decisiones que cambian tu código.

Se avisa por cambio de estado, no por escaneo

Tres ciudades y tres eventos in_transit son un solo webhook. El payload trae el timeline completo igual, así que no pierdes nada y no recibes un feed.

Verify-before-enable

Tu endpoint se guarda deshabilitado y recibe un webhook.ping firmado. Solo se habilita si respondes 2xx devolviendo el challenge como cuerpo — a propósito: eso prueba que del otro lado hay un receptor y no un reflector.

El código de rastreo y la PII no viajan

El segundo factor es credencial y ya lo tienes. Remitente, destinatario y contenido del bulto son datos de terceros y se quedan afuera del POST a tu servidor.

Reintentos con id de evento estable

Hasta 3 intentos por entrega (10 s de timeout, backoff de 500 ms). Si fallan, la marca de agua no avanza y el próximo poll reintenta el mismo cambio con el mismo id. Deduplica por X-Webhook-Event-Id. Y la firma lleva un timestamp (t=<unix>) DENTRO de lo firmado: verifica que sea reciente para rechazar reenvíos viejos (anti-replay).

Cadencia atada al TTL del cache

El poller nunca consulta más rápido que el cache: pedir 1 minuto cuando el TTL es de 10 daría diez lecturas idénticas. Se corrige solo y queda en el log.

Solo HTTPS, y se revalida en cada entrega

La URL se valida contra SSRF al registrar y la IP real se vuelve a chequear al conectar, contra DNS rebinding. No se siguen redirects.