Documentacion.

API REST para consultar tracking de envios, agencias y ubicaciones de shalom.com.pe.

Auth

X-API-Key

Rate limit

60 / min

Formato

JSON

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

Autenticacion

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

X-API-Key: tu-api-key

Solicita tu API key para empezar a usar la API.

Errores

Estructura consistente en todos los errores:

 {
  "error": {
    "code": "not_found",
    "message": "orden no existe",
    "request_id": "01JXZ..."
  }
} 

HTTP	code	Descripcion
400	bad_request	Parametros faltantes o invalidos
401	unauthorized	API key invalida o ausente
403	forbidden	Sin permisos
404	not_found	Recurso no existe
422	upstream_rejected	Upstream rechazo la solicitud
429	rate_limited	Rate limit excedido
502	upstream_unavailable	Upstream no disponible
504	upstream_timeout	Timeout
500	internal	Error interno

Rate Limits

Limite por defecto: 60 requests por minuto por API key.

 X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1713200060 

GET/v1/tracking

Busca una orden y retorna orden + estados en paralelo.

Query params (al menos 1 requerido)

Param	Tipo	Descripcion
numero	string	Numero de orden
codigo	string	Codigo de orden
ose_id	string	ID interno de la orden

Request

curl -H "X-API-Key: mi-key" \
  https://api.shalom-api-peru.com/v1/tracking?numero=0123456789

 200 OK  
 {
  "order": {
    "ose_id": 584210,
    "numero_orden": "0123456789",
    "entregado": true,
    "origen": { "nombre": "LIMA" },
    "destino": { "nombre": "AREQUIPA" }
  },
  "status": {
    "origen":    { "fecha": "15/04/2026", "hora": "09:30" },
    "entregado": { "fecha": "16/04/2026", "hora": "11:40" }
  }
} 

GET/v1/tracking/{ose_id}/events

Hitos del envio: origen, transito, demora, destino, entregado, reparto.

Path	Tipo	Descripcion
ose_id	string	ID de la orden

 200 OK  
 {
  "origen":    { "fecha": "15/04/2026", "hora": "09:30", "descripcion": "Recibido en agencia origen" },
  "transito":  { "fecha": "15/04/2026", "hora": "14:20", "descripcion": "En viaje" },
  "demora":    null,
  "destino":   { "fecha": "16/04/2026", "hora": "08:15", "descripcion": "Llego a destino" },
  "entregado": { "fecha": "16/04/2026", "hora": "11:40", "descripcion": "Entregado al destinatario" },
  "reparto":   null
} 

GET/v1/tracking/{ose_id}/voucher

Comprobante de la orden. Retorna 404 si no tiene comprobante emitido.

GET/v1/tracking/{ose_id}/grt

Enlace a la Guia de Remision del Transportista.

Param	En	Descripcion
ose_id	path	ID de la orden
cap_id	query	ID del capitulo (requerido)

 {
  "enlace": "https://..."
} 

GET/v1/agencies

Lista paginada de agencias.

Param	Default	Descripcion
page	1	Pagina
per_page	100	Items por pagina (max 500)

 200 OK  
 {
  "page": 1,
  "per_page": 100,
  "items": [
    {
      "id": 1,
      "nombre": "LIMA CENTRO",
      "departamento": "LIMA",
      "aereo": true,
      "latitud": -12.046,
      "longitud": -77.030
    }
  ]
} 

GET/v1/agencies/search

Busca por texto y/o filtros de ubicacion.

Param	Tipo	Descripcion
q	string	Texto libre
departamento	string	Filtrar por depto
provincia	string	Filtrar por provincia
aereo	bool	Servicio aereo

GET/v1/agencies/{id}

Detalle completo de una agencia por ID numerico.

GET/v1/locations/departments

Todos los departamentos del Peru.

 {
  "items": [
    { "id": 1, "name": "AMAZONAS", "ubi_id": 101 }
  ]
} 

GET/v1/locations/departments/{depId}/provinces

Provincias de un departamento.

Path	Descripcion
depId	ID del departamento (int)

GET/v1/locations/departments/{depId}/provinces/{provId}/districts

Distritos de una provincia.

Path	Descripcion
depId	ID del departamento
provId	ID de la provincia

Health Checks

Publicos, sin auth.

GET/healthz

Liveness. 200 si el servidor esta vivo.

GET/readyz

Readiness. 200 cuando esta listo para recibir trafico.