Historial de cambios de un código postal
/v1/postal-codes/{code}/historyTodos los planes; include=sat, planes de pago (Básico o superior), y los códigos postales de demostración en todos los planes¿Qué hace?
Qué le pasó a un código postal con el tiempo: asentamientos que se agregaron, se eliminaron o cambiaron de nombre, y los que se movieron desde o hacia él. Sirve cuando una dirección que guardaste ya no valida.
Todos los cambios registrados del código postal y de sus asentamientos, del más antiguo al más reciente. También funciona con códigos postales que ya no existen, mientras hayan existido después de history_since (ver /v1/meta). Un data vacío significa que no hubo cambios desde history_since. Sin paginar.
Con include=sat trae también los cambios del código postal y de sus colonias en el catálogo del SAT (sat_postal_code, sat_settlement) desde sat_history_since, intercalados en orden: cuando el SAT cambió una clave, el estímulo fronterizo o el huso horario del código postal, o agregó, quitó o renombró una de sus colonias (c_Colonia).
La petición
| Parámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
codeen la rutaobligatorio | texto | 5 dígitos | Código postal de 5 dígitos. |
includeen la consulta | lista de textoseparados por comas | sat | sat: también los cambios en el catálogo del SAT (planes de pago: Básico o superior; los códigos postales de demostración, en todos los planes). |
Ejemplo
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/postal-codes/20286/history"const url = new URL("https://colonix.silgaru.mx/v1/postal-codes/20286/history");
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/postal-codes/20286/history", 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/postal-codes/20286/history";$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": "20286", "history_since": "2026-10-05", "data": [ { "version": "2026.10.15-fb39a8da", "source_date": "2026-10-15", "entity": "settlement", "change": "added", "id": "01001-0585", "changed_fields": [], "before": null, "after": { "id": "01001-0585", "postal_code": "20286", "name": "Reserva de Sonoma", "type": "Fraccionamiento", "zone": "Urbano", "city": "Aguascalientes", "state": { "id": "01", "name": "Aguascalientes" }, "municipality": { "id": "001", "name": "Aguascalientes" } } } ], "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). |
history_since | fecha | Fecha de la primera versión del dato registrada |
sat_history_sinceno siempre viene | fecha o null | Solo con include=sat: fecha desde la que se registra el historial del SAT (ver /v1/meta) |
data | lista de objetos | |
data[].version | texto | Versión del dato que publicó el cambio |
data[].source_date | fecha | Fecha desde la que as_of ve el cambio: la del archivo de SEPOMEX o, en los cambios del SAT, la fecha de publicación de la revisión del SAT que lo trajo (si el SAT cambió el contenido sin una revisión nueva, la del archivo de SEPOMEX de la versión que lo trajo). |
data[].entity | texto | Qué cambió: en SEPOMEX (postal_code, settlement) o en el catálogo del SAT (sat_postal_code, sat_settlement)postal_codesettlementsat_postal_codesat_settlement |
data[].change | texto | Tipo de cambioaddedremovedmodified |
data[].id | texto | Código postal, clave del asentamiento o, en sat_settlement, el código postal y la c_Colonia (06700/0947) |
data[].changed_fields | lista de texto | Campos que difieren entre before y after (vacío salvo en modified) |
data[].before | objeto o null | Valor antes del cambio; null si se agregó |
data[].after | objeto o null | Valor después del cambio; null si se eliminó |
data_version | texto | Versión del dato |
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