Cuando un CRM alimenta un ERP, una tienda envía pedidos a logística o una aplicación interna publica eventos para otros sistemas, la integración depende de algo más que una URL, una cola o un archivo compartido. Depende de que todas las partes interpreten los datos de la misma forma a lo largo del tiempo. Los contratos de datos para integraciones convierten esa expectativa en reglas explícitas, comprobables y gobernables.
Su objetivo no es documentar una interfaz una sola vez, sino evitar que un cambio aparentemente pequeño —renombrar un campo, admitir un estado nuevo o modificar una unidad monetaria— provoque errores silenciosos, reprocesos o decisiones de negocio incorrectas. Son especialmente útiles cuando intervienen equipos distintos, aplicaciones de terceros y despliegues con calendarios independientes.
Qué es un contrato de datos y qué problema resuelve
Un contrato de datos define el acuerdo operativo entre quien produce información y quien la consume. Es aplicable a una respuesta de servicio, un evento, un fichero periódico, una tabla compartida o un mensaje de una cola. Describe qué se entrega, qué significa, bajo qué condiciones es válido y cómo evolucionará.
Por ejemplo, un mensaje de pedido con orderId, status e amount necesita precisar si el importe está en unidades o céntimos, qué moneda se aplica, qué estados son admisibles, si un pedido cancelado puede tener importe cero y si un mismo mensaje puede llegar más de una vez. Sin estas reglas, dos sistemas pueden aceptar técnicamente el mismo JSON y, aun así, actuar de forma incompatible.
El contrato reduce tres riesgos frecuentes:
- Roturas directas: un consumidor no puede deserializar, validar o procesar un dato cambiado.
- Errores semánticos: el formato parece correcto, pero cambia el significado de un campo o una regla de negocio.
- Dependencias invisibles: un productor desconoce que un campo, valor o comportamiento es usado por otros consumidores.
Documentación, esquema y contrato operativo
La documentación explica cómo debería funcionar una integración. Un esquema formaliza parte de esa explicación: estructura, nombres, tipos, campos obligatorios y, según la tecnología, restricciones. Ambos son necesarios, pero no bastan para operar una integración de forma segura.
El contrato operativo reúne el esquema con decisiones que se pueden revisar y probar: propietario, consumidores conocidos, política de compatibilidad, versionado, reglas semánticas, calidad mínima, tratamiento de errores y procedimiento de cambio. Puede representarse con OpenAPI, AsyncAPI, JSON Schema, Avro, Protobuf, SQL u otra especificación, pero la herramienta no sustituye esas decisiones.
Un contrato útil debería incluir como mínimo:
- Identidad y alcance: nombre, propósito, canal, productor, responsable y clasificación de sensibilidad.
- Estructura: campos, tipos, cardinalidad, obligatoriedad, formatos y ejemplos válidos.
- Semántica: significado, unidad, zona horaria, moneda, catálogo de valores y reglas de cálculo.
- Calidad: unicidad, rangos, relaciones entre campos, frescura esperada y orden cuando sea relevante.
- Operación: frecuencia, límites de tamaño, orden de entrega, reintentos, conservación y canal de incidencias.
- Evolución: versión, cambios compatibles, cambios que requieren coordinación y periodo de retirada.
Compatibilidad: evaluar cambios con una perspectiva explícita
La terminología de compatibilidad puede variar entre equipos. Para evitar decisiones erróneas, conviene adoptar la perspectiva habitual de lectura de esquemas, usada por numerosos registros de esquemas: la compatibilidad hacia atrás significa que el esquema o consumidor nuevo puede leer datos producidos con el esquema anterior; la compatibilidad hacia delante significa que el esquema o consumidor anterior puede leer datos producidos con el esquema nuevo. La compatibilidad total exige ambas direcciones.
Esta definición no permite deducir el comportamiento real sólo mirando una regla abstracta. Debe verificarse con el formato, el serializador, el esquema de lectura y la implementación concreta del consumidor. Añadir un campo opcional con valor por defecto, por ejemplo, puede ser compatible hacia atrás si la versión nueva sabe completar su ausencia al leer datos antiguos. Pero un consumidor antiguo sólo podrá leer el mensaje nuevo si su tecnología e implementación ignoran campos desconocidos o si su esquema de lectura resuelve correctamente ese campo mediante un valor por defecto. No debe asumirse sin una prueba.
Antes de aprobar un cambio, formule preguntas concretas: ¿puede la nueva versión procesar mensajes ya almacenados? ¿puede la versión anterior seguir procesando mensajes emitidos durante un despliegue gradual? ¿qué ocurre con consumidores externos que no se actualizan al mismo ritmo? La respuesta debe venir de pruebas representativas, no sólo de la etiqueta de compatibilidad del registro.
Como regla práctica, suelen ser cambios de menor riesgo añadir campos realmente opcionales, ampliar metadatos no interpretados o corregir descripciones. Suelen requerir nueva versión y coordinación eliminar o renombrar campos, cambiar tipos, estrechar rangos, alterar unidades, reinterpretar nulos o introducir valores de enumeración que activen lógica distinta. Mantener temporalmente un campo obsoleto y publicar una fecha de retirada ofrece una transición más segura que eliminarlo de inmediato.
Diseño según el tipo de intercambio
Un mismo principio adopta formas distintas según el mecanismo. En eventos, identifique el hecho ocurrido, el instante de negocio, el origen, el identificador del evento y la entidad afectada. Declare si el evento es inmutable, si puede llegar desordenado y si existen eventos de corrección.
Si la entrega es al menos una vez, el consumidor necesita una estrategia verificable para detectar o tolerar duplicados. Puede usar un identificador de evento guardado en un registro de deduplicación, una clave de negocio con operaciones idempotentes, una restricción en almacenamiento o un mecanismo acordado equivalente. Una clave de idempotencia es una opción frecuente, pero no un requisito universal. Lo importante es definir qué duplicados se esperan, durante cuánto tiempo se detectan y qué resultado debe producir su reprocesamiento.
En respuestas síncronas de servicios, el contrato debe distinguir datos de negocio, errores funcionales y fallos técnicos. Es preferible definir códigos, estructura de error, campos seguros para diagnóstico y condiciones de reintento. En cargas periódicas, especifique el corte temporal, la zona horaria, si el archivo contiene una carga completa o incremental, la clave de conciliación y el comportamiento ante registros repetidos o ausentes.
Pruebas de contrato antes y después de producción
Las pruebas de contrato automatizan la comprobación de que productor y consumidor respetan el acuerdo. En desarrollo, valide ejemplos válidos e inválidos contra el esquema y las reglas semánticas relevantes. Incluya casos límite: nulos permitidos, valores desconocidos, decimales, fechas con zona horaria y combinaciones de campos dependientes.
En integración continua, el cambio de contrato debe compararse con la última versión publicada. El control puede bloquear modificaciones incompatibles, exigir una versión nueva o requerir aprobación del responsable. También conviene ejecutar consumidores de referencia o pruebas pactadas por consumidores críticos frente a datos de prueba producidos por la nueva versión.
Antes de producción, pruebe la convivencia entre versiones que realmente existirá durante el despliegue. Tras publicar, observe tasas de validación fallida, mensajes enviados a cuarentena, errores de deserialización, retraso de procesamiento y proporción de valores desconocidos. Registre identificadores técnicos, versión del contrato, tipo de error y origen; evite incluir datos personales, secretos o cargas completas cuando no sean imprescindibles para diagnosticar.
Gobierno del cambio, excepciones y trazabilidad
Un flujo ligero y explícito evita que el contrato sea un documento olvidado. El productor propone el cambio con su motivación, impacto previsto, ejemplo de antes y después, clasificación de compatibilidad y plan de retirada. Los responsables de consumidores afectados revisan la semántica y las pruebas. Un propietario designado aprueba, publica la versión y comunica la ventana de adopción.
Las excepciones también deben estar definidas. Si llega un valor fuera de rango, no siempre procede rechazar toda la carga: puede enviarse a cuarentena, marcarse para revisión o aceptarse con una señal de calidad, según el riesgo de negocio. Para valores de catálogo desconocidos, determine si el consumidor debe ignorarlos, preservarlos, aplicar un comportamiento seguro o detener el proceso. Diferencie cuidadosamente entre campo ausente, campo null y valor vacío: pueden expresar situaciones distintas.
Por último, mantenga un registro versionado de contratos, decisiones de compatibilidad, aprobaciones, fechas de deprecación y evidencia de pruebas. Esta trazabilidad permite responder quién cambió qué, por qué se consideró seguro y qué consumidores debían adaptarse. Así, la evolución deja de depender de comprobaciones manuales y pasa a ser una disciplina técnica verificable.