Ir al contenido

Mantener tu catálogo al día

Los códigos postales y las colonias cambian: SEPOMEX da de alta colonias nuevas, da de baja otras y corrige nombres. Si guardas direcciones o una lista de colonias en tu sistema, Colonix te dice exactamente qué cambió desde la última vez, para que actualices solo eso.

Necesitas: plan Negocio para /v1/changes. El historial de un solo código postal (/v1/postal-codes/{code}/history) está en todos los planes.

  1. Guarda el data_version de la última respuesta que usaste para llenar tu base.
  2. Revisa de vez en cuando si hay una versión nueva: GET /v1/meta (o el X-Data-Version de cualquier respuesta). El catálogo se revisa cada semana; revisar una vez al día es suficiente.
  3. Si cambió, pide GET /v1/changes?since=<tu versión>, recorre todas las páginas y aplica cada cambio.
  4. Al terminar, guarda el data_version nuevo.

Cada elemento de data es un cambio, del más antiguo al más reciente:

GET /v1/changes?since=2026.10.05-936974de (un elemento)
{
"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" }
}
}
Campo Qué es
version La versión del dato en la que se publicó el cambio
entity Qué cambió: postal_code (un código postal) o settlement (un asentamiento) de SEPOMEX, o sat_postal_code y sat_settlement (un código postal o una colonia del catálogo del SAT)
change added (alta), removed (baja) o modified (cambio)
id La clave: el código postal, el id estable del asentamiento o, en una colonia del SAT, el código postal y su c_Colonia (06700/0947)
source_date La fecha desde la que una consulta con as_of ve el cambio
changed_fields En un modified, qué campos cambiaron (por ejemplo, ["office"] o ["name"])
before, after El registro antes y después: before es null en un alta y after es null en una baja

Dentro de una versión llegan primero los códigos postales y los asentamientos de SEPOMEX, y después los códigos postales y las colonias del SAT, cada grupo ordenado por clave. Un asentamiento que cambia de municipio cambia de clave: llega como una baja y un alta. Si solo guardas uno de los dos catálogos, salta las entidades del otro, como hace el ejemplo de abajo.

Los cambios del SAT llegan cuando el SAT publica una revisión de su catálogo: en un código postal, sus claves de estado, municipio o localidad, el estímulo fronterizo o el huso horario (changed_fields dice cuáles); en una colonia, su nombre, o si se agregó o se quitó.

El id de un asentamiento (07078-0020) es su clave de SEPOMEX: el estado, el municipio y un número. Sirve para seguir la misma colonia de una versión a otra porque no cambia cuando SEPOMEX le corrige el nombre o la mueve a otro código postal. Solo cambia si pasa a otro municipio, y entonces llega como una baja y un alta.

Eso quiere decir que, con el mismo id, el nombre y el código postal pueden ser otros. Pasó el 15 de octubre de 2026 en San Cristóbal de las Casas:

GET /v1/postal-codes/29267/history (un elemento, recortado)
{
"version": "2026.10.15-fb39a8da",
"entity": "settlement",
"change": "modified",
"id": "07078-0020",
"changed_fields": ["postal_code", "name"],
"before": { "id": "07078-0020", "postal_code": "29267", "name": "Jubilados y Pensionados" },
"after": { "id": "07078-0020", "postal_code": "29263", "name": "San Vicente Ferrer" }
}

No es raro: de los 82 cambios a asentamientos que conservaron su id desde que empezó el historial (el 5 de octubre de 2026), 23 le cambiaron solo el nombre (a dos, solo un acento), 28 solo el código postal y 4 las dos cosas. SEPOMEX no dice si es la misma colonia con otro nombre o si la clave pasó a otro lugar, así que Colonix tampoco puede saberlo. Por eso:

  • Guarda el id junto con el nombre y el código postal de la dirección, no el id solo. Si muestras el nombre que tiene hoy el id, a tu usuario le aparece otra colonia sin que nadie se entere.
  • Cuando un cambio modified traiga name o postal_code en changed_fields, la dirección guardada ya no dice lo mismo que el catálogo: vuelve a validarla con /v1/validate/postal-code-settlement o pídele a tu usuario que la confirme. No la cambies en silencio: un paquete o una factura con otro código postal va a otro lugar.
  • Si solo guardaste el nombre y el código postal, la validación con el nombre de antes te dice qué pasó: “Jubilados y Pensionados” en el 29267 responde not_found con history (renamed_and_moved, la versión y la colonia de hoy en history.settlement).

El ejemplo de abajo junta esas direcciones para revisarlas.

Este script en Python mantiene una tabla de asentamientos en SQLite. La primera vez, guarda la versión con la que llenaste la tabla; después, cada vez que lo corras, aplica solo los cambios.

actualizar.py
import os
import sqlite3
import requests
API = "https://colonix.silgaru.mx"
SESION = requests.Session()
SESION.headers["x-api-key"] = os.environ["COLONIX_API_KEY"]
db = sqlite3.connect("direcciones.db")
db.execute("CREATE TABLE IF NOT EXISTS asentamientos (id TEXT PRIMARY KEY, postal_code TEXT, name TEXT)")
db.execute("CREATE TABLE IF NOT EXISTS estado (clave TEXT PRIMARY KEY, valor TEXT)")
def consultar(ruta, **params):
res = SESION.get(API + ruta, params=params, timeout=10)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['type']}: {data['detail']}")
return data
def actualizar():
fila = db.execute("SELECT valor FROM estado WHERE clave = 'data_version'").fetchone()
if fila is None:
raise SystemExit("Guarda primero en 'estado' el data_version con el que llenaste la tabla")
mia = fila[0]
vigente = consultar("/v1/meta")["data_version"]
if vigente == mia:
return "Al día"
cursor, aplicados, revisar = None, 0, []
with db: # una sola transacción: o se aplica todo, o nada
while True:
params = {"since": mia, "limit": 500}
if cursor:
params["cursor"] = cursor
pagina = consultar("/v1/changes", **params)
for c in pagina["data"]:
if c["entity"] != "settlement":
continue # este ejemplo solo guarda asentamientos
if c["change"] == "removed":
db.execute("DELETE FROM asentamientos WHERE id = ?", (c["id"],))
else: # added o modified
a = c["after"]
db.execute(
"INSERT OR REPLACE INTO asentamientos VALUES (?, ?, ?)",
(a["id"], a["postal_code"], a["name"]),
)
if {"name", "postal_code"} & set(c["changed_fields"]):
b = c["before"] # mismo id, otro nombre u otro CP: hay que revisar
revisar.append(f"{b['name']} ({b['postal_code']}) → {a['name']} ({a['postal_code']})")
aplicados += 1
cursor = pagina["next_cursor"]
if not cursor:
break
db.execute(
"INSERT OR REPLACE INTO estado VALUES ('data_version', ?)", (pagina["data_version"],)
)
for r in revisar:
print("Vuelve a validar las direcciones de", r)
return f"{aplicados} cambios aplicados; ahora en {pagina['data_version']}"
print(actualizar())

Tres cosas que lo hacen seguro:

  • Guarda la versión nueva al final, en la misma transacción que los cambios: si algo falla a la mitad, la próxima vez empiezas otra vez desde tu versión anterior.
  • Si el catálogo se actualiza mientras recorres las páginas, recibes cursor-expired: la transacción se deshace y basta con volver a correrlo.
  • La versión nueva es la de las respuestas (data_version de la última página), no la del último cambio.

Para saber qué le pasó a un código postal en particular (por ejemplo, porque una dirección guardada ya no valida), GET /v1/postal-codes/{code}/history da todos sus cambios y los de sus asentamientos, incluidos los que se movieron a otro código postal. Funciona también con códigos postales que ya no existen, mientras hayan existido después de history_since. Con include=sat (plan Básico o superior) suma los cambios del código postal en el catálogo del SAT.

Para ver cómo estaba un código postal en una fecha, en lugar de qué le cambió, usa as_of.