Consulta un código postal mexicano desde tu propia aplicación
Alguien escribió cinco dígitos en un formulario. Necesitas saber a qué estado y municipio corresponden, y qué colonias pudo haber querido decir, antes de que pueda terminar la dirección. Eso es una sola solicitud.
Lo que en realidad estás intentando hacer
Una dirección mexicana no es un campo de texto libre. Un código postal determina el estado y el municipio sin margen de duda, y reduce la colonia a una lista corta. Cada checkout, cada formulario de entrega y cada importación de CRM del país hace las mismas tres cosas con ese hecho.
-
Rellenar los campos que el cliente no debería tener que escribir.
El estado y el municipio se deducen del código. Volver a pedirlos son tres oportunidades más de equivocarse en una dirección de entrega.
-
Ofrecer la colonia como lista y no como caja de texto.
Aquí es donde las direcciones se echan a perder de verdad. Si la escriben ellos, te dan «Centro», «centro», «Col. Centro» y «Guadalajara Centro» para un mismo lugar.
-
Rechazar un código que no existe, en el momento en que se escribe.
Que un número de cinco dígitos pase una expresión regular no lo convierte en un código postal real. La consulta responde 404 cuando no hay nada ahí, que es la validación más barata que vas a escribir.
Una solicitud, todo lo que el formulario necesita
Manda el código, recibe el registro. El 06600 es la zona de la Colonia Juárez, en la alcaldía Cuauhtémoc de la Ciudad de México, y es el código que usan los ejemplos de toda la referencia, así que es fácil de contrastar.
Solicitud
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/postal-codes/06600
Respuesta
{
"data": {
"id": 384,
"code": "06600",
"state": { "id": 1, "name": "Ciudad de México", "code": "09" },
"municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
"city": { "id": 1, "name": "Ciudad de México" },
"settlements": [
{ "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
]
}
}
El estado y el municipio van directos a sus campos. El arreglo settlements es el desplegable de colonias: muestra name, guarda id. Ese id es lo que almacenas en el pedido, porque sigue significando la misma colonia después de que el catálogo se actualice, y una cadena de texto no.
Si ya tienes el estado y el municipio en el registro y solo necesitas la lista otra vez —el cliente cambió de opinión, o estás volviendo a mostrar una dirección guardada—, hay una llamada más ligera que se salta el resto:
Solicitud
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/postal-codes/06600/settlements
Respuesta
{
"data": [
{ "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
]
}
Antes de publicarlo
Cuatro cosas con las que la gente tropieza
-
Los códigos postales son cadenas, no enteros.
Todos los códigos de la Ciudad de México y buena parte del centro del país empiezan con cero. Si en cualquier punto de tu stack interpretas 06600 como número, vas a estar pidiendo el 6600, que está en otra parte por completo.
-
Un 404 es una respuesta, no una falla.
Un código desconocido devuelve 404 con un mensaje que lo nombra. Trátalo como «ese código postal no existe» y muestra el error en el campo; no lo reintentes ni lo registres como una caída.
-
Una colonia no siempre es una colonia.
settlement_type distingue entre Colonia, Fraccionamiento, Barrio, Unidad habitacional y las demás. Si en el desplegable muestras solo el nombre, dos lugares distintos bajo el mismo código pueden verse idénticos.
-
Guárdalo en caché. Cambia una vez al mes como mucho.
El catálogo se contrasta con la fuente el primer día de cada mes y no se mueve nada salvo que la fuente se haya movido. GET /v1/account/db-version te dice qué versión te respondió, así que una caché con esa clave se invalida sola.