Ir al contenido

Validar una dirección para CFDI 4.0

Una factura se rechaza si el código postal no está en el catálogo del SAT, y un complemento como Carta Porte también si la colonia, el municipio o el estado no son las claves que corresponden a ese código postal. Con Colonix revisas la dirección antes de timbrar y obtienes esas claves en una sola consulta.

Necesitas: plan Básico o superior. Los cinco códigos postales de demostración (06700, 44100, 64000, 22000 y 77500) responden /v1/sat/postal-codes/{code} en cualquier plan para que pruebes; la validación con include=sat o include=cfdi no tiene códigos de demostración.

Dato Dónde se usa Qué hace Colonix
Código postal (c_CodigoPostal) LugarExpedicion del emisor y DomicilioFiscalReceptor del receptor Confirma que está en el catálogo del SAT
Colonia (c_Colonia) Domicilios de complementos, como las ubicaciones de Carta Porte Te da la clave de la colonia y dice si el SAT la tiene
Estado, municipio y localidad (c_Estado, c_Municipio, c_Localidad) Domicilios de complementos Te da las claves que corresponden al código postal
El domicilio completo (CodigoPostal, Colonia, Localidad, Municipio, Estado, Pais) Carta Porte y Comercio Exterior Con include=cfdi, te lo arma con las claves y te dice qué atributo dejar fuera (paso 3)

Cuando tu cliente captura su dirección, valida el par código postal + colonia con include=sat:

curl -G -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/validate/postal-code-settlement \
--data-urlencode "postal_code=44100" --data-urlencode "settlement=guadalajara centro" -d include=sat
200 OK
{
"postal_code": "44100",
"query": "guadalajara centro",
"postal_code_exists": true,
"outcome": "valid",
"valid": true,
"match": "exact",
"confidence": 1,
"settlement": {
"id": "14039-0003",
"postal_code": "44100",
"name": "Guadalajara Centro",
"type": "Colonia",
"zone": "Urbano",
"city": "Guadalajara",
"state": { "id": "14", "name": "Jalisco" },
"municipality": { "id": "039", "name": "Guadalajara" }
},
"same_name_settlements": [],
"suggestions": [],
"found_in_other_postal_codes": [],
"sat": {
"status": "key",
"postal_code_in_sat": true,
"settlement_in_sat": true,
"c_colonia": "0003",
"sat_match": "exact",
"sat_name": "Guadalajara Centro",
"sat_candidate": null,
"in_sepomex_postal_code": null,
"options": []
},
"data_version": "2026.11.05-36a7823b"
}

No tienes que combinar campos para saber qué pasó: outcome dice la conclusión de la validación y sat.status, la del SAT.

outcome Qué significa Qué hacer
valid La colonia es del código postal (settlement) Sigue con sat.status
ambiguous La colonia es del código postal, pero dos o más tienen ese nombre (same_name_settlements) Que tu cliente elija la suya por el tipo
sat_only SEPOMEX no la tiene en ese código postal, pero el SAT sí (solo con include=sat o include=cfdi) Para el CFDI, la clave sirve; para el domicilio, confírmalo con tu cliente
approximate El nombre señala una colonia del código postal, pero no es su nombre completo: “Centro” por “Guadalajara Centro”, “Roma” por “Roma Norte”, “E. Zapata” por “Emiliano Zapata” o un error de escritura (el motivo, en suggestions[].reason). Con only_settlement, tu cliente escribió el municipio o “Domicilio conocido” y el código postal tiene una sola colonia Muestra las suggestions y que tu cliente elija; Colonix nunca corrige solo. Una sugerencia que cambia el número (“Supermanzana 52” por “Supermanzana 22”) queda debajo de 0.70: es otro lugar
other_postal_code La colonia existe, pero en otro código postal del mismo municipio o estado Probablemente el error está en el código postal: muéstrale found_in_other_postal_codes
postal_code_not_found El código postal no existe Pide a tu cliente que lo revise
not_found Ninguno de los anteriores Pide a tu cliente que revise la dirección

Si tu cliente escribe el municipio o la ciudad en lugar de la colonia (“Toluca”), o algo como “Domicilio conocido” o “S/N”, Colonix no culpa al código postal: la conclusión nunca es other_postal_code. Y si escribe un nombre que SEPOMEX renombró, movió a otro código postal o dio de baja, history dice qué cambió, en qué versión del dato y dónde está hoy esa colonia (history.settlement): “Jubilados y Pensionados” en el 29267 es hoy “San Vicente Ferrer” en el 29263. Muéstraselo; nunca se toma solo como válido.

sat.status Qué significa Qué hacer
key La colonia tiene su clave del SAT (sat.c_colonia); con sat.sat_match: "equivalent", el SAT escribe distinto el nombre (“Villa Centro Americana” por “Villa Centroamericana”), pero es la misma colonia Usa sat.c_colonia; el nombre del SAT está en sat.sat_name
candidate El SAT no tiene una colonia con ese nombre, pero sí una que probablemente es la misma (sat.sat_candidate) Pregunta a tu cliente si su colonia es la del candidato; usa esa clave solo si confirma
no_key La colonia existe en SEPOMEX, pero el SAT no tiene clave para ella Si tu comprobante necesita c_Colonia, elige otra colonia del código postal que sí la tenga o revisa con tu cliente
sat_only Solo el SAT tiene esa colonia en el código postal: sat.c_colonia es su clave y sat.in_sepomex_postal_code, si SEPOMEX tiene la misma colonia en otro código postal del municipio Usa la clave para el CFDI y confirma el domicilio con tu cliente
ambiguous Varias colonias del código postal tienen ese nombre y claves distintas (sat.options) Que tu cliente elija; usa el c_colonia de la que elija
not_found Ningún catálogo tiene ese nombre en el código postal Revisa outcome y sus listas
postal_code_not_in_sat El código no está en el catálogo del SAT No timbres con él: el CFDI se rechazaría

Un caso real de no_key: en el 77500 (Cancún), “Residencial La Cascada” responde "outcome": "valid", pero "sat": { "status": "no_key", "c_colonia": null, … }, porque el catálogo del SAT no la incluye ni tiene una parecida.

Cómo decide Colonix cuándo una colonia del SAT es la misma que la de SEPOMEX, y cuándo solo la sugiere, está explicado con casos reales en Cómo se unen las colonias del SAT y de SEPOMEX.

Las diferencias que no son de nombre (colonias nuevas que el SAT aún no tiene, colonias que solo tiene el SAT, dos colonias con el mismo nombre, códigos postales sin colonias en el SAT o que faltan en su catálogo) tienen sus ejemplos en Casos reales del cruce entre el SAT y SEPOMEX.

3. Arma el domicilio con claves en una consulta

Section titled “3. Arma el domicilio con claves en una consulta”

El CFDI 4.0 solo pide códigos postales. Los complementos, en cambio, piden el domicilio completo con las claves de los catálogos del SAT:

Dónde Qué pide del domicilio
CFDI 4.0 (LugarExpedicion, DomicilioFiscalReceptor) Solo el código postal
Carta Porte 3.1 (Ubicacion/Domicilio y TiposFigura/Domicilio) CodigoPostal, Estado y Pais, obligatorios; Colonia, Localidad y Municipio, opcionales, pero si los escribes deben ser claves
Comercio Exterior 2.0 (domicilios del emisor, el receptor y el destinatario) Las mismas claves, con las mismas reglas

Las reglas del SAT para un domicilio en México (Pais="MEX") están en las matrices de errores de cada complemento (por ejemplo, CP143 a CP147 en Carta Porte 3.1): la colonia debe ser una c_Colonia del mismo código postal, y el estado, el municipio y la localidad deben ser los que el catálogo c_CodigoPostal tiene en la fila de ese código postal. Un domicilio con un municipio que no corresponde se rechaza al timbrar.

Con include=cfdi, la misma validación del paso 1 te devuelve el nodo armado, con los nombres de los atributos del XML y las claves que salen de esa fila, así que siempre coinciden. Este es el ejemplo del instructivo de llenado de Carta Porte 3.1 del SAT:

curl -G -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/validate/postal-code-settlement \
--data-urlencode "postal_code=06300" --data-urlencode "settlement=guerrero" -d include=cfdi
200 OK (fragmento)
"cfdi": {
"ready": true,
"address": {
"CodigoPostal": "06300",
"Colonia": "0900",
"Localidad": "06",
"Municipio": "015",
"Estado": "CMX",
"Pais": "MEX"
},
"fields": {
"CodigoPostal": { "status": "key", "name": null },
"Colonia": { "status": "key", "name": "Guerrero", "in_sepomex": true, "sat_candidate": null, "options": [] },
"Localidad": { "status": "key", "name": "Ciudad de México" },
"Municipio": { "status": "key", "name": "Cuauhtémoc" },
"Estado": { "status": "key", "name": "Ciudad de México" }
}
}

La calle, los números y la referencia los agregas tú. En fields, cada atributo dice qué hacer:

status Qué significa Qué hacer
key La clave del SAT está en address Escríbela en el atributo
omit El SAT no le asigna una clave a ese código postal (o, en Colonia, la colonia no tiene clave del SAT) No escribas el atributo: es opcional, y cualquier valor tendría que coincidir con una fila que no lo trae
confirm Solo en Colonia: el SAT no tiene una colonia con ese nombre, pero sat_candidate probablemente es la misma Pregúntale a tu cliente; usa la clave del candidato solo si confirma
choose Solo en Colonia: dos o más colonias del código postal tienen ese nombre y claves distintas (options, cada una con su tipo y su c_colonia) Que tu cliente elija la suya; escribe el c_colonia de la que elija
not_found El código postal no está en el catálogo del SAT o, en Colonia, la colonia no es de ese código postal No timbres con ese domicilio: revisa la respuesta de la validación (suggestions, found_in_other_postal_codes)

ready: true quiere decir que el nodo se puede usar tal como está. Si es false, algún atributo es confirm, choose o not_found.

Casos reales:

  • Sin localidad. En el 45220 (Nextipac, Zapopan), la fila del SAT no trae localidad: "Localidad": null con "status": "omit". Pasa en 20,513 de los 31,868 códigos postales de SEPOMEX; el municipio falta en 1,247 (por ejemplo, el 20343, en Aguascalientes).
  • Colonia por confirmar. En el 14654, “dolores tlalli” es válida en SEPOMEX, pero el SAT la escribe “Dolores Tlali”: "Colonia": null, "status": "confirm" y la clave 2453 en sat_candidate.
  • Colonia que solo tiene el SAT. En el 01490, SEPOMEX no tiene “Torres de Mixcoac”, así que la validación responde "valid": false y "outcome": "sat_only", pero el SAT sí la tiene: "Colonia": "0212" con "in_sepomex": false. La clave se da solo si una colonia del SAT de ese código postal tiene el mismo nombre o uno equivalente.
  • Dos colonias con el mismo nombre. En el 02240 (Azcapotzalco) hay un barrio y un pueblo “San Andrés”: "outcome": "ambiguous", "Colonia": null, "status": "choose" y en options las claves 0398 (barrio) y 0399 (pueblo).
  • Código postal fuera del SAT. El 91312 está en SEPOMEX pero no en c_CodigoPostal: todos los atributos vienen en not_found y ready: false.

Si necesitas todas las colonias del código postal (por ejemplo, para una lista desplegable donde tu cliente elige la suya), pide el código postal en el catálogo del SAT:

curl -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/sat/postal-codes/44100
200 OK
{
"postal_code": "44100",
"in_sat": true,
"in_sepomex": true,
"state": { "sat_code": "JAL", "id": "14", "name": "Jalisco" },
"municipality": { "sat_code": "039", "name": "Guadalajara" },
"locality": { "sat_code": "03", "name": "Guadalajara" },
"border_stimulus": null,
"border_stimulus_decree": null,
"time_zone": {
"description": "Tiempo del Centro",
"utc_offset_summer": -6,
"utc_offset_winter": -6,
"dst_start": null,
"dst_end": null,
"iana": "America/Mexico_City",
"utc_offset_standard": -6,
"utc_offset_dst": null,
"matches_sat": true
},
"settlements": [
{
"c_colonia": "0003",
"name": "Guadalajara Centro",
"settlement_id": "14039-0003",
"match": "exact",
"sepomex_name": "Guadalajara Centro",
"sepomex_candidate": null
}
],
"settlements_missing_in_sat": [],
"sat_revision": {
"file": "catCFDI_V_4_20261029.xls",
"postal_codes": "8",
"settlements": "0",
"settlements_revised": false,
"published": "2026-01-22"
},
"data_version": "2026.11.05-36a7823b"
}
Campo Para qué
state.sat_code, municipality.sat_code, locality.sat_code c_Estado, c_Municipio y c_Localidad del domicilio
settlements[].c_colonia c_Colonia de cada colonia que el SAT tiene para el código postal
settlements[].match Cómo se unió con SEPOMEX: exact (mismo nombre), equivalent (mismo nombre escrito distinto) o null
settlements_missing_in_sat Colonias de SEPOMEX sin clave del SAT: no las ofrezcas donde se pida c_Colonia. Si alguna trae sat_candidate, es la colonia del SAT que probablemente es la misma: confírmala antes de usar su clave
border_stimulus Si el código postal está en la región del estímulo fiscal fronterizo, según el SAT: north (norte), south (sur) o null (ninguna). El código postal no basta para aplicarlo: ver la sección 4
border_stimulus_decree Hasta cuándo está vigente el decreto del estímulo (valid_until), cuándo se publicó (published) y su enlace en el DOF (source); null fuera de las regiones fronterizas
time_zone El huso horario como lo publica el SAT (description, utc_offset_summer, utc_offset_winter, dst_start, dst_end) y la hora local real: iana, utc_offset_standard, utc_offset_dst y matches_sat (sección 4)
in_sat, in_sepomex En qué catálogos está el código postal: hay códigos que solo están en uno
sat_revision Archivo y revisión del catálogo del SAT con que se respondió; settlements_revised dice si el SAT ha revisado alguna vez el catálogo de colonias (abajo)

Un código postal puede estar en el catálogo del SAT y no en el de SEPOMEX, o al revés. Colonix no corrige un catálogo con el otro: te dice en cuál está cada dato para que decidas.

El SAT revisa su catálogo de códigos postales (postal_codes es su revisión: la 8, del 22 de enero de 2026), pero nunca ha publicado una revisión del de colonias. En su archivo del 29 de octubre de 2026 (catCFDI_V_4_20261029.xls), c_Colonia sigue en la revisión 0, sin fecha de publicación y vigente desde el 1 de enero de 2022, cuando entró en vigor CFDI 4.0. Por eso settlements es "0" y settlements_revised es false.

Mientras tanto, SEPOMEX sigue dando de alta colonias. Las que agregó después de que el SAT armó su catálogo pueden no tener c_Colonia: aparecen en settlements_missing_in_sat y, al validarlas, con sat.status: "no_key" (o candidate, si el SAT tiene una parecida). No es un error de Colonix ni de tu cliente: la colonia existe, pero el SAT todavía no le da clave. Si el SAT publica una revisión, settlements_revised pasa a true en la siguiente actualización.

4. La hora de la factura y el estímulo fronterizo

Section titled “4. La hora de la factura y el estímulo fronterizo”

La Fecha del CFDI va en la hora local del lugar donde se expide (el código postal de LugarExpedicion). Para calcularla no necesitas interpretar textos como “Marzo, Segundo domingo, 02:00”: time_zone.iana es el nombre de la zona horaria real del código postal en la base de husos horarios que usan todos los lenguajes, y con él tu biblioteca calcula la hora exacta de ese momento.

// Node: la hora local de un código postal, con su zona de time_zone.iana
new Date().toLocaleString("sv-SE", { timeZone: "America/Ciudad_Juarez" }).replace(" ", "T");
# Python: lo mismo con zoneinfo (en Windows, instala antes el paquete tzdata: pip install tzdata)
from datetime import datetime
from zoneinfo import ZoneInfo
datetime.now(ZoneInfo("America/Ciudad_Juarez")).strftime("%Y-%m-%dT%H:%M:%S")

En casi todo el país lo que publica el SAT coincide con la hora real (matches_sat: true). La excepción son dos franjas de la frontera de Chihuahua, donde el catálogo del SAT sigue la letra de la Ley de los Husos Horarios (reformada el 29 de noviembre de 2022) y la gente usa la hora de las ciudades vecinas de Estados Unidos:

Municipios Según el catálogo del SAT Hora real
Juárez, Ascensión, Janos, Guadalupe y Praxedis G. Guerrero −6 en invierno y −7 en verano −7 en invierno y −6 en verano, como El Paso (America/Ciudad_Juarez)
Ojinaga, Coyame del Sotol y Manuel Benavides −6 todo el año −6 en invierno y −5 en verano, como Presidio (America/Ojinaga)

Un caso real, el 32000 (Ciudad Juárez):

GET /v1/sat/postal-codes/32000 (fragmento)
{
"postal_code": "32000",
"border_stimulus": "north",
"border_stimulus_decree": {
"published": "2025-12-31",
"valid_until": "2026-12-31",
"requires_sat_notice": true,
"source": "https://dof.gob.mx/nota_detalle.php?codigo=5777697&fecha=31/12/2025"
},
"time_zone": {
"description": "Tiempo del Centro en Frontera",
"utc_offset_summer": -7,
"utc_offset_winter": -6,
"dst_start": "Marzo, Segundo domingo, 02:00",
"dst_end": "Noviembre, Primer domingo, 02:00",
"iana": "America/Ciudad_Juarez",
"utc_offset_standard": -7,
"utc_offset_dst": -6,
"matches_sat": false
}
}

En una pequeña parte de los códigos postales de Chihuahua que solo están en el catálogo del SAT, sin municipio, no se puede saber si son de la franja de Ojinaga: ahí iana y los demás campos de la hora real vienen en null y quedan los del SAT.

El estímulo fiscal de la región fronteriza

Section titled “El estímulo fiscal de la región fronteriza”

border_stimulus dice si el código postal está en la región fronteriza norte o sur según el SAT, pero el código postal no basta para facturar con el estímulo (la tasa de IVA reducida):

  • El contribuyente debe presentar ante el SAT el aviso para aplicarlo (requires_sat_notice) y cumplir sus requisitos, como tener su domicilio fiscal, sucursal o establecimiento en la región y no estar en las listas de los artículos 69 y 69-B del Código Fiscal. Hay actos a los que no aplica, como la venta de inmuebles o los contenidos digitales. Los detalles están en el minisitio del SAT.
  • El decreto tiene fecha de término: border_stimulus_decree.valid_until. Después de esa fecha el estímulo deja de aplicar, salvo que un decreto nuevo lo prorrogue; cuando se publica una prórroga en el DOF, Colonix actualiza la fecha.

Usa border_stimulus para saber si un cliente podría tener el estímulo, y el aviso ante el SAT de ese cliente para decidir si se lo aplicas.