Ir al contenido

Historial de cambios de un código postal

GET/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ámetroTipoValores aceptadosDescripción
codeen la rutaobligatoriotexto
5 dígitos
Código postal de 5 dígitos.
includeen la consultalista 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"

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": "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

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).
history_sincefechaFecha de la primera versión del dato registrada
sat_history_sinceno siempre vienefecha o nullSolo con include=sat: fecha desde la que se registra el historial del SAT (ver /v1/meta)
datalista de objetos
data[].versiontextoVersión del dato que publicó el cambio
data[].source_datefechaFecha 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[].entitytextoQué cambió: en SEPOMEX (postal_code, settlement) o en el catálogo del SAT (sat_postal_code, sat_settlement)
postal_codesettlementsat_postal_codesat_settlement
data[].changetextoTipo de cambio
addedremovedmodified
data[].idtextoCódigo postal, clave del asentamiento o, en sat_settlement, el código postal y la c_Colonia (06700/0947)
data[].changed_fieldslista de textoCampos que difieren entre before y after (vacío salvo en modified)
data[].beforeobjeto o nullValor antes del cambio; null si se agregó
data[].afterobjeto o nullValor después del cambio; null si se eliminó
data_versiontextoVersión del dato

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.