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.
Cómo funciona
Section titled “Cómo funciona”- Guarda el
data_versionde la última respuesta que usaste para llenar tu base. - Revisa de vez en cuando si hay una versión nueva:
GET /v1/meta(o elX-Data-Versionde cualquier respuesta). El catálogo se revisa cada semana; revisar una vez al día es suficiente. - Si cambió, pide
GET /v1/changes?since=<tu versión>, recorre todas las páginas y aplica cada cambio. - Al terminar, guarda el
data_versionnuevo.
Los cambios
Section titled “Los cambios”Cada elemento de data es un cambio, del más antiguo al más reciente:
{ "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ó.
Si guardas el id de una colonia
Section titled “Si guardas el id de una colonia”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:
{ "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
idjunto con el nombre y el código postal de la dirección, no elidsolo. Si muestras el nombre que tiene hoy elid, a tu usuario le aparece otra colonia sin que nadie se entere. - Cuando un cambio
modifiedtraiganameopostal_codeenchanged_fields, la dirección guardada ya no dice lo mismo que el catálogo: vuelve a validarla con/v1/validate/postal-code-settlemento 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
29267respondenot_foundconhistory(renamed_and_moved, la versión y la colonia de hoy enhistory.settlement).
El ejemplo de abajo junta esas direcciones para revisarlas.
Un ejemplo completo
Section titled “Un ejemplo completo”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.
import osimport sqlite3import 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_versionde la última página), no la del último cambio.
Un solo código postal
Section titled “Un solo código postal”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.
© 2026 Silgaru