Integraciones B2B: por qué negociar el formato del dato antes de conectar los sistemas
Integraciones B2B: por qué negociar el formato del dato antes de conectar los sistemas
El pipeline está en producción. Los endpoints responden. Las credenciales funcionan. Y tres semanas después, el sistema destino empieza a fallar de forma intermitente porque el campo published_at llega a veces como ISO 8601, a veces como epoch en milisegundos, y en ocasiones simplemente no llega.
Nadie lo documentó. Nadie lo negoció. Se asumió que "los dos lados hablan JSON" era suficiente. No lo era.
Este es el error más frecuente en integraciones B2B entre equipos técnicos: confundir conectividad con compatibilidad. Que dos sistemas puedan intercambiar datos no significa que estén de acuerdo en qué significa cada dato.
El problema real no es el protocolo, es el contrato
Cuando dos organizaciones integran APIs, el debate suele girar en torno al protocolo (REST vs GraphQL vs WebSockets), la autenticación (OAuth2, API keys, mTLS) y los rate limits. Todo eso importa. Pero el problema que realmente mata las integraciones en producción es anterior: la ausencia de un contrato de datos explícito.
Un contrato de datos no es solo un schema JSON. Es un acuerdo formal —aunque sea un documento en Confluence— que responde a estas preguntas:
- ¿Qué campos son obligatorios y cuáles opcionales?
- ¿Qué tipos son fijos y cuáles pueden variar según el contexto?
- ¿Qué ocurre cuando un campo se depreca? ¿Hay período de transición?
- ¿Qué significado semántico tiene cada campo? ¿
scorees de 0 a 1 o de 0 a 100? - ¿Los valores nulos y los campos ausentes son equivalentes?
Sin respuestas explícitas a estas preguntas, cada equipo opera con sus propias suposiciones. Y las suposiciones divergen en producción.
Tres patrones de ruptura habituales
1. El campo que cambia de tipo sin avisar
Un proveedor decide cambiar category de string a array porque algunos registros pertenecen a múltiples categorías. Es una mejora razonable. Pero si el consumidor espera un string y recibe un array, el parser falla. Si falla en silencio, los datos se descartan sin log. Si falla con excepción, el pipeline se detiene.
La solución no es solo validar tipos en recepción. Es establecer, de antemano, una política de evolución del schema: qué cambios son retrocompatibles y cuáles requieren versión nueva.
2. Los valores que no significan lo mismo en los dos lados
Un campo sentiment con valor 1 puede significar "positivo" en un sistema y "negativo" en otro dependiendo de si la escala va de -1 a 1 o de 1 a 3. Ningún tipo de dato fuerza semántica. Solo la documentación lo hace, y la documentación hay que leerla y validarla activamente, no asumir que el otro equipo la leyó.
3. La latencia del campo opcional
Un campo opcional que aparece en el 95 % de los registros durante el desarrollo aparece en el 40 % en producción porque las fuentes en producción son más heterogéneas. El equipo consumidor había construido lógica de negocio asumiendo que ese campo "casi siempre" estaría presente. Ahora esa lógica falla silenciosamente en el 60 % de los casos.
Cómo estructurar la negociación antes de la integración
El momento de negociar el formato del dato no es después del primer error en producción. Es antes de escribir la primera línea de código de integración. El proceso puede ser simple:
Paso 1: intercambio de schemas anotados
Cada parte expone su schema con anotaciones semánticas, no solo tipos. Herramientas como JSON Schema (con description por campo) o AsyncAPI permiten hacer esto de forma estructurada. No es burocracia: es la única forma de detectar incompatibilidades sin datos reales.
Paso 2: acuerdo sobre campos críticos y campos opcionales
Clasifica explícitamente qué campos son blockers si están ausentes y cuáles el pipeline puede degradar gracefully. Esto define la lógica de validación en recepción y las alertas en monitorización.
Paso 3: simulación con datos reales heterogéneos
Los schemas se validan bien con datos de desarrollo. Los datos de producción tienen encoding inesperado, caracteres especiales, fechas en formatos mixtos y valores nulos donde no debería haberlos. Antes de la puesta en marcha, ejecuta el pipeline con una muestra real del proveedor —aunque sea pequeña— y revisa cuántos registros pasan validación sin manipulación.
Paso 4: política de cambio y notificación
Documenta qué periodo de preaviso se da antes de un cambio breaking, qué canal se usa para notificarlo y quién en cada equipo es responsable de recibirlo. Sin este acuerdo, un cambio de schema se convierte en un incidente de producción con responsabilidades difusas.
Validación en tiempo real como red de seguridad
Incluso con un contrato bien negociado, los datos cambian. Las APIs evolucionan. Las fuentes upstream introducen variaciones que el proveedor no controla completamente.
Por eso, la validación del schema en el lado consumidor no es un paso inicial: es una capa permanente del pipeline. Cada registro que entra debe validarse contra el contrato vigente. Los registros que fallan no deben descartarse sin trazabilidad —deben ir a una cola de errores con contexto suficiente para diagnóstico.
En pipelines que integran señales del universo público de Internet —como los que construyen equipos técnicos sobre APIs como FeedScale— esta validación es especialmente relevante porque el volumen de fuentes es alto y la heterogeneidad estructural es inherente al dato de origen.
El coste de no negociar antes
Hay una aritmética simple: una hora de reunión para alinear contratos de datos antes de la integración evita, en media, varios días de debugging cuando el problema emerge en producción. Y el debugging en producción tiene coste adicional: afecta a datos reales, compromete SLAs y genera desconfianza entre los equipos.
Las integraciones B2B más robustas que existen no lo son porque los ingenieros que las construyeron fueran más hábiles. Lo son porque los equipos de ambos lados trataron el contrato de datos como un entregable tan importante como el código.
Conectividad es fácil. Compatibilidad hay que construirla antes de conectar.