Cómo estaba un código postal en una fecha
Los catálogos cambian: una colonia cambia de nombre, otra aparece, el SAT publica una revisión
nueva. Cuando revisas algo que pasó antes (una factura de hace meses, una dirección que capturaste
y que hoy ya no valida), lo que importa no es cómo está el código postal hoy, sino cómo estaba ese
día. Con as_of le pides a Colonix justo eso.
Necesitas: cualquier plan para /v1/postal-codes/{code}?as_of=… (SEPOMEX). Plan Básico o
superior para /v1/sat/postal-codes/{code}?as_of=… (SAT); los cinco códigos postales de
demostración responden en cualquier plan.
En SEPOMEX
Section titled “En SEPOMEX”Agrega as_of con la fecha (AAAA-MM-DD) a la consulta de un código postal. Este es un caso real:
el 15 de octubre de 2026, SEPOMEX cambió “Mecatlan” (pueblo) por “Mecatlán Centro” (colonia) en el
93080. Así estaba el 10 de octubre:
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/postal-codes/93080?as_of=2026-10-10"{ "postal_code": "93080", "state": { "id": "30", "name": "Veracruz de Ignacio de la Llave" }, "municipality": { "id": "103", "name": "Mecatlán" }, "office": "93261", "settlement_count": 2, "settlements": [ { "id": "30103-0002", "name": "La Cruz", "type": "Colonia", "zone": "Rural", "city": null }, { "id": "30103-2162", "name": "Mecatlan", "type": "Pueblo", "zone": "Rural", "city": null } ], "as_of": { "date": "2026-10-10", "sepomex_date": "2026-10-05", "data_version": "2026.10.05-936974de" }, "data_version": "2026.11.05-36a7823b"}Sin as_of, el mismo asentamiento (30103-2162, la clave no cambia) sale como “Mecatlán Centro”.
El bloque as_of dice en qué se basa la respuesta:
| Campo | Qué es |
|---|---|
as_of.date |
La fecha que pediste |
as_of.sepomex_date |
La fecha del archivo de SEPOMEX que da la respuesta: el más reciente de ese día o antes |
as_of.data_version |
La versión del dato que publicó ese archivo |
data_version |
La versión con que respondió la API (la vigente), como en cualquier respuesta |
El catálogo se revisa cada semana. Si SEPOMEX publicó dos archivos entre una revisión y la
siguiente, solo queda registrado el último, así que la respuesta es la del archivo de
sepomex_date: nunca una fecha que no tengamos.
Con as_of se aceptan fields (más as_of entre los campos) pero no include: la ubicación, la
zona metropolitana y el bloque del SAT describen el dato de hoy. Si el código postal no existía ese
día, la respuesta es 404 postal-code-not-found.
En el SAT
Section titled “En el SAT”Para una factura importa el catálogo del SAT: si el código postal estaba en c_CodigoPostal y
cuáles eran sus claves ese día. Por ejemplo, al revisar o sustituir una factura del 30 de junio:
curl -H "x-api-key: TU_LLAVE" "https://colonix.silgaru.mx/v1/sat/postal-codes/93080?as_of=2026-06-30"{ "postal_code": "93080", "in_sat": true, "state": { "sat_code": "VER", "id": "30", "name": "Veracruz" }, "municipality": { "sat_code": "103", "name": "Mecatlán" }, "locality": null, "border_stimulus": null, "border_stimulus_decree": null, "settlements": [ { "c_colonia": "2162", "name": "Mecatlan" } ], "as_of": { "date": "2026-06-30", "sat_revision": { "postal_codes": "8", "published": "2026-01-22" }, "effective_since": "2026-01-22" }, "data_version": "2026.11.05-36a7823b"}| Campo | Qué es |
|---|---|
in_sat |
Si el código postal estaba en c_CodigoPostal ese día (si no estaba en ningún catálogo del SAT, la respuesta es 404) |
as_of.sat_revision |
La revisión del catálogo de códigos postales del SAT que da la respuesta y su fecha de publicación |
as_of.effective_since |
Desde cuándo aplica ese contenido: la fecha de publicación de la revisión |
border_stimulus_decree |
El decreto del estímulo fronterizo vigente ese día, o null si era uno anterior |
Con as_of la respuesta describe solo el catálogo del SAT: no trae el emparejamiento con SEPOMEX
(match, sepomex_name, sugerencias), in_sepomex ni settlements_missing_in_sat. Para eso está
la consulta sin as_of, con el dato de hoy.
Desde cuándo se puede preguntar
Section titled “Desde cuándo se puede preguntar”Colonix no inventa lo que no registró. Cada catálogo responde desde que empezó su historial:
- SEPOMEX: desde
history_sincede/v1/meta, el 5 de octubre de 2026. - SAT: desde
sat_history_since, la fecha de publicación de la primera revisión registrada: el 22 de enero de 2026 (revisión 8 dec_CodigoPostal).
Una fecha anterior, o posterior a hoy (en la Ciudad de México), responde 400
as-of-out-of-range:
{ "type": "/errors/as-of-out-of-range", "title": "Date out of range", "status": 400, "detail": "The history of the SAT catalog starts on 2026-01-22; as_of cannot be earlier."}Cuándo cambió
Section titled “Cuándo cambió”as_of te dice cómo estaba; el historial te dice cuándo cambió:
GET /v1/postal-codes/{code}/historyda los cambios de SEPOMEX del código postal y de sus asentamientos. Coninclude=sat(plan Básico o superior) suma los del SAT (sat_postal_codeysat_settlement), intercalados en orden.GET /v1/changes(plan Negocio) da todos los cambios desde tu versión, también los del SAT. Ver Mantener tu catálogo al día.
En cada cambio, source_date es la fecha desde la que as_of lo ve: una consulta con as_of de
ese día o posterior ya lo incluye.
© 2026 Silgaru