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/departmentsDepartamentos 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"{
"items": [
{ "id": 1, "name": "AMAZONAS", "ubi_id": 101 },
{ "id": 15, "name": "LIMA", "ubi_id": 1501 }
]
}Listar provincias de un departamento
GET /locations/departments/{depId}/provincesProvincias del departamento con al menos una agencia de Shalom, ordenadas por nombre. Consume 1 operación.
| Parámetro | Requerido | Descripció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"{
"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}/districtsDistritos (zonas) de la provincia con al menos una agencia de Shalom, ordenados por nombre. Consume 1 operación.
| Parámetro | Requerido | Descripció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"{
"items": [
{ "id": 2, "name": "ANCON", "ubi_id": 150102 },
{ "id": 3, "name": "ATE-VITARTE", "ubi_id": 150103 }
]
}Errores
| Código | Significado |
|---|---|
400 | depId o provId no es un número entero. |
404 | No hay agencias en ese departamento o en esa provincia (o el ID no existe). |
Preguntas frecuentes
Porque la lista sale del catálogo de agencias de Shalom. Solo aparecen los departamentos, provincias y distritos donde hay al menos una agencia.
Con GET /locations/departments/{depId}/provinces/{provId}/districts, usando los id que devuelven los niveles anteriores.
No. La guía se crea con el ter_id de la agencia de destino. Los ubigeos sirven para armar y validar la dirección del cliente.
Para la autogestión reparto_domicilio usa GET /shipments/home-delivery/ubigeo, que devuelve los IDs tal como los pide Shalom Pro.