Ir al contenido

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.

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"
200 OK
{
"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.

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"
200 OK (sin time_zone, que viene igual que sin as_of)
{
"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.

Colonix no inventa lo que no registró. Cada catálogo responde desde que empezó su historial:

  • SEPOMEX: desde history_since de /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 de c_CodigoPostal).

Una fecha anterior, o posterior a hoy (en la Ciudad de México), responde 400 as-of-out-of-range:

GET /v1/sat/postal-codes/93080?as_of=2025-12-15
{
"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."
}

as_of te dice cómo estaba; el historial te dice cuándo cambió:

  • GET /v1/postal-codes/{code}/history da los cambios de SEPOMEX del código postal y de sus asentamientos. Con include=sat (plan Básico o superior) suma los del SAT (sat_postal_code y sat_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.