Para qué sirven los ubigeos
Un ubigeo es el código oficial de departamento, provincia o distrito del Perú. Los necesitas para armar formularios de dirección y para que el destino quede bien identificado.
Ubicaciones (ubigeos)
Última actualización: 2026-09-21 · Base URL: https://api.shalom-api.lat
El catálogo de ubicaciones deriva del catálogo de agencias: departamento → provincia → distrito, cada uno con su ID de ubigeo. Útil para llenar selectores de dirección en tu checkout con solo las zonas que Shalom cubre.
GET
/locations/departmentsListar departamentos (Perú)
Obtiene todos los departamentos del Perú con cobertura de Shalom.
curl -X GET "https://api.shalom-api.lat/locations/departments" \
-H "x-api-key: TU_API_KEY"Respuesta (ejemplo)
{
"items": [
{ "id": 1, "name": "AMAZONAS", "ubi_id": 101 },
{ "id": 15, "name": "LIMA", "ubi_id": 1501 }
]
}GET
/locations/departments/{depId}/provincesListar provincias de un departamento
Obtiene todas las provincias pertenecientes al departamento especificado por su ID.
| Parámetro | Descripción |
|---|---|
| {depId}* | ID del departamento (integer), ej. 15. |
curl -X GET "https://api.shalom-api.lat/locations/departments/15/provinces" \
-H "x-api-key: TU_API_KEY"Respuesta (ejemplo)
{
"items": [
{ "id": 2, "name": "BARRANCA", "ubi_id": 1502 },
{ "id": 5, "name": "CAÑETE", "ubi_id": 1505 }
]
}GET
/locations/departments/{depId}/provinces/{provId}/districtsListar distritos de una provincia
Obtiene todos los distritos pertenecientes a la provincia y departamento especificados por sus IDs.
| Parámetro | Descripción |
|---|---|
| {depId}* | ID del departamento (integer). |
| {provId}* | ID de la provincia (integer), ej. 1. |
curl -X GET "https://api.shalom-api.lat/locations/departments/15/provinces/1/districts" \
-H "x-api-key: TU_API_KEY"Respuesta (ejemplo)
{
"items": [
{ "id": 2, "name": "ANCON", "ubi_id": 150102 },
{ "id": 3, "name": "ATE-VITARTE", "ubi_id": 150103 }
]
}Se consultan en cascada
Primero pides los departamentos, después las provincias de un departamento y después los distritos de una provincia, usando los IDs que devuelve cada nivel.
El catálogo es estable
La división territorial cambia poco, así que puedes guardar el resultado en tu lado y evitar llamadas repetidas. No necesitas consultarlo en cada venta.
No confundas ubigeo con agencia
El ubigeo es la división territorial; la agencia es el punto físico donde se despacha. Para validar la dirección del cliente usas el ubigeo; para crear la guía necesitas el ID de la agencia de destino.
Errores de esta sección
| 404 | El departamento o provincia con ese ID no existe en el catálogo. |
Preguntas frecuentes
¿Qué es un ubigeo?
El código oficial del Perú para identificar un departamento, una provincia o un distrito.
¿Cómo obtengo los distritos de una provincia?
Con GET /locations/departments/{depId}/provinces/{provId}/districts.
¿Los IDs del catálogo cambian con el tiempo?
Cambian muy poco, así que puedes cachearlos en tu sistema y ahorrarte consultas.
¿Los ubigeos son obligatorios para crear un envío?
El envío se crea con el ID de la agencia de destino. Los ubigeos sirven para validar y armar la dirección del cliente.
¿Qué pasa si consulto un departamento o provincia que no existe?
La API responde 404 indicando que ese ID no está en el catálogo.
Continúa con
¿Aún no tienes API key?
Escríbenos por WhatsApp y la recibes de inmediato para probar todos estos ejemplos.
Solicitar API key