Ir al contenido

Consulta en lote de códigos postales

GET/v1/postal-codes/batchNegocio y Enterprise

¿Qué hace?

Consulta muchos códigos postales a la vez; por ejemplo, para revisar todas las direcciones de tu lista de clientes.

Hasta 100 códigos postales por petición (codes, separados por comas), con los mismos bloques de include que /v1/postal-codes/{code}. Un elemento por código pedido, en el mismo orden, con found y el mismo result que /v1/postal-codes/{code} o el error de ese código: un código malo nunca hace fallar todo el lote. Cuenta como una consulta por código.

La petición

ParámetroTipoValores aceptadosDescripción
codesen la consultaobligatoriolista de textoseparados por comas
de 1 a 100 elementos
cada uno: 5 dígitos
Códigos postales de 5 dígitos separados por comas (de 1 a 100).
includeen la consultalista de textoseparados por comas
satlocationmetro
Bloques opcionales a agregar, separados por comas (sat,location,metro). sat: datos del SAT para CFDI 4.0; requiere un plan de pago. location: ubicación de referencia del código postal; requiere un plan de pago. metro: zona metropolitana del código postal; requiere un plan de pago. Los códigos postales de demostración en /v1/postal-codes/{code} dan los tres bloques en todos los planes.

Ejemplo

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/postal-codes/batch?codes=06700,00000"

Cambia TU_LLAVE por tu llave; en los lenguajes, se lee de la variable de entorno COLONIX_API_KEY. Esta petición es la que produjo la respuesta de abajo.

La respuesta

Respuesta real a la petición del ejemplo. Viene con los encabezados ETag, X-Data-Version, Cache-Control, X-RapidAPI-Billing.

200 OK
{
"data": [
{
"postal_code": "06700",
"found": true,
"result": {
"postal_code": "06700",
"state": {
"id": "09",
"name": "Ciudad de México"
},
"municipality": {
"id": "015",
"name": "Cuauhtémoc"
},
"office": "06401",
"settlement_count": 1,
"settlements": [
{
"id": "09015-0947",
"name": "Roma Norte",
"type": "Colonia",
"zone": "Urbano",
"city": "Ciudad de México"
}
],
"data_version": "2026.11.05-36a7823b"
},
"error": null
},
{
"postal_code": "00000",
"found": false,
"result": null,
"error": {
"type": "/errors/postal-code-not-found",
"title": "Postal code not found",
"status": 404,
"detail": "Postal code 00000 does not exist in the current catalog."
}
}
],
"data_version": "2026.11.05-36a7823b"
}

Campos

CampoTipoDescripción
datalista de objetos
data[].postal_codetextoEl código tal como se pidió
data[].foundbooleanoEl código postal existe
data[].resultobjeto o nullIgual que /v1/postal-codes/{code}, o null
data[].errorobjeto o nullPor qué este código no tiene resultado (invalid-parameter o postal-code-not-found), o null
data_versiontextoVersión del dato

Errores

Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.

EstadoCuándo
400Parámetro inválido o repetido (/errors/invalid-parameter), un parámetro que el endpoint no tiene (/errors/unknown-parameter), cursor vencido (/errors/cursor-expired), versión del dato desconocida (/errors/unknown-version) o as_of fuera del historial registrado (/errors/as-of-out-of-range).
401Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key).
403Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed).
429Se alcanzó la cuota mensual (/errors/quota-exceeded) o el límite por minuto (/errors/rate-limited). La respuesta del límite por minuto trae el mismo cuerpo, pero con Content-Type: application/json.
5XXError inesperado (/errors/internal-error) o servicio no disponible por un momento (503, que puede llegar sin cuerpo). Reintenta unas cuantas veces, esperando cada vez más.