olva API Olva API Perú

Documentación.

API REST para consultar tracking, agencias y ubicaciones de Olva Courier.

Auth

X-API-Key

Rate limit

60 / min

Formato

JSON

Base URL: https://api.olva-api-peru.com

Autenticación

Todas las rutas requieren el header X-API-Key con tu key.

X-API-Key: tu-api-key

Errores

Los errores devuelven un objeto { "error": "..." } junto al código HTTP correspondiente.

Código Descripción
400Parámetro inválido (tracking o año de emisión)
401API Key ausente o inválida
404Recurso no encontrado
429Límite de requests excedido
500 / 502Error interno o al consultar Olva

Rate Limits

Cada API key tiene un límite por defecto de 60 requests por minuto. Si lo superas, recibirás un 429.

Endpoints

Tracking
GET

/v1/tracking/{track}/{year}

Agencias
GET

/v1/agencias
GET

Buscar guía

/v1/tracking/{track}/{year}

Consulta los datos y el estado de una guía por su número de tracking y año de emisión (Solo se permite visualizar de los últimos 4 años).

Path params

track Número de tracking.
year Año de emisión en formato de 2 dígitos (YY).

Ejemplo 

curl https://api.olva-api-peru.com/v1/tracking/12345678/25 \
  -H "X-API-Key: tu-api-key"

Respuesta 200 

{
  "general": {
    "fecha_envio": "01/01/2026",
    "id_envio": "1749XXXX",
    "remitente": "SANCHEZ XXXXX XXXXX",
    "consignado": "VICTOR ALBERTO XXXXX XXXXX",
    "origen": "LIMA",
    "destino": "CARAVELI-AQP"
  },
  "details": [
    ...
  ],
  "realtime": []
}
GET

Listar / Filtrar Agencias

/v1/agencias

Filtra agencias por departamento, tipo de sede, partner o nombre. Resultados paginados.

Query params

cod_depCódigo de departamento de acuerdo a ubigeo (match exacto).
departamentoNombre del departamento (match exacto).
tipoTipo de sede (tiendas, puntos-autorizados, olva-agentes).
partner Filtra entre agencias propias de Olva y puntos autorizados asociados. Valores permitidos: SI o NO.
nombresBúsqueda por prefijo del nombre.
pagePágina, por defecto 1.
limitResultados por página, por defecto 20, máx. 100.

Ejemplo 

curl "https://api.olva-api-peru.com/v1/agencias?departamento=LIMA&limit=10" \
  -H "X-API-Key: tu-api-key"

Respuesta 200 

{
  "total": 42,
  "page": 1,
  "limit": 10,
  "results": [
    {
      "nombres": "...",
      "tipo": "...",
      "ubigeo": "...",
      "cod_dep": "...",
      "departamento": "...",
      "partner": "...",
      "direccion": "...",
      "lng": -77.03,
      "lat": -12.04,
      "horario": "..."
    }
  ]
}

Health Checks

Públicos, sin auth.

GET /healthz

Liveness. 200 si el servidor está activo.

1