Ir al contenido

Validar que un asentamiento pertenece a un código postal

GET/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ámetroTipoValores aceptadosDescripción
postal_codeen la consultaobligatoriotexto
5 dígitos
Código postal de 5 dígitos.
settlementen la consultaobligatoriotexto—Nombre del asentamiento como lo escribió el usuario (de 2 a 100 caracteres, hasta 12 palabras).
includeen la consultalista 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"

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.

200 OK
{
"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

CampoTipoDescripción
postal_codetextoCó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).
querytextoEl nombre del asentamiento tal como se recibió
postal_code_existsbooleanoEl código postal está en el catálogo de SEPOMEX
outcometextoLa 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
validbooleanoEl nombre coincide exacta o equivalentemente con un asentamiento del código postal (outcome valid o ambiguous)
matchtextoexact (válido), approximate (outcome approximate: ver suggestions) o none
exactapproximatenone
confidencenúmero1 idéntico, 0.98 equivalente (abreviaturas, artículos, el resto de la dirección al final), menos para la mejor sugerencia
settlementobjeto o nullEl asentamiento encontrado si es válido, o null (también con outcome ambiguous: ver same_name_settlements)
settlement.idtextoClave 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_codetextoCó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.nametextoNombre del asentamiento
settlement.typetextoTipo de asentamiento
settlement.zonetextoZona
UrbanoRuralSemiurbano
settlement.citytexto o nullCiudad, o null si no tiene
settlement.stateobjetoElemento de un catálogo.
settlement.municipalityobjetoElemento de un catálogo.
settlement.matchno siempre vienetextoSolo con fuzzy=true: si el resultado coincide con q exactamente o con errores
exactapproximate
same_name_settlementslista de objetosCon 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[].idtextoClave 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_codetextoCó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[].nametextoNombre del asentamiento
same_name_settlements[].typetextoTipo de asentamiento
same_name_settlements[].zonetextoZona
UrbanoRuralSemiurbano
same_name_settlements[].citytexto o nullCiudad, o null si no tiene
same_name_settlements[].stateobjetoElemento de un catálogo.
same_name_settlements[].municipalityobjetoElemento de un catálogo.
same_name_settlements[].matchno siempre vienetextoSolo con fuzzy=true: si el resultado coincide con q exactamente o con errores
exactapproximate
suggestionslista de objetosHasta 5 asentamientos del código postal a los que puede referirse el nombre, el mejor primero
suggestions[].settlementobjetoAsentamiento (colonia, fraccionamiento, ranchería...).
suggestions[].confidencenúmeroDe 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[].reasontextoPor 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_codeslista de objetosHasta 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[].idtextoClave 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_codetextoCó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[].nametextoNombre del asentamiento
found_in_other_postal_codes[].typetextoTipo de asentamiento
found_in_other_postal_codes[].zonetextoZona
UrbanoRuralSemiurbano
found_in_other_postal_codes[].citytexto o nullCiudad, o null si no tiene
found_in_other_postal_codes[].stateobjetoElemento de un catálogo.
found_in_other_postal_codes[].municipalityobjetoElemento de un catálogo.
found_in_other_postal_codes[].matchno siempre vienetextoSolo con fuzzy=true: si el resultado coincide con q exactamente o con errores
exactapproximate
historyobjeto o nullCuando 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.changetextoQué hizo SEPOMEX: lo renombró, lo movió a otro código postal, las dos cosas o lo dio de baja
renamedmovedrenamed_and_movedremoved
history.versiontextoVersión del dato que trajo el cambio (ver /v1/changes)
history.source_datefechaFecha del archivo de SEPOMEX que lo trajo
history.beforeobjetoEl asentamiento como era
history.settlementobjeto o nullEl asentamiento con el mismo id hoy, o null si se dio de baja
satno siempre vieneobjetoCon include=sat
sat.statustextoLa 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_satbooleanoEl código postal está en c_CodigoPostal
sat.settlement_in_satbooleanoEl asentamiento tiene clave del SAT para este código postal (status key o sat_only)
sat.c_coloniatexto o nullClave de colonia del SAT (status key o sat_only), o null
sat.sat_matchtexto o nullCó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_nametexto o nullNombre en el catálogo del SAT (status key o sat_only), o null
sat.in_sepomex_postal_codetexto o nullCon 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.optionslista de objetosCon status ambiguous: los asentamientos con ese nombre y sus claves del SAT. Vacía en los demás casos
sat.sat_candidateobjeto o nullSin 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 vieneobjetoCon 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.readybooleanoEl 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.addressobjetoLos 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.fieldsobjetoEl 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_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.