Consulta en lote de códigos postales
/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ámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
codesen la consultaobligatorio | lista 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 consulta | lista 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"const url = new URL("https://colonix.silgaru.mx/v1/postal-codes/batch");url.searchParams.set("codes", "06700,00000");
const res = await fetch(url, { headers: { "x-api-key": process.env.COLONIX_API_KEY }, signal: AbortSignal.timeout(5000),});const data = await res.json();if (!res.ok) throw new Error(`${data.type}: ${data.detail}`);
console.log(data);import osimport requests
res = requests.get( "https://colonix.silgaru.mx/v1/postal-codes/batch", params={"codes": "06700,00000"}, headers={"x-api-key": os.environ["COLONIX_API_KEY"]}, timeout=5,)data = res.json()if not res.ok: raise RuntimeError(f"{data['type']}: {data['detail']}")
print(data)<?php$url = "https://colonix.silgaru.mx/v1/postal-codes/batch?" . http_build_query(["codes" => "06700,00000"]);$ch = curl_init($url);curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("COLONIX_API_KEY")], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5,]);$data = json_decode(curl_exec($ch), true);if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) { throw new RuntimeException("{$data['type']}: {$data['detail']}");}
print_r($data);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.
{ "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
| Campo | Tipo | Descripción |
|---|---|---|
data | lista de objetos | |
data[].postal_code | texto | El código tal como se pidió |
data[].found | booleano | El código postal existe |
data[].result | objeto o null | Igual que /v1/postal-codes/{code}, o null |
data[].error | objeto o null | Por qué este código no tiene resultado (invalid-parameter o postal-code-not-found), o null |
data_version | texto | Versión del dato |
Errores
Todos en formato application/problem+json; ninguno cuenta para tu cuota. Qué hacer con cada uno: Errores.
| Estado | Cuándo |
|---|---|
400 | Pará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). |
401 | Credenciales faltantes (/errors/missing-api-key) o inválidas (/errors/invalid-api-key). |
403 | Llave suspendida (/errors/api-key-suspended) o endpoint fuera de tu plan (/errors/plan-not-allowed). |
429 | Se 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. |
5XX | Error 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. |
© 2026 Silgaru