Ir al contenido

Datos del SAT de un código postal (CFDI 4.0)

GET/v1/sat/postal-codes/{code}Planes de pago (Básico o superior); los códigos postales de demostración, en todos los planes

¿Qué hace?

Todo lo que dicen los catálogos del SAT sobre un código postal: las claves para CFDI 4.0 y sus complementos, como Carta Porte (estado, municipio, localidad y colonias), el estímulo de la región fronteriza con la vigencia de su decreto, y el huso horario: como lo publica el SAT y el real (iana), que difieren en las franjas fronterizas de Chihuahua (matches_sat).

También indica qué asentamientos de SEPOMEX faltan en el catálogo del SAT (no tienen c_Colonia). Funciona con códigos postales que solo están en uno de los catálogos (in_sat, in_sepomex). Ningún catálogo se corrige con el otro.

Un asentamiento de SEPOMEX y una colonia del SAT del mismo código postal son el mismo asentamiento cuando sus nombres son iguales o equivalentes (las reglas de la validación: abreviaturas, tipo de asentamiento al inicio, espacios y artículos; match dice cuál, y sepomex_name muestra el nombre en SEPOMEX). Cuando los nombres no coinciden pero probablemente son el mismo lugar, cada lado sugiere el otro (sat_candidate, sepomex_candidate), con qué tanto se parecen los nombres, qué los distingue y si sus claves tienen el mismo número. Una sugerencia nunca es la clave: el asentamiento de SEPOMEX sigue en settlements_missing_in_sat hasta que lo confirmes.

Con as_of obtienes lo que decía el catálogo del SAT en una fecha pasada, por ejemplo la de una factura que vas a sustituir o revisar: si el código postal estaba en c_CodigoPostal (in_sat), sus claves, estímulo fronterizo, huso horario y colonias de ese día. as_of.sat_revision dice qué revisión del catálogo da la respuesta y as_of.effective_since, desde cuándo aplica. Las fechas van desde sat_history_since (ver /v1/meta) hasta hoy; una anterior responde 400 /errors/as-of-out-of-range. Un código postal que no estaba en ningún catálogo del SAT responde 404. Con as_of la respuesta no tiene el lado de SEPOMEX (ni emparejamiento, ni in_sepomex, ni settlements_missing_in_sat): describe solo el catálogo del SAT. border_stimulus_decree es el decreto vigente en esa fecha, o null si era uno anterior.

La petición

ParámetroTipoValores aceptadosDescripción
codeen la rutaobligatoriotexto
5 dígitos
Código postal de 5 dígitos.
as_ofen la consultafecha—Fecha (AAAA-MM-DD) para obtener lo que decía el catálogo del SAT ese día, desde sat_history_since (ver /v1/meta) hasta hoy en la Ciudad de México.

Ejemplo

curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/sat/postal-codes/22000"

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": "22000",
"in_sat": true,
"in_sepomex": true,
"state": {
"sat_code": "BCN",
"id": "02",
"name": "Baja California"
},
"municipality": {
"sat_code": "004",
"name": "Tijuana"
},
"locality": {
"sat_code": "04",
"name": "Tijuana"
},
"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 Noroeste",
"utc_offset_summer": -7,
"utc_offset_winter": -8,
"dst_start": "Marzo, Segundo domingo, 02:00",
"dst_end": "Noviembre, Primer domingo, 02:00",
"iana": "America/Tijuana",
"utc_offset_standard": -8,
"utc_offset_dst": -7,
"matches_sat": true
},
"settlements": [
{
"c_colonia": "0528",
"name": "Zona Centro",
"settlement_id": "02004-0528",
"match": "exact",
"sepomex_name": "Zona Centro",
"sepomex_candidate": null
},
{
"c_colonia": "0530",
"name": "Zona Este",
"settlement_id": "02004-0530",
"match": "exact",
"sepomex_name": "Zona Este",
"sepomex_candidate": null
},
{
"c_colonia": "1824",
"name": "Zona Norte",
"settlement_id": "02004-1824",
"match": "exact",
"sepomex_name": "Zona Norte",
"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"
}

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).
data_versiontextoVersión del dato
in_satbooleanoEl código postal está en c_CodigoPostal (válido para CFDI)
in_sepomexbooleanoEl código postal está en el catálogo de SEPOMEX
stateobjeto o nullClave del estado en el SAT y en el INEGI, o null si no está en el SAT
state.sat_codeno siempre vienetextoClave del SAT (AGU, CMX...)
state.idno siempre vienetextoClave INEGI de 2 dígitos
state.nameno siempre vienetextoNombre
municipalityobjeto o nullClave del SAT con su nombre, o null
municipality.sat_codeno siempre vienetextoClave del SAT
municipality.nameno siempre vienetexto o nullNombre
localityobjeto o nullClave del SAT con su nombre, o null
locality.sat_codeno siempre vienetextoClave del SAT
locality.nameno siempre vienetexto o nullNombre
border_stimulustexto o nullEstímulo fiscal de la región fronteriza: north (norte), south (sur) o null. El código postal no basta para aplicarlo: ver border_stimulus_decree
northsouth
border_stimulus_decreeobjeto o nullVigencia del decreto del estímulo fiscal de la región fronteriza, o null si el código postal no está en una región fronteriza. El contribuyente debe presentar un aviso ante el SAT (requires_sat_notice) y cumplir sus requisitos; después de valid_until el estímulo deja de aplicar, salvo que un decreto nuevo lo prorrogue
border_stimulus_decree.publishedfechaFecha de publicación en el DOF del decreto que fija la vigencia actual
border_stimulus_decree.valid_untilfechaÚltimo día en que aplica el estímulo
border_stimulus_decree.requires_sat_noticebooleanoEl contribuyente debe presentar el aviso ante el SAT para aplicarlo: el código postal no basta
border_stimulus_decree.sourcetextoEl decreto en el DOF
time_zoneobjeto o nullHuso horario como lo publica el SAT, más el huso real (iana y sus diferencias con UTC), o null si no está en el SAT. En las franjas fronterizas de Chihuahua el SAT sigue la letra de la ley de husos horarios y difiere de la hora que se usa en la práctica (matches_sat: false)
time_zone.descriptiontextoNombre del huso horario (en español, como lo publica el SAT)
time_zone.utc_offset_summernúmero o nullDiferencia con UTC en verano según el SAT (horas)
time_zone.utc_offset_winternúmero o nullDiferencia con UTC en invierno según el SAT (horas)
time_zone.dst_starttexto o nullCuándo empieza el horario de verano según el SAT (en español), o null
time_zone.dst_endtexto o nullCuándo termina el horario de verano según el SAT (en español), o null
time_zone.ianatexto o nullZona horaria real (nombre de la base tz de IANA), para calcular la hora local con cualquier biblioteca de zonas horarias; null si no se puede determinar
time_zone.utc_offset_standardnúmero o nullDiferencia real con UTC fuera del horario de verano (horas), o null
time_zone.utc_offset_dstnúmero o nullDiferencia real con UTC en horario de verano (horas), o null si la zona no tiene
time_zone.matches_satbooleano o nullLas diferencias reales son las que publica el SAT; null si no hay qué comparar
settlementslista de objetosColonias del SAT (c_Colonia) del código postal
settlements[].c_coloniatextoClave de colonia del SAT (c_Colonia), única dentro del código postal
settlements[].nametextoNombre en el catálogo del SAT
settlements[].settlement_idtexto o nullAsentamiento de SEPOMEX con el mismo nombre o uno equivalente (ver match), o null
settlements[].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
settlements[].sepomex_nametexto o nullNombre de ese asentamiento en SEPOMEX, o null
settlements[].sepomex_candidateobjeto o nullSin asentamiento de SEPOMEX: el del mismo código postal que probablemente es el mismo lugar, o null
settlements_missing_in_satlista de objetosAsentamientos de SEPOMEX del código postal sin clave del SAT: ninguna colonia del SAT tiene el mismo nombre ni uno equivalente, o las que lo tienen ya son de otro asentamiento con ese nombre
settlements_missing_in_sat[].idtextoClave del asentamiento
settlements_missing_in_sat[].nametextoNombre del asentamiento
settlements_missing_in_sat[].sat_candidateobjeto o nullLa colonia del SAT del mismo código postal que probablemente es el mismo lugar (confírmala antes de usar su clave), o null
sat_revisionobjetoVersión del archivo de catálogos del SAT que se usó.
sat_revision.filetextoNombre del archivo del SAT
sat_revision.postal_codestextoRevisión de c_CodigoPostal
sat_revision.settlementstextoRevisión de c_Colonia; "0" es el catálogo original, sin revisiones
sat_revision.settlements_revisedbooleanoSi el SAT ha publicado alguna vez una revisión de c_Colonia. Si es false, el catálogo de colonias es el que el SAT publicó cuando entró en vigor, así que las colonias que SEPOMEX agregó después pueden no tener clave del SAT (no_key en la validación).
sat_revision.publishedfechaFecha de publicación de c_CodigoPostal

Campos con as_of

Lo que decía el catálogo del SAT de un código postal en la fecha as_of (sin el lado de SEPOMEX).

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).
in_satbooleanoEl código postal estaba en c_CodigoPostal en esa fecha (válido para CFDI)
stateobjeto o nullClave del estado del SAT y clave del INEGI, o null si no estaba en c_CodigoPostal
state.sat_codetextoClave del SAT (AGU, CMX...)
state.idtextoClave INEGI de 2 dígitos
state.nametextoNombre
municipalityobjeto o nullClave del SAT con su nombre, o null
municipality.sat_codeno siempre vienetextoClave del SAT
municipality.nameno siempre vienetexto o nullNombre
localityobjeto o nullClave del SAT con su nombre, o null
locality.sat_codeno siempre vienetextoClave del SAT
locality.nameno siempre vienetexto o nullNombre
border_stimulustexto o nullEstímulo fiscal de la región fronteriza en esa fecha: north (norte), south (sur) o null
northsouth
border_stimulus_decreeobjeto o nullEl decreto del estímulo fronterizo vigente en esa fecha (los mismos campos que sin as_of), o null si el código postal no estaba en una región fronteriza o el decreto vigente entonces era uno anterior
border_stimulus_decree.publishedfechaFecha de publicación en el DOF del decreto que fija la vigencia
border_stimulus_decree.valid_untilfechaÚltimo día en que aplica el estímulo
border_stimulus_decree.requires_sat_noticebooleanoEl contribuyente debe presentar el aviso ante el SAT para aplicarlo: el código postal no basta
border_stimulus_decree.sourcetextoEl decreto en el DOF
time_zoneobjeto o nullHuso horario como lo publicaba el SAT en esa fecha, más el real (los mismos campos que sin as_of), o null si no estaba en c_CodigoPostal
time_zone.descriptiontextoNombre del huso horario (en español, como lo publica el SAT)
time_zone.utc_offset_summernúmero o nullDiferencia con UTC en verano según el SAT (horas)
time_zone.utc_offset_winternúmero o nullDiferencia con UTC en invierno según el SAT (horas)
time_zone.dst_starttexto o nullCuándo empieza el horario de verano según el SAT (en español), o null
time_zone.dst_endtexto o nullCuándo termina el horario de verano según el SAT (en español), o null
time_zone.ianatexto o nullZona horaria real (nombre en la base tz de IANA), o null si no se puede determinar
time_zone.utc_offset_standardnúmero o nullDiferencia real con UTC fuera del horario de verano (horas), o null
time_zone.utc_offset_dstnúmero o nullDiferencia real con UTC en horario de verano (horas), o null si la zona no tiene
time_zone.matches_satbooleano o nullLas diferencias reales son las que publica el SAT; null si no hay qué comparar
settlementslista de objetosColonias del SAT (c_Colonia) del código postal en esa fecha, por nombre
settlements[].c_coloniatextoClave de colonia del SAT (c_Colonia), única dentro del código postal
settlements[].nametextoNombre en el catálogo del SAT
as_ofobjetoEn qué se basa la respuesta
as_of.datefechaLa fecha que pediste
as_of.sat_revisionobjetoRevisión del catálogo de códigos postales del SAT (c_CodigoPostal) que da la respuesta
as_of.effective_sincefechaFecha desde la que aplica este contenido: la de publicación de la revisión o, si el SAT cambió el contenido sin una revisión nueva, la del archivo de SEPOMEX que lo trajo
data_versiontextoVersión del dato de esta respuesta (la vigente)

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).
404El recurso no existe (/errors/postal-code-not-found, /errors/state-not-found, /errors/municipality-not-found, /errors/location-not-covered o /errors/route-not-found). No cuenta para tu cuota.
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.