Ir al contenido

Cómo se unen las colonias del SAT y de SEPOMEX

El SAT y SEPOMEX publican catálogos distintos, y a veces escriben distinto la misma colonia: “Villa Centroamericana” en uno, “Villa Centro Americana” en el otro. Si se comparan letra por letra, la colonia parece no tener clave del SAT aunque sí la tenga. Colonix une los nombres que son el mismo escrito de otra forma y te da su clave. Cuando los nombres no coinciden pero probablemente son el mismo lugar, te sugiere la colonia del SAT para que tú la confirmes: nunca la da como la clave.

Necesitas: plan Básico o superior para include=sat en la validación y para /v1/sat/postal-codes/{code}; plan Negocio para /v1/sat/discrepancies. Ninguno de los dos catálogos se corrige: siempre recibes los dos nombres tal como los publica cada uno.

Esta guía trata de los nombres. Lo que difiere de fondo (colonias que el SAT aún no tiene, códigos postales que faltan en un catálogo) está en Casos reales del cruce entre el SAT y SEPOMEX.

Colonix compara cada asentamiento de SEPOMEX solo con las colonias del SAT del mismo código postal, y cada par puede terminar de una de estas formas:

Resultado Qué significa ¿Recibes la clave c_Colonia?
Exacto (exact) El mismo nombre, sin contar mayúsculas ni acentos Sí
Equivalente (equivalent) El mismo nombre escrito de otra forma (las reglas, abajo) Sí
Sugerencia (sat_candidate, sepomex_candidate, possible_match) Nombres distintos que probablemente son el mismo lugar No: recibes un candidato que debes confirmar
Sin pareja Ninguna colonia del SAT del código postal se le parece lo suficiente, o hay más de una candidata No

Con el dato del 05/11/2026, 120,535 asentamientos de SEPOMEX tienen su clave del SAT (1,739 de ellos por un nombre equivalente) y otros 3,876 reciben una sugerencia.

Nombres repetidos en un código postal. Algunos códigos postales tienen dos asentamientos con el mismo nombre: en el 02240, “San Andrés” es un barrio (09002-0398) y también un pueblo (09002-0399). Ahí Colonix une cada uno con la colonia del SAT de su mismo número (0398 y 0399), y nunca da dos claves del SAT a un mismo asentamiento: si el SAT tiene más colonias con ese nombre que SEPOMEX, las que sobran cuentan como colonias que solo están en el SAT. Al validar, “San Andrés” no elige ninguno (los dos son del código postal), pero “Pueblo San Andrés” sí: el del tipo que se escribió.

Equivalente: el mismo nombre escrito de otra forma

Section titled “Equivalente: el mismo nombre escrito de otra forma”

Dos nombres son equivalentes cuando, al quitar estas diferencias, queda exactamente el mismo texto:

  • Mayúsculas y acentos: “Cancún” y “CANCUN”.
  • Abreviaturas comunes: “Fracc.” y “Fraccionamiento”, “Sta.” y “Santa”, “Nte.” y “Norte”, “U.H.” y “Unidad Habitacional”.
  • El tipo de asentamiento al inicio: “Colonia Guadalupe” y “Guadalupe”; también Barrio, Pueblo, Fraccionamiento, Unidad Habitacional y Conjunto Habitacional.
  • Los espacios entre palabras: “Buena Vista” y “Buenavista”.
  • Los artículos de, del, el, la, las y los: “Ojo de Agua” y “El Ojo de Agua”.
  • La forma de escribir un ordinal: “2da. Sección”, “2a Sección” y “Segunda Sección”; “1er”, “1ro”, “1o”, “Primero” y “Primera” (del primero al décimo). “Quinta” solo cuenta como ordinal antes de una palabra como Sección, Etapa o Ampliación, porque también es un tipo de casa (“Quinta del Rey”).
  • El día de una fecha con dígitos o con letra: “5 de Mayo” y “Cinco de Mayo”, “1o de Mayo” y “Primero de Mayo”, “31 de Marzo” y “Treinta y Uno de Marzo”. Solo antes de “de” y un mes: “Cinco Hermanos” no cambia, y dos días distintos (“Dieciséis” y “Diecisiete de Septiembre”) siguen siendo nombres distintos.

Son las mismas reglas con que la validación da una colonia por válida: si /v1/validate/postal-code-settlement acepta un nombre como la colonia, la unión con el SAT usa el mismo criterio. Casos reales:

Código postal En SEPOMEX En el SAT Qué los distingue
13278 Villa Centroamericana Villa Centro Americana Un espacio
62724 Buena Vista Buenavista Un espacio
51442 Ojo de Agua El Ojo de Agua Un artículo
78950 Guadalupe Colonia Guadalupe El tipo al inicio
23888 Lote 2-A Lote 2a Un guion
66074 Mirasur Mira Sur Un espacio
22624 Obrera 2da. Sección Obrera 2a Sección La forma del ordinal
22020 Chapultepec Decima Sección Chapultepec 10a Sección El ordinal con letra
09800 Culhuacán Pueblo Culhuacán El tipo al inicio
32390 Benito Juárez U.H. Benito Juárez El tipo al inicio, abreviado
86910 Dieciséis de Septiembre 16 de Septiembre El día con letra

Un equivalente se trata igual que un nombre exacto: el asentamiento recibe la clave, match dice "equivalent" y sepomex_name (o sat_name en la validación) te muestra cómo lo escribe el otro catálogo, por si lo necesitas en tu comprobante.

curl -G -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/validate/postal-code-settlement \
--data-urlencode "postal_code=13278" --data-urlencode "settlement=villa centroamericana" -d include=sat
200 OK (fragmento)
"sat": {
"status": "key",
"postal_code_in_sat": true,
"settlement_in_sat": true,
"c_colonia": "1959",
"sat_match": "equivalent",
"sat_name": "Villa Centro Americana",
"sat_candidate": null,
"in_sepomex_postal_code": null,
"options": []
}

Cuando los nombres no son equivalentes pero se parecen mucho, Colonix te sugiere la colonia del otro catálogo. Una sugerencia nunca es la clave: el asentamiento sigue sin c_Colonia y sigue apareciendo en settlements_missing_in_sat y en las diferencias hasta que tú lo confirmes. Solo se sugiere cuando se cumple todo esto:

  1. Los dos están en el mismo código postal.
  2. Es el único candidato de los dos lados: si un asentamiento se parece a dos colonias del SAT, o una colonia del SAT a dos asentamientos, no se sugiere ninguna.
  3. Los dos nombres tienen las mismas marcas: números, ordinales y numerales romanos (también escritos con letra, como “Uno” o “Segunda”), puntos cardinales (Norte, Sur, Oriente, Poniente) y letras de sector (“Sector B”). Son las palabras que distinguen lugares vecinos.
  4. La diferencia es de uno de estos tres tipos:
difference Qué significa Caso real
alias Iguales si se quita lo que va entre paréntesis, que uno de los catálogos agrega: un nombre antiguo o popular 86287: “Santa Catalina (San Marcos)” en SEPOMEX, “Santa Catalina” en el SAT
extra_words Un nombre tiene todas las palabras del otro y alguna más 34440: “Mesa de Guadalupe” en SEPOMEX, “Rancho Mesa de Guadalupe” en el SAT
spelling Letras distintas: errores de escritura, singular o plural 14654: “Dolores Tlalli” en SEPOMEX, “Dolores Tlali” en el SAT

Así se ve una sugerencia en la validación:

curl -G -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/validate/postal-code-settlement \
--data-urlencode "postal_code=14654" --data-urlencode "settlement=dolores tlalli" -d include=sat
200 OK (fragmento)
"sat": {
"status": "candidate",
"postal_code_in_sat": true,
"settlement_in_sat": false,
"c_colonia": null,
"sat_match": null,
"sat_name": null,
"sat_candidate": {
"c_colonia": "2453",
"name": "Dolores Tlali",
"similarity": 0.92,
"difference": "spelling",
"same_key": true
},
"in_sepomex_postal_code": null,
"options": []
}

La colonia es válida en SEPOMEX ("valid": true), pero el SAT no tiene ninguna con ese nombre ("status": "candidate"). Tiene “Dolores Tlali”, con una “l” menos, en el mismo código postal: es la sugerencia.

Cada sugerencia trae dos datos para que decidas:

similarity, qué tanto se parecen los nombres (de 0 a 1). Es la misma escala que confidence en la validación: desde 0.70 se considera el mismo nombre con errores de escritura. Mide los nombres, no el lugar: no es la probabilidad de que sean la misma colonia. Por eso no te damos un porcentaje de probabilidad: para calcularlo haría falta saber de antemano cuáles sugerencias son correctas, y esa lista no existe. Las sugerencias por alias pueden tener una similitud baja, porque el texto entre paréntesis cuenta (“Santa Catalina (San Marcos)” y “Santa Catalina”: 0.67).

same_key, si las claves tienen el mismo número. La clave de un asentamiento de SEPOMEX termina con un número que casi siempre es el c_Colonia del SAT: “Dolores Tlalli” es 09012-2453 y “Dolores Tlali” es la 2453. En las colonias con el mismo nombre en los dos catálogos, los números coinciden en más del 98 % de los casos, así que true es una evidencia más de que la sugerencia es correcta (96 % de las sugerencias la tienen). No es prueba: una colonia que cambió de nombre también conserva el número. Y false no descarta la sugerencia, pero sí pide más cuidado.

Estos casos reales parecen el mismo nombre, pero son lugares distintos. Colonix no los une ni los sugiere:

Código postal En SEPOMEX En el SAT Por qué no
20196 Ojocaliente I, II y III Ojocaliente Numerales romanos distintos
16240 Tlaxopan Tlaxopan 1a Sección y Tlaxopan 2a Sección Ordinales distintos
56350 Dieciséis de Septiembre Diecisiete de Septiembre Números con letra distintos
27960 Santa Anita Uno (El Jacalón) Santa Anita Dos (El Jacalón) Números con letra distintos
48904 Brisas del Oeste Brisas del Norte Puntos cardinales distintos
20130 Residencial Campestre Club de Golf Residencial Campestre Club de Golf Norte y Sur Dos candidatos (y un punto cardinal de más)

Un número, un ordinal y un numeral romano tampoco se intercambian, aunque valgan lo mismo: “Sección 2”, “2a Sección” y “Sección II” son nombres distintos. Solo cambia la forma de escribir el mismo ordinal (“2da” y “2a”).

Si la respuesta dice Qué hacer
match o sat_match: "exact" Usa la clave c_colonia
match o sat_match: "equivalent" Usa la clave c_colonia; el nombre del otro catálogo está en sepomex_name o sat_name
Una sugerencia (sat_candidate) Pregunta a tu usuario, con los dos nombres a la vista: “¿Tu colonia es «Dolores Tlali»?”. Usa su clave solo si confirma
Sin clave ni sugerencia La colonia no tiene clave del SAT: si tu comprobante necesita c_Colonia, pide a tu usuario que elija otra colonia del código postal que sí la tenga

En la validación no tienes que leer cada campo: sat.status dice la conclusión (key, candidate, no_key, sat_only, ambiguous…); la tabla completa está en Validar una dirección para CFDI 4.0.

Nunca uses la clave de una sugerencia sin que alguien la confirme. Si guardas la respuesta, guarda también data_version: te dice con qué dato se respondió.

Endpoint Campos
GET /v1/validate/postal-code-settlement?include=sat En sat: status, sat_match, sat_name, sat_candidate, in_sepomex_postal_code y, con nombres repetidos, options
GET /v1/sat/postal-codes/{code} En cada colonia de settlements: match, settlement_id, sepomex_name y sepomex_candidate; en cada asentamiento de settlements_missing_in_sat: sat_candidate
GET /v1/sat/discrepancies En cada asentamiento: possible_match (la sugerencia del otro catálogo, o null). Los equivalentes ya no aparecen como diferencias

No tienes que hacer nada cuando el SAT o SEPOMEX publican cambios. Colonix revisa los catálogos cada semana y, con cada dato nuevo, vuelve a unir y a sugerir con las mismas reglas. Si algún día cambian las reglas, cambia el ETag de las respuestas aunque el dato sea el mismo, para que tu caché no se quede con una respuesta anterior.