Validar que un asentamiento pertenece a un código postal
/v1/validate/postal-code-settlementTodos los planes; include=sat e include=cfdi, planes de pago (Básico o superior)¿Qué hace?
Revisa que la colonia que escribió tu usuario de verdad pertenezca al código postal, antes de guardar la dirección, enviar o facturar. Si no, recibe las más parecidas o el código postal donde ese nombre sí existe.
Compara el nombre con los asentamientos del código postal, sin importar mayúsculas ni acentos, abreviaturas comunes (col., nte, fracc, sta...), el tipo de asentamiento al inicio, los espacios entre palabras ("Buena Vista" y "Buenavista") ni los artículos de, del, el, la, las y los ("Ojo de Agua" y "El Ojo de Agua"). Un ordinal puede escribirse en cualquiera de sus formas ("2a", "2da" y "Segunda" son lo mismo), pero los números, los ordinales y los numerales romanos deben tener el mismo valor y no se intercambian: "Sección 2", "2a Sección" y "Sección II" son nombres distintos. El día de una fecha puede ir con dígitos o con letra ("5 de Mayo" y "Cinco de Mayo" son el mismo nombre). Las palabras del final que son el resto de la dirección no cuentan: el municipio, el estado (también "CDMX", "Edo. Méx."), "del.", "alc." o "alcaldía" antes del municipio, el país ("México") y el propio código postal, con o sin "C.P." ("Roma Norte, Cuauhtémoc, CDMX" es valid). También sirve la línea completa de la dirección: se compara lo que va después del último "Col." o "Colonia" ("Calle Colima 123, Col. Roma Norte" es valid). Se entienden las abreviaturas de lo que SEPOMEX escribe completo: "SM" o "S.M." (Supermanzana), "Gpe." (Guadalupe), "Hda." (Hacienda), "Cda." (Cerrada), "Rcda." (Rinconada), "Pto." (Puerto), "Pdte." (Presidente), "Hrs." (Héroes) y "Ntra. Sra." (Nuestra Señora).
Nunca corrige en silencio: solo un nombre exacto o equivalente es valid. Cuando el nombre no es el completo de un asentamiento pero claramente señala uno, es una sugerencia con su reason, nunca valid: uno de los nombres de un asentamiento escrito como "A (B)" (alternate_name), el nombre sin el lugar que lleva ("Centro" por "Guadalajara Centro" o "Zona Centro", place_name), parte del nombre ("Roma" por "Roma Norte", contains), el mismo número en otra forma ("1a Sección" por "I Sección", same_number), iniciales en lugar de una palabra ("E. Zapata" por "Emiliano Zapata", abbreviation; "E." también puede ser otro nombre) o un error de escritura (spelling). Una sugerencia cuyo nombre no tiene un número que se escribió ("Supermanzana 52" por "Supermanzana 22") es otro lugar: queda debajo de 0.70, así que nunca es approximate por sí sola ni queda antes de una que conserva el número.
Cuando lo escrito no es una colonia sino el municipio o una ciudad del código postal ("Toluca") o un marcador de domicilio sin colonia ("Domicilio conocido", "S/N"), no se culpa al código postal: la conclusión nunca es other_postal_code. Si el código postal tiene una sola colonia, se sugiere con reason: only_settlement; tú decides si la usas. Cuando el nombre no está pero SEPOMEX renombró, movió o dio de baja un asentamiento con ese nombre en este código postal, history dice qué cambió, en qué versión del dato y dónde está hoy ese asentamiento.
outcome da la conclusión en un solo campo, para que no tengas que deducirla de los demás: valid; ambiguous (el nombre es del código postal, pero lo tiene más de uno de sus asentamientos: elige uno de same_name_settlements); approximate (el nombre señala un asentamiento del código postal: ver suggestions, con su confidence de 0 a 1 y su reason); other_postal_code (el nombre existe en otro código postal del mismo municipio o estado, en found_in_other_postal_codes, y ningún asentamiento de este código postal lo contiene: el error puede estar en el código postal); not_found (sus suggestions, si las hay, son débiles, de menos de 0.70); o postal_code_not_found. Un código postal que no existe no es un error: la respuesta dice postal_code_exists: false.
Con include=sat, también indica si el asentamiento tiene clave del SAT (c_Colonia) para CFDI 4.0 y sus complementos, con la conclusión en sat.status. Cuando el SAT escribe el nombre distinto, sat_match dice cómo se unieron; cuando los nombres no coinciden pero probablemente son el mismo lugar, sat_candidate sugiere la colonia del SAT, que debes confirmar: nunca se da como la clave. Con include=sat o include=cfdi, outcome también puede ser sat_only: SEPOMEX no tiene esa colonia en el código postal (ya no, o nunca la tuvo), pero el catálogo del SAT todavía la tiene ahí, así que su clave sirve en un CFDI.
Con include=cfdi, también devuelve el nodo Domicilio que piden los complementos del CFDI 4.0 (Carta Porte 3.1 y Comercio Exterior 2.0) con las claves del SAT, con los nombres de los atributos del XML y listo para copiar: CodigoPostal, Colonia (c_Colonia), Localidad (c_Localidad), Municipio (c_Municipio), Estado (c_Estado) y Pais (MEX). Salen de la fila del código postal en c_CodigoPostal, así que siempre coinciden con ella, como piden las reglas de validación del SAT. Cada atributo dice si se usa su clave, si se deja fuera (el SAT no le asigna una a ese código postal), si hay que confirmar la colonia sugerida o si hay que elegir entre asentamientos del código postal con el mismo nombre y claves distintas. El CFDI 4.0 por sí solo pide únicamente el código postal (LugarExpedicion, DomicilioFiscalReceptor).
La petición
| Parámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
postal_codeen la consultaobligatorio | texto | 5 dígitos | Código postal de 5 dígitos. |
settlementen la consultaobligatorio | texto | — | Nombre del asentamiento como lo escribió el usuario (de 2 a 100 caracteres, hasta 12 palabras). |
includeen la consulta | lista de textoseparados por comas | satcfdi | Bloques adicionales (planes de pago: Básico o superior): sat, si la colonia tiene clave del SAT para CFDI 4.0; cfdi, el nodo Domicilio de los complementos del CFDI (Carta Porte, Comercio Exterior) con las claves del SAT. |
Ejemplo
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/validate/postal-code-settlement?postal_code=06700&settlement=roma%20nrte"const url = new URL("https://colonix.silgaru.mx/v1/validate/postal-code-settlement");url.searchParams.set("postal_code", "06700");url.searchParams.set("settlement", "roma nrte");
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/validate/postal-code-settlement", params={"postal_code": "06700", "settlement": "roma nrte"}, 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/validate/postal-code-settlement?" . http_build_query(["postal_code" => "06700", "settlement" => "roma nrte"]);$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.
{ "postal_code": "06700", "query": "roma nrte", "postal_code_exists": true, "outcome": "approximate", "valid": false, "match": "approximate", "confidence": 0.9, "settlement": null, "same_name_settlements": [], "suggestions": [ { "settlement": { "id": "09015-0947", "postal_code": "06700", "name": "Roma Norte", "type": "Colonia", "zone": "Urbano", "city": "Ciudad de México", "state": { "id": "09", "name": "Ciudad de México" }, "municipality": { "id": "015", "name": "Cuauhtémoc" } }, "confidence": 0.9, "reason": "spelling" } ], "found_in_other_postal_codes": [], "history": null, "data_version": "2026.11.05-36a7823b"}Campos
| Campo | Tipo | Descripción |
|---|---|---|
postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
query | texto | El nombre del asentamiento tal como se recibió |
postal_code_exists | booleano | El código postal está en el catálogo de SEPOMEX |
outcome | texto | La conclusión, la primera de estas que aplique. valid: el nombre es un asentamiento del código postal (settlement). ambiguous: lo es, pero más de un asentamiento del código postal tiene ese nombre (valid es true, settlement es null y same_name_settlements los lista: elige uno por su type; cuando el tipo se escribe al inicio, como en "Pueblo San Andrés", el asentamiento de ese tipo es valid). sat_only, solo con include=sat o include=cfdi: ningún asentamiento de SEPOMEX del código postal tiene ese nombre, pero el catálogo del SAT lo tiene para este código postal (ver sat o cfdi). approximate: el nombre señala un asentamiento del código postal (ver suggestions y su reason). other_postal_code: el nombre existe en otro código postal del mismo municipio o estado (ver found_in_other_postal_codes) y ningún asentamiento de este código postal lo contiene. postal_code_not_found: el código postal no está en el catálogo de SEPOMEX. not_found: ninguna de las anteriores; sus suggestions, si las hay, son débiles (confianza de menos de 0.70).validambiguoussat_onlyapproximateother_postal_codepostal_code_not_foundnot_found |
valid | booleano | El nombre coincide exacta o equivalentemente con un asentamiento del código postal (outcome valid o ambiguous) |
match | texto | exact (válido), approximate (outcome approximate: ver suggestions) o noneexactapproximatenone |
confidence | número | 1 idéntico, 0.98 equivalente (abreviaturas, artículos, el resto de la dirección al final), menos para la mejor sugerencia |
settlement | objeto o null | El asentamiento encontrado si es válido, o null (también con outcome ambiguous: ver same_name_settlements) |
settlement.id | texto | Clave EEMMM-NNNN (estado, municipio, id SEPOMEX): no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal; otro municipio es otra clave |
settlement.postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
settlement.name | texto | Nombre del asentamiento |
settlement.type | texto | Tipo de asentamiento |
settlement.zone | texto | ZonaUrbanoRuralSemiurbano |
settlement.city | texto o null | Ciudad, o null si no tiene |
settlement.state | objeto | Elemento de un catálogo. |
settlement.municipality | objeto | Elemento de un catálogo. |
settlement.matchno siempre viene | texto | Solo con fuzzy=true: si el resultado coincide con q exactamente o con erroresexactapproximate |
same_name_settlements | lista de objetos | Con outcome ambiguous: los asentamientos del código postal cuyo nombre es el escrito (exacta o equivalentemente); se distinguen por su tipo. Vacía en los demás casos |
same_name_settlements[].id | texto | Clave EEMMM-NNNN (estado, municipio, id SEPOMEX): no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal; otro municipio es otra clave |
same_name_settlements[].postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
same_name_settlements[].name | texto | Nombre del asentamiento |
same_name_settlements[].type | texto | Tipo de asentamiento |
same_name_settlements[].zone | texto | ZonaUrbanoRuralSemiurbano |
same_name_settlements[].city | texto o null | Ciudad, o null si no tiene |
same_name_settlements[].state | objeto | Elemento de un catálogo. |
same_name_settlements[].municipality | objeto | Elemento de un catálogo. |
same_name_settlements[].matchno siempre viene | texto | Solo con fuzzy=true: si el resultado coincide con q exactamente o con erroresexactapproximate |
suggestions | lista de objetos | Hasta 5 asentamientos del código postal a los que puede referirse el nombre, el mejor primero |
suggestions[].settlement | objeto | Asentamiento (colonia, fraccionamiento, ranchería...). |
suggestions[].confidence | número | De 0 a 1: 0.95 con alternate_name, place_name y same_number, 0.90 con contains y abbreviation, 0.80 con only_settlement; con spelling, qué tan parecidos son los nombres, y a lo más 0.69 cuando al nombre le falta un número que se escribió |
suggestions[].reason | texto | Por qué se sugiere. alternate_name: el nombre es uno de los nombres de un asentamiento escrito como "A (B)". place_name: el nombre sin el municipio, la ciudad o "Zona" que lleva el asentamiento ("Centro" y "Guadalajara Centro"). contains: todas las palabras escritas están en el nombre, en orden ("Roma" y "Roma Norte"). same_number: el mismo nombre con el número en otra forma ("1a Sección" y "I Sección"; no se intercambian, así que confírmalo). abbreviation: el nombre con iniciales en lugar de algunas palabras ("E. Zapata" y "Emiliano Zapata"). only_settlement: lo escrito es el municipio, una ciudad o un marcador como "Domicilio conocido", y este es el único asentamiento del código postal. spelling: un error de escritura o un nombre parecido.alternate_nameplace_namecontainssame_numberabbreviationonly_settlementspelling |
found_in_other_postal_codes | lista de objetos | Hasta 5 asentamientos con nombre equivalente en otros códigos postales del mismo municipio (primero) o del mismo estado; nunca de otros estados, que casi nunca son la dirección que quiso escribir el usuario. Si el código postal no existe, primero los códigos postales más cercanos por número, de cualquier estado. |
found_in_other_postal_codes[].id | texto | Clave EEMMM-NNNN (estado, municipio, id SEPOMEX): no cambia cuando SEPOMEX le cambia el nombre o lo mueve a otro código postal; otro municipio es otra clave |
found_in_other_postal_codes[].postal_code | texto | Código postal de 5 dígitos (conserva los ceros iniciales). Con 4 dígitos, si existe el código con un cero adelante, el detail del 400 lo sugiere (las hojas de cálculo convierten 09700 en 9700). |
found_in_other_postal_codes[].name | texto | Nombre del asentamiento |
found_in_other_postal_codes[].type | texto | Tipo de asentamiento |
found_in_other_postal_codes[].zone | texto | ZonaUrbanoRuralSemiurbano |
found_in_other_postal_codes[].city | texto o null | Ciudad, o null si no tiene |
found_in_other_postal_codes[].state | objeto | Elemento de un catálogo. |
found_in_other_postal_codes[].municipality | objeto | Elemento de un catálogo. |
found_in_other_postal_codes[].matchno siempre viene | texto | Solo con fuzzy=true: si el resultado coincide con q exactamente o con erroresexactapproximate |
history | objeto o null | Cuando el nombre no está (outcome not_found, other_postal_code o postal_code_not_found) pero el historial de cambios tiene un asentamiento con ese nombre en este código postal, el cambio más reciente así; null si no. Explica por qué un nombre que antes validaba ya no. |
history.change | texto | Qué hizo SEPOMEX: lo renombró, lo movió a otro código postal, las dos cosas o lo dio de bajarenamedmovedrenamed_and_movedremoved |
history.version | texto | Versión del dato que trajo el cambio (ver /v1/changes) |
history.source_date | fecha | Fecha del archivo de SEPOMEX que lo trajo |
history.before | objeto | El asentamiento como era |
history.settlement | objeto o null | El asentamiento con el mismo id hoy, o null si se dio de baja |
satno siempre viene | objeto | Con include=sat |
sat.status | texto | La conclusión para el SAT. key: el asentamiento tiene clave del SAT (c_colonia). candidate: no la tiene, pero sat_candidate probablemente es el mismo lugar; confírmala antes de usar su clave. no_key: no tiene clave ni candidata. sat_only: ningún asentamiento de SEPOMEX del código postal tiene ese nombre, pero el catálogo del SAT lo tiene para este código postal, con c_colonia y sat_name; el SAT acepta esa clave en un CFDI. ambiguous: varios asentamientos del código postal tienen ese nombre y claves distintas (ver options). not_found: ningún catálogo tiene ese nombre para el código postal. postal_code_not_in_sat: el código postal no está en c_CodigoPostal.keycandidateno_keysat_onlyambiguousnot_foundpostal_code_not_in_sat |
sat.postal_code_in_sat | booleano | El código postal está en c_CodigoPostal |
sat.settlement_in_sat | booleano | El asentamiento tiene clave del SAT para este código postal (status key o sat_only) |
sat.c_colonia | texto o null | Clave de colonia del SAT (status key o sat_only), o null |
sat.sat_match | texto o null | Cómo se unieron un asentamiento de SEPOMEX y una colonia del SAT del mismo código postal: exact (el mismo nombre, sin importar mayúsculas ni acentos) o equivalent (el mismo nombre escrito distinto: abreviaturas comunes, el tipo de asentamiento al inicio, los espacios entre palabras o los artículos de, del, el, la, las y los, o un ordinal en otra de sus formas, como "2da" y "2a"; los números, los ordinales y los numerales romanos deben tener el mismo valor). Null cuando no hay unión. Los dos cuentan como el mismo asentamiento. La unión es uno a uno: cuando un código postal tiene varios asentamientos con el mismo nombre, cada uno se une con la colonia del SAT de su mismo número (el final de settlement_id, como 0398 en 09002-0398).exactequivalent |
sat.sat_name | texto o null | Nombre en el catálogo del SAT (status key o sat_only), o null |
sat.in_sepomex_postal_code | texto o null | Con sat_only: el código postal donde SEPOMEX tiene este mismo asentamiento (el mismo nombre y el mismo número al final de su settlement_id, en el mismo municipio), o null. En ese caso el SAT y SEPOMEX no coinciden en el código postal del asentamiento. |
sat.options | lista de objetos | Con status ambiguous: los asentamientos con ese nombre y sus claves del SAT. Vacía en los demás casos |
sat.sat_candidate | objeto o null | Sin clave: la colonia del SAT del mismo código postal que probablemente es el mismo lugar (confírmala antes de usar su clave), o null |
cfdino siempre viene | objeto | Con include=cfdi: el nodo Domicilio de los complementos del CFDI 4.0 (Carta Porte 3.1 y Comercio Exterior 2.0) para un domicilio en México, con las claves del SAT. El SAT rechaza un domicilio cuyas claves no coinciden con la fila del código postal en c_CodigoPostal (el estado y, si se escriben, el municipio y la localidad) o cuya Colonia no es un c_Colonia de ese código postal. Estas claves salen de esa fila, así que siempre coinciden. La calle, los números y la referencia los agregas tú. |
cfdi.ready | booleano | El nodo se puede usar tal como está: el código postal está en el catálogo del SAT y la colonia tiene su clave o se deja fuera (omit). False cuando un campo es not_found o hay que confirmar (confirm) o elegir (choose) la colonia. |
cfdi.address | objeto | Los atributos, con los nombres del XML: CodigoPostal, Colonia, Localidad, Municipio, Estado y Pais (siempre MEX). Null significa: no escribas el atributo (todos, salvo CodigoPostal, Estado y Pais, son opcionales en los complementos). Null en CodigoPostal y Estado significa que el código postal no está en el catálogo del SAT: el nodo no sirve. |
cfdi.fields | objeto | El resultado de cada atributo de address: su status (key, usa la clave; omit, deja fuera el atributo; confirm, solo en Colonia, confirma sat_candidate antes de usar su clave; choose, solo en Colonia, elige una de options; not_found, el código postal no está en el catálogo del SAT o la colonia no es del código postal) y name, el nombre de la clave en el catálogo del SAT. Colonia trae además in_sepomex (false cuando solo el catálogo del SAT tiene esa colonia), sat_candidate y options. |
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