Ir al contenido
SShalom API

Ubicaciones (ubigeos)

Obtén los departamentos, provincias y distritos del Perú donde Shalom tiene agencias, con sus IDs, para armar selectores de dirección en tu checkout.

Las ubicaciones se arman a partir del catálogo de agencias: departamento, provincia y distrito, cada uno con su ID. Sirven para llenar los selectores de dirección de tu checkout solo con las zonas donde Shalom tiene agencias.

Se consultan en cascada

Primero pides los departamentos, después las provincias de un departamento y después los distritos de una provincia, con los id que devuelve cada nivel. Como salen del catálogo de agencias, que se refresca cada 3 horas, cambian poco y puedes guardarlas de tu lado.

No confundas ubicación con agencia

La ubicación es la división territorial; la agencia es el punto físico donde se despacha o se recoge. Para armar la dirección del cliente usas la ubicación; para crear la guía necesitas el ter_id de la agencia (ver Agencias y cobertura).

Listar departamentos

GET /locations/departments

Departamentos del Perú con al menos una agencia de Shalom, ordenados por nombre. Consume 1 operación.

curl -X GET "https://api.shalom-api.lat/locations/departments" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "items": [
    { "id": 1, "name": "AMAZONAS", "ubi_id": 101 },
    { "id": 15, "name": "LIMA", "ubi_id": 1501 }
  ]
}
En los departamentos, ubi_id es id × 100 más el ID de su provincia más baja con agencia; no es el código INEI de 2 dígitos. Usa id para pedir sus provincias.

Listar provincias de un departamento

GET /locations/departments/{depId}/provinces

Provincias del departamento con al menos una agencia de Shalom, ordenadas por nombre. Consume 1 operación.

ParámetroRequeridoDescripción
{depId}SíID del departamento (entero), ej. 15.
curl -X GET "https://api.shalom-api.lat/locations/departments/15/provinces" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "items": [
    { "id": 2, "name": "BARRANCA", "ubi_id": 1502 },
    { "id": 5, "name": "CAÑETE", "ubi_id": 1505 }
  ]
}

Listar distritos de una provincia

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

Distritos (zonas) de la provincia con al menos una agencia de Shalom, ordenados por nombre. Consume 1 operación.

ParámetroRequeridoDescripción
{depId}SíID del departamento (entero).
{provId}SíID de la provincia (entero), ej. 1.
curl -X GET "https://api.shalom-api.lat/locations/departments/15/provinces/1/districts" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "items": [
    { "id": 2, "name": "ANCON", "ubi_id": 150102 },
    { "id": 3, "name": "ATE-VITARTE", "ubi_id": 150103 }
  ]
}

Errores

CódigoSignificado
400depId o provId no es un número entero.
404No hay agencias en ese departamento o en esa provincia (o el ID no existe).

Preguntas frecuentes

Relacionado