Datos del SAT de un código postal (CFDI 4.0)
/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ámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
codeen la rutaobligatorio | texto | 5 dígitos | Código postal de 5 dígitos. |
as_ofen la consulta | fecha | — | 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"const url = new URL("https://colonix.silgaru.mx/v1/sat/postal-codes/22000");
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/sat/postal-codes/22000", 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/sat/postal-codes/22000";$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": "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
| 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). |
data_version | texto | Versión del dato |
in_sat | booleano | El código postal está en c_CodigoPostal (válido para CFDI) |
in_sepomex | booleano | El código postal está en el catálogo de SEPOMEX |
state | objeto o null | Clave del estado en el SAT y en el INEGI, o null si no está en el SAT |
state.sat_codeno siempre viene | texto | Clave del SAT (AGU, CMX...) |
state.idno siempre viene | texto | Clave INEGI de 2 dígitos |
state.nameno siempre viene | texto | Nombre |
municipality | objeto o null | Clave del SAT con su nombre, o null |
municipality.sat_codeno siempre viene | texto | Clave del SAT |
municipality.nameno siempre viene | texto o null | Nombre |
locality | objeto o null | Clave del SAT con su nombre, o null |
locality.sat_codeno siempre viene | texto | Clave del SAT |
locality.nameno siempre viene | texto o null | Nombre |
border_stimulus | texto o null | Estímulo fiscal de la región fronteriza: north (norte), south (sur) o null. El código postal no basta para aplicarlo: ver border_stimulus_decreenorthsouth |
border_stimulus_decree | objeto o null | Vigencia 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.published | fecha | Fecha de publicación en el DOF del decreto que fija la vigencia actual |
border_stimulus_decree.valid_until | fecha | Último día en que aplica el estímulo |
border_stimulus_decree.requires_sat_notice | booleano | El contribuyente debe presentar el aviso ante el SAT para aplicarlo: el código postal no basta |
border_stimulus_decree.source | texto | El decreto en el DOF |
time_zone | objeto o null | Huso 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.description | texto | Nombre del huso horario (en español, como lo publica el SAT) |
time_zone.utc_offset_summer | número o null | Diferencia con UTC en verano según el SAT (horas) |
time_zone.utc_offset_winter | número o null | Diferencia con UTC en invierno según el SAT (horas) |
time_zone.dst_start | texto o null | Cuándo empieza el horario de verano según el SAT (en español), o null |
time_zone.dst_end | texto o null | Cuándo termina el horario de verano según el SAT (en español), o null |
time_zone.iana | texto o null | Zona 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_standard | número o null | Diferencia real con UTC fuera del horario de verano (horas), o null |
time_zone.utc_offset_dst | número o null | Diferencia real con UTC en horario de verano (horas), o null si la zona no tiene |
time_zone.matches_sat | booleano o null | Las diferencias reales son las que publica el SAT; null si no hay qué comparar |
settlements | lista de objetos | Colonias del SAT (c_Colonia) del código postal |
settlements[].c_colonia | texto | Clave de colonia del SAT (c_Colonia), única dentro del código postal |
settlements[].name | texto | Nombre en el catálogo del SAT |
settlements[].settlement_id | texto o null | Asentamiento de SEPOMEX con el mismo nombre o uno equivalente (ver match), o null |
settlements[].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 |
settlements[].sepomex_name | texto o null | Nombre de ese asentamiento en SEPOMEX, o null |
settlements[].sepomex_candidate | objeto o null | Sin asentamiento de SEPOMEX: el del mismo código postal que probablemente es el mismo lugar, o null |
settlements_missing_in_sat | lista de objetos | Asentamientos 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[].id | texto | Clave del asentamiento |
settlements_missing_in_sat[].name | texto | Nombre del asentamiento |
settlements_missing_in_sat[].sat_candidate | objeto o null | La colonia del SAT del mismo código postal que probablemente es el mismo lugar (confírmala antes de usar su clave), o null |
sat_revision | objeto | Versión del archivo de catálogos del SAT que se usó. |
sat_revision.file | texto | Nombre del archivo del SAT |
sat_revision.postal_codes | texto | Revisión de c_CodigoPostal |
sat_revision.settlements | texto | Revisión de c_Colonia; "0" es el catálogo original, sin revisiones |
sat_revision.settlements_revised | booleano | Si 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.published | fecha | Fecha 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).
| 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). |
in_sat | booleano | El código postal estaba en c_CodigoPostal en esa fecha (válido para CFDI) |
state | objeto o null | Clave del estado del SAT y clave del INEGI, o null si no estaba en c_CodigoPostal |
state.sat_code | texto | Clave del SAT (AGU, CMX...) |
state.id | texto | Clave INEGI de 2 dígitos |
state.name | texto | Nombre |
municipality | objeto o null | Clave del SAT con su nombre, o null |
municipality.sat_codeno siempre viene | texto | Clave del SAT |
municipality.nameno siempre viene | texto o null | Nombre |
locality | objeto o null | Clave del SAT con su nombre, o null |
locality.sat_codeno siempre viene | texto | Clave del SAT |
locality.nameno siempre viene | texto o null | Nombre |
border_stimulus | texto o null | Estímulo fiscal de la región fronteriza en esa fecha: north (norte), south (sur) o nullnorthsouth |
border_stimulus_decree | objeto o null | El 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.published | fecha | Fecha de publicación en el DOF del decreto que fija la vigencia |
border_stimulus_decree.valid_until | fecha | Último día en que aplica el estímulo |
border_stimulus_decree.requires_sat_notice | booleano | El contribuyente debe presentar el aviso ante el SAT para aplicarlo: el código postal no basta |
border_stimulus_decree.source | texto | El decreto en el DOF |
time_zone | objeto o null | Huso 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.description | texto | Nombre del huso horario (en español, como lo publica el SAT) |
time_zone.utc_offset_summer | número o null | Diferencia con UTC en verano según el SAT (horas) |
time_zone.utc_offset_winter | número o null | Diferencia con UTC en invierno según el SAT (horas) |
time_zone.dst_start | texto o null | Cuándo empieza el horario de verano según el SAT (en español), o null |
time_zone.dst_end | texto o null | Cuándo termina el horario de verano según el SAT (en español), o null |
time_zone.iana | texto o null | Zona horaria real (nombre en la base tz de IANA), o null si no se puede determinar |
time_zone.utc_offset_standard | número o null | Diferencia real con UTC fuera del horario de verano (horas), o null |
time_zone.utc_offset_dst | número o null | Diferencia real con UTC en horario de verano (horas), o null si la zona no tiene |
time_zone.matches_sat | booleano o null | Las diferencias reales son las que publica el SAT; null si no hay qué comparar |
settlements | lista de objetos | Colonias del SAT (c_Colonia) del código postal en esa fecha, por nombre |
settlements[].c_colonia | texto | Clave de colonia del SAT (c_Colonia), única dentro del código postal |
settlements[].name | texto | Nombre en el catálogo del SAT |
as_of | objeto | En qué se basa la respuesta |
as_of.date | fecha | La fecha que pediste |
as_of.sat_revision | objeto | Revisión del catálogo de códigos postales del SAT (c_CodigoPostal) que da la respuesta |
as_of.effective_since | fecha | Fecha 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_version | texto | Versió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.
| 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). |
404 | El 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. |
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