Couriers de Perú · un solo APIREST · JSON · Webhooks HMAC

Crea y rastrea envíos de couriers peruanos con un solo contrato.

Genera la guía, cotiza antes, sigue el envío y recibe el aviso cuando cambia de estado. Una integración para 5 couriers — con el nivel de evidencia de cada uno publicado en el propio API.

Pedir acceso →Ver la API

Etiqueta de rastreoGET /v1/tracking

carrier

marvisur

tracking_number

V001-0000001

status

delivered

status_raw "ENTREGADO"

delivered: true
terminal: true
detail: full

events[0]

registered ← "RECEPCION"

2023-07-01 07:54 -05:00 · GARCI CARBAJAL

Respuesta real, recortada

Couriers relevados: 5
Agencias sincronizadas: 1619
Estados canónicos: 11
Couriers que despachan: 2

IntegradosExpreso MarvisurOlva CourierUrbano ExpressCruz del Sur CargoShalom

01Qué hace

Despacha, rastrea y cobra sin escribir cinco integraciones

Cada courier peruano tiene su propio formato de guía, su propio vocabulario de estados y su propia idea de qué significa «no encontrado». Acá es un solo contrato REST — y te decimos, courier por courier, cuánta evidencia real respalda cada integración.

01POST /v1/shipments
Crear.
Genera la guía con el courier
Un solo cuerpo para todos: origen, destino, quién manda, qué va adentro y quién paga. Devuelve el número de seguimiento y el rótulo listo para imprimir.
2 de 5 couriersOlva Courier · Shalom
02POST /v1/shipments/quote
Cotizar.
Cuánto cuesta, antes de crearla
El precio real del courier para ese origen, destino y peso. No crea nada y no gasta cupo, así que se puede llamar en cada cambio del carrito.
Sin efectosAgencia o domicilio, con el precio de cada uno
03GET /v1/tracking
Rastrear.
Un vocabulario, no cinco
Once estados canónicos con el literal del courier siempre adjunto, timeline ordenado y zona horaria explícita. Normalizar sin perder el dato original.
5 de 5 couriersCon el nivel de evidencia de cada uno publicado
04POST /v1/tracking/subscriptions
Avisar.
O deja que te avise
Suscribes un envío y recibes un POST firmado cuando cambia de estado. Llega el mismo objeto que devuelve la consulta.
Webhooks HMACCon reintentos y deduplicación

NotaLa creación es lo más nuevo y por eso lo más desigual: 2 de los 5 couriers la tienen, y cada uno con su propio nivel de evidencia. Está todo abajo, sin maquillaje.

02Integración

Pregúntale al API, o deja que un webhook te avise

Siempre el mismo Shipment: estado canónico, timeline ordenado con zona horaria explícita, bultos y pago. El literal del courier siempre adjunto en status_raw, porque normalizar no debería significar perder el dato original.

Llamas tú

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.

200 OK · application/json
{
  "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
      }
    }
  ]
}

Llamas tú

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.

200 OK · application/json
{
  "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"
}

Llamas tú

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.

200 OK · ?carrier=olva&ubigeo=150122
{
  "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" ] }
}

Llamas tú

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.

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

201 Created · application/json
{
  "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 }
}

Te llamamos

Te avisamos cuando el envío cambia de estado. Llega el mismo objeto.

Firmado con HMAC, con reintentos y deduplicación. El poller acelera cerca de la entrega y se apaga solo cuando el envío termina.

POST a tu endpoint
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" }
  }
}

Cuatro eventostracking.updatedtracking.deliveredtracking.expiredwebhook.ping

Las 6 reglas del receptor Ver los 11 endpoints en la referencia →

03Cobertura

Qué hace cada courier hoy, sin maquillaje

Cada courier aporta hasta tres cosas: crear guías, rastrear envíos y publicar sus agencias. Los 5 publicados rastrean y publican agencias; 2 crean.

Qué hace hoy cada uno de los 5 couriers peruanos integrados: crear guías, rastrear envíos, publicar su catálogo de agencias, y con cuánta evidencia está verificado cada uno.
Crear	Rastrear	Agencias	Evidencia	Ver detalle
Crearno: No disponible	Rastrearsí: Operativo	Agencias193: Operativo	rastreolivecrearnone	→
Crearsí: Operativo	Rastrearsí: Operativo	Agencias427: Operativo	rastreocontract_onlycrearlive	→
Crearno: No disponible	Rastrearsí: Operativo	Agencias265: Operativo	rastreolivecrearnone	→
Crearno: No disponible	Rastrearsí: Operativo	Agencias180: Operativo	rastreolivecrearnone	→
Crearsí: Operativo	Rastrearsí: Operativo	Agencias554: Operativo	rastreolivecrearcode_derived	→

liveVerificado en vivo
code_derivedDerivado de código
contract_onlySolo contrato
noneSin adaptador

Compara los 5 couriers lado a lado →

04Agencias

Busca una agencia entre las 1619 sincronizadas

El mismo GET /v1/agencies que usarías tú, contra los catálogos de los couriers que publican uno. Cada resultado dice de dónde salió su ubigeo — y cuándo no lo pudimos resolver.

GET/v1/agencies?per_page=6

consultando…

El buscador necesita JavaScript. La misma consulta, sin él:curl "https://api.tracking-peru.com/v1/agencies?carrier=olva&q=miraflores"

05Estados

Un envío, once estados, un solo vocabulario

Cada courier nombra los hitos a su manera y ninguno usa los mismos. Este es el recorrido al que los traducimos —el mismo para los cinco—, con el literal original siempre adjunto en status_raw.

01registered
El courier lo recibió y lo dio de alta.
02at_origin
En la agencia de origen, sin salir todavía.
03in_transit
Viajando entre sedes.
04at_destination
Llegó a la ciudad de destino.
05out_for_deliveryoavailable_for_pickup
Sale a repartir, o queda esperando en agencia.
06delivered
Entregado. No hay estado después de este.

Del literal del courier al estado canónico

Validados contra respuestas reales: 5 de 5 couriers (Expreso Marvisur, Olva Courier, Urbano Express, Cruz del Sur Cargo y Shalom).

marvisur devolvió"RECEPCION"statusregistered

Y 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.

06Precios

Una key, un plan desde S/ 0, sin sorpresas

Los cuatro planes llegan a los mismos endpoints y a los mismos carriers. Lo que cambia es cuántas órdenes creas al mes —ese es el medidor— y cómo te respondemos cuando algo se rompe.

Plan Gratuito

S/0para siempre

sin tarjeta, no vence

Para integrar el rastreo, probarlo en serio y quedarte. No vence.

no incluido

hasta 1.000 al mes

documentación y comunidad

Empezar gratis

Plan Básico

S/39al mes

o S/ 390 al año — 2 meses gratis

La primera operación con envíos todas las semanas.

120

hasta 10.000 al mes

por correo

Contratar por correo

Plan Plus

S/89al mes

o S/ 890 al año — 2 meses gratis

Volumen sostenido y respuesta rápida cuando algo se rompe.

500

120

hasta 50.000 al mes

prioritario

Contratar por correo

Plan Premium

S/249al mes

o S/ 2.490 al año — 2 meses gratis

Picos fuertes, la mayor capacidad publicada y consultas sin tope.

2.000

500

300

sin tope

prioritario

Contratar por correo

Todos los planes incluyen

Todos los carriers — ninguno queda reservado para el plan caro
Todos los endpoints: rastreo, agencias y cobertura por ubigeo
Webhooks firmados con HMAC, con reintentos y deduplicación
Cada carrier con su nivel de evidencia publicado
Los carriers que se vayan completando, sin costo extra

Hoy eso son 5 couriers con rastreo operativo y 5 catálogos de agencias (1619 puntos sincronizados). Los que faltan entran a tu key sin que pagues de nuevo.

Cómo se paga

Los planes pagos se coordinan por correo: el botón abre uno con el plan en el asunto, y te emitimos la key el mismo día. Sin formulario y sin tarjeta guardada.

07Empezar

Empieza gratis con 1.000 consultas al mes, y no vence

Déjanos tu correo y te emitimos la key en el momento. El plan Free no vence y no pide tarjeta: si tu volumen crece, subes de plan cuando quieras. Y si el courier que te importa está en ámbar, dilo — eso prioriza el orden en que se completan.

01Ves la key en pantalla apenas la pides, y además te llega por correo.
02Una key gratuita por dirección de correo. Si esa dirección ya tiene la suya, te lo decimos en el momento.
03El plan Free no vence: no te cobramos, no se renueva sola y no hay nada que cancelar.
04La key gratis trae todo el API: todos los carriers, todos los endpoints y webhooks firmados.

Autenticación: X-API-Key
Formato: JSON · REST
Webhooks: firmados · HMAC

Formulario · Key gratuita

¿Ya tienes cuenta?

Entrar al panel →

¿Un plan pago o algo a medida?

hola@tracking-peru.com