Ir al contenido
SShalom API

Agencias y cobertura

Consulta el catálogo de agencias de Shalom por API: listado, búsqueda por texto, departamento, provincia, servicio aéreo y cercanía con coordenadas, y una versión pública sin API key.

El catálogo de agencias se refresca desde Shalom cada 3 horas e incluye dirección, teléfono, horarios, coordenadas y si cada agencia atiende envíos aéreos. Su ter_id es el que se usa como origen y destino al cotizar y al crear guías.

Listado o búsqueda

GET /agencies devuelve el catálogo completo, con un filtro opcional por texto. GET /agencies/search suma filtros por departamento, provincia y servicio aéreo, y el orden por cercanía.

Ordenar por cercanía

Con near=lat,lng el resultado viene ordenado por distancia a ese punto y cada agencia trae distancia_km. Con radius_km recortas el radio. Es lo que necesitas para mostrar la agencia más cercana en tu checkout.

La versión pública no pide key

GET /public/agencies y GET /public/agencies/search responden sin API key. Sirven para ver el formato real antes de integrar y alimentan la demo y el mapa del sitio.

Guarda el ter_id

Para crear un envío necesitas el ter_id de las agencias de origen y destino. Guárdalo junto al pedido al cotizar: así no tienes que volver a buscarlo al registrar la guía.

Listar agencias

GET /agencies

Devuelve el catálogo completo de agencias, sin las listas de rutas aéreas de origen y destino. Consume 1 operación.

ParámetroRequeridoDescripción
qNoTexto para filtrar por departamento, provincia, zona o ter_zona (contiene, sin distinguir mayúsculas).
curl -X GET "https://api.shalom-api.lat/agencies?q=lima" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "message": "Lista de agencias filtrada.",
  "total": 26,
  "query": "lima",
  "data": [
    {
      "ter_id": 392,
      "ter_abrebiatura": "MLGVLL",
      "zona": "CERCADO LIMA",
      "ter_zona": "LIMA OESTE 2",
      "provincia": "LIMA",
      "departamento": "LIMA",
      "latitud": "-12.04638719585",
      "longitud": "-77.049473000003",
      "direccion": "JR. PRESBÍTERO GARCÍA VILLÓN NRO. 560 CERCADO LIMA - LIMA",
      "telefono": "(01) 500 7878",
      "hora_atencion": "LUNES A VIERNES - 8:00 AM A 8:00 PM",
      "hora_domingo": "",
      "estadoAgencia": "ATENDIENDO EN ESTE MOMENTO",
      "nombre": "LIMA / LIMA / CERCADO LIMA / MALVINAS - JR. GARCIA VILLÓN",
      "lugar_over": "MALVINAS - JR. GARCIA VILLÓN",
      "ter_aereo": 1,
      "dep_id": 15,
      "prov_id": 1,
      "dist_id": 1,
      "ubi_id": 150101,
      "...": "más campos del catálogo de Shalom"
    }
  ]
}
Sin q, message es "Lista de agencias minimal." y query llega en null.

Búsqueda avanzada

GET /agencies/search

Filtra por texto libre, departamento, provincia y servicio aéreo, y ordena por cercanía a unas coordenadas. Consume 1 operación.

ParámetroRequeridoDescripción
qNoTexto libre. Busca en departamento, provincia, zona, ter_zona, nombre y dirección.
departamentoNoFiltra por departamento (contiene el texto).
provinciaNoFiltra por provincia (contiene el texto).
aereoNotrue para solo agencias con servicio aéreo (ter_aereo = 1); false para solo terrestres.
nearNoCoordenadas "lat,lng" (ej. -12.046,-77.043). Ordena del más cercano al más lejano y agrega distancia_km.
radius_kmNoRadio máximo en kilómetros. Solo se aplica junto con near.
per_pageNoMáximo de resultados (1 a 500, por defecto 100).
curl -X GET "https://api.shalom-api.lat/agencies/search?near=-12.046,-77.043&radius_km=5&per_page=5" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "total": 26,
  "returned": 5,
  "data": [
    {
      "ter_id": 392,
      "lugar_over": "MALVINAS - JR. GARCIA VILLÓN",
      "departamento": "LIMA",
      "provincia": "LIMA",
      "direccion": "JR. PRESBÍTERO GARCÍA VILLÓN NRO. 560 CERCADO LIMA - LIMA",
      "latitud": "-12.04638719585",
      "longitud": "-77.049473000003",
      "ter_aereo": 1,
      "distancia_km": 0.71,
      "...": "los mismos campos que GET /agencies"
    }
  ]
}
total es la cantidad de resultados antes del límite y returned la que se devolvió. distancia_km solo aparece con near.

Listado público (sin API key)

GET /public/agencies

El mismo listado que GET /agencies, sin API key ni consumo de cuota. Es el que usa la demo del sitio.

ParámetroRequeridoDescripción
qNoTexto para filtrar por departamento, provincia, zona o ter_zona.
curl -X GET "https://api.shalom-api.lat/public/agencies?q=lima" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "message": "Lista de agencias filtrada.",
  "total": 26,
  "query": "lima",
  "data": [ { "ter_id": 392, "...": "misma estructura que GET /agencies" } ]
}

Búsqueda pública (sin API key)

GET /public/agencies/search

La misma búsqueda que GET /agencies/search, con los mismos parámetros, sin API key ni consumo de cuota.

ParámetroRequeridoDescripción
qNoTexto libre.
departamentoNoFiltra por departamento.
provinciaNoFiltra por provincia.
aereoNotrue o false.
nearNoCoordenadas "lat,lng" para ordenar por cercanía.
radius_kmNoRadio máximo en kilómetros (con near).
per_pageNoMáximo de resultados (1 a 500, por defecto 100).
curl -X GET "https://api.shalom-api.lat/public/agencies/search?near=-12.046,-77.043&per_page=5" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "success": true,
  "total": 26,
  "returned": 5,
  "data": [ { "ter_id": 392, "distancia_km": 0.71, "...": "misma estructura que GET /agencies/search" } ]
}

Errores

CódigoSignificado
400near no tiene el formato lat,lng, aereo no es true ni false, o per_page está fuera del rango 1 a 500.
429Superaste el rate limit. En las rutas /public/* el límite se cuenta por IP.
500El catálogo de agencias no está disponible en este momento. Reintenta.

Preguntas frecuentes

Relacionado