Cambios desde una versión del dato
/v1/changesNegocio y Enterprise¿Qué hace?
Qué cambió en el catálogo desde la versión que tienes, para actualizar solo eso en tu propia base de datos en lugar de volver a consultar todo.
Cambios publicados después de la versión del dato since, del más antiguo al más reciente (por versión; dentro de cada versión, códigos postales de SEPOMEX, asentamientos de SEPOMEX, códigos postales del SAT y colonias del SAT, cada uno por clave). Guarda el data_version que tienes, llama a este endpoint con él, aplica los cambios y guarda el data_version nuevo. Paginada: sigue next_cursor. Un data vacío con next_cursor: null significa que estás al día. Si solo guardas uno de los catálogos, omite las entidades del otro (entity).
La petición
| Parámetro | Tipo | Valores aceptados | Descripción |
|---|---|---|---|
sinceen la consultaobligatorio | texto | — | Versión del dato que ya tienes (el data_version de una respuesta anterior). Debe ser history_since o posterior; si no, 400 /errors/unknown-version. |
limiten la consulta | entero | de 1 a 500 por omisión: 50 | Tamaño de página (1–500, 50 por omisión). No existe un valor "sin límite": para obtener todos los resultados, sigue next_cursor hasta que sea null. |
cursoren la consulta | texto | — | Valor opaco de next_cursor de la página anterior, enviado tal cual. Solo vale para la versión del dato que lo emitió (si no, 400 /errors/cursor-expired). |
Ejemplo
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/changes?since=2026.10.05-936974de&limit=2"const url = new URL("https://colonix.silgaru.mx/v1/changes");url.searchParams.set("since", "2026.10.05-936974de");url.searchParams.set("limit", "2");
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/changes", params={"since": "2026.10.05-936974de", "limit": "2"}, 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/changes?" . http_build_query(["since" => "2026.10.05-936974de", "limit" => "2"]);$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.
{ "data": [ { "version": "2026.10.15-fb39a8da", "source_date": "2026-10-15", "entity": "postal_code", "change": "removed", "id": "29269", "changed_fields": [], "before": { "postal_code": "29269", "state": { "id": "07", "name": "Chiapas" }, "municipality": { "id": "078", "name": "San Cristóbal de las Casas" }, "office": "29201" }, "after": null }, { "version": "2026.10.15-fb39a8da", "source_date": "2026-10-15", "entity": "postal_code", "change": "removed", "id": "29294", "changed_fields": [], "before": { "postal_code": "29294", "state": { "id": "07", "name": "Chiapas" }, "municipality": { "id": "078", "name": "San Cristóbal de las Casas" }, "office": "29201" }, "after": null } ], "next_cursor": "MjAyNi4xMS4wNS0zNmE3ODIzYnwx", "data_version": "2026.11.05-36a7823b"}Campos
| Campo | Tipo | Descripción |
|---|---|---|
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ó |
next_cursor | texto o null | Cursor opaco de la página siguiente; null si no hay más resultados. |
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). |
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