API y empresas

Esquema estable de una API de multas: qué garantiza el contrato

Prometer que el esquema no cambia es distinto de prometer que el dato está. Conviene enumerar qué asegura el contrato sobre la forma y qué queda del lado de la cobertura.

Foto de Marco FerreiroMarco FerreiroAutor en multas.ar
4 min de lectura
Fichero de madera abierto sobre un escritorio, con fichas de cartulina en blanco alineadas entre separadores de cartón, bajo luz natural.
Fichero de madera abierto sobre un escritorio, con fichas de cartulina en blanco alineadas entre separadores de cartón, bajo luz natural.

Antes de firmar una integración de multas, la pregunta que más se repite es si el esquema va a cambiar. La respuesta honesta no es “no”: es una lista. Un contrato de datos promete cosas concretas y, si está bien escrito, dice también qué no promete. Los incidentes más molestos de una integración no nacen de una promesa rota, sino de una que nunca existió y que el consumidor dio por hecha.

Un esquema estable no es un esquema inmutable: es uno cuyos cambios resultan compatibles con los clientes existentes o se anuncian antes de aplicarse. Estabilidad es previsibilidad, no congelamiento.

La distinción importa porque una consulta de infracciones reúne datos de fuentes ajenas, con vocabularios y disponibilidad propios. El contrato puede sostener la forma aunque el contenido varíe; lo que no puede es hacer que una jurisdicción responda.

Cuatro promesas de forma

Un contrato de datos serio se lee como cuatro compromisos verificables:

  • un nombre de campo no cambia de significado: si montoTotal deja de incluir intereses, eso es un cambio incompatible aunque el tipo siga siendo el mismo;
  • el tipo declarado se respeta en todas las respuestas, incluidas las parciales y las de error;
  • los campos declarados obligatorios están presentes en cualquier respuesta válida;
  • ninguna eliminación ocurre sin aviso previo.

OpenAPI 3.1 sirve para escribir esa descripción y JSON Schema para el esquema de cada objeto. Son formatos de descripción: valen lo que valga el compromiso de mantenerlos al día.

Lo que no figura pesa igual: ninguna de las cuatro promesas dice que el valor esté disponible, que sea reciente ni que provenga de todas las jurisdicciones previstas.

Validar no es verificar

Una respuesta puede pasar la validación completa y no decir nada útil. La lista required de JSON Schema controla la presencia de una propiedad, no la calidad del valor: el importe de un acta puede llegar con una cadena vacía, con null si el esquema lo admite o con un relleno convenido; null, ausente y cero no significan lo mismo.

El vocabulario de validación de 2020-12 trata format como anotación, salvo que se active explícitamente la variante de aserción. Una fecha de infracción declarada como date-time puede describir la intención sin que el validador rechace un valor mal formado.

Un listado vacío que valida perfecto puede significar “no hay infracciones”, “la fuente no respondió” o “la consulta todavía corre”. Esa diferencia no vive en el validador: la declaramos aparte, en un campo de estado y en la cobertura por fuente.

Lo que el formato no garantiza

Debajo del esquema está el formato de intercambio, donde la lista se acorta más. RFC 8259 recomienda que los nombres de un objeto sean únicos, pero recomendar no es prohibir: advierte que, ante nombres repetidos, el comportamiento difiere entre implementaciones. Un JSON válido puede no tener un único significado.

Tampoco hay orden garantizado. Un objeto JSON es una colección sin orden: un cliente que depende de la posición de las claves no lee el contrato, lee un accidente. Los arreglos sí son ordenados, pero el formato promete que ese orden llega intacto, no cuál es: el criterio con el que se ordena una lista de actas tiene que estar escrito.

Los números tampoco vuelven siempre idénticos. El mismo RFC describe los límites de interoperabilidad: fuera del rango y la precisión habituales, dos clientes pueden discrepar, y de ahí que los identificadores viajen como texto.

Extensión: quién tolera qué

Casi todo cambio incompatible empieza como una extensión razonable: un valor nuevo de estado, un campo agregado, una jurisdicción que aparece. El contrato tiene que declarar de antemano qué puede crecer y quién absorbe ese crecimiento:

  • si el conjunto de valores de un campo es cerrado o puede recibir miembros nuevos;
  • si el cliente debe ignorar los campos desconocidos o rechazarlos;
  • qué hace un consumidor ante un valor que no conoce: descartarlo, mostrarlo tal cual o detenerse.

Con esas tres respuestas escritas, agregar una jurisdicción nueva es rutina. Sin ellas, el mismo cambio se descubre en producción: adelantá el hallazgo con tests de contrato.

Qué pedir antes de integrar

El aviso también es parte del contrato. RFC 9745 estandariza cómo señalar que un recurso está obsoleto, o va a estarlo, y desde qué fecha, para que un cliente lo detecte sin leer un changelog. Habla del recurso, no de un campo suelto, y no reemplaza el aviso directo ni la guía de migración.

Antes de conectar un sistema propio, pedí por escrito la descripción vigente del esquema y su versión, la política sobre campos desconocidos y valores nuevos, qué campos son obligatorios y cuáles pueden faltar, cómo se distingue una patente sin multas de una consulta incompleta, y con cuánta anticipación se anuncia una baja. Guardá esa respuesta con fecha: es la línea de base contra la que vas a comparar cuando algo cambie.

Si alguna de esas respuestas no está escrita, todavía no hay garantía: hay una costumbre. Las costumbres cambian sin aviso, y en una integración eso se descubre siempre el mismo día, el de la primera respuesta que no encaja.

Metodología

Alcance
Revisión del alcance de un contrato de datos para respuestas de consultas de infracciones: qué compromisos admiten verificación y cuáles quedan fuera. No cubre el diseño de versiones ni la suite de pruebas que detecta cambios incompatibles.
Unidad de análisis
Un campo del contrato y el compromiso verificable que el proveedor asume sobre su nombre, tipo, presencia y evolución.
Cobertura
Semántica de OpenAPI 3.1 y JSON Schema 2020-12 para descripción y validación, el modelo de datos de JSON y el mecanismo estandarizado de anuncio de obsolescencia, revisados al 29 de agosto de 2026.

Limitaciones

  • Los estándares citados describen forma y validación; la semántica de negocio de cada campo debe definirse en el contrato del proveedor.
  • El comportamiento ante claves duplicadas o números fuera del rango interoperable depende de la biblioteca que use cada cliente.
  • Ningún compromiso de esquema modifica la disponibilidad de las fuentes oficiales ni la exactitud de lo que informan.

Fuentes

Preguntas frecuentes

¿Un esquema estable significa que la respuesta nunca va a cambiar?

No. Significa que los cambios serán compatibles con los clientes existentes o se anunciarán antes de aplicarse. Puede haber campos nuevos, valores nuevos en un campo abierto y correcciones sobre datos ya entregados sin que el contrato se rompa.

Si la respuesta valida contra el esquema, ¿el dato está completo?

No. La validación confirma forma y tipos, no disponibilidad ni cobertura. Un listado vacío que valida puede significar que no hay infracciones, que una fuente no respondió o que la consulta sigue en curso; esa diferencia se lee en el estado y la cobertura declarados, no en el validador.

¿Qué pasa con el contrato si una fuente oficial cambia su formato?

El contrato puede absorber el cambio o anunciarlo, pero no evitarlo. Un vocabulario nuevo en la fuente suele llegar como un valor nuevo dentro de un campo abierto, y una corrección posterior puede modificar un dato ya entregado sin que la forma se rompa. Por eso conviene acordar de antemano qué campos admiten valores nuevos y cómo se avisa una corrección.

Notas relacionadas