Integraciones B2B: cómo mapear dependencias upstream antes de que el pipeline colapse
Integraciones B2B: cómo mapear dependencias upstream antes de que el pipeline colapse
La mayoría de los fallos en integraciones B2B no ocurren por errores de código. Ocurren porque alguien asumió que la API de terceros iba a seguir comportándose igual que el día del contrato. Sin documentación de dependencias. Sin un mapa real de qué parte del pipeline depende de qué proveedor y en qué condiciones.
Cuando el proveedor upstream cambia algo —un campo renombrado, una paginación distinta, un límite nuevo en el plan— el fallo llega tarde y en silencio. El pipeline sigue corriendo, pero los datos que entrega ya no son los que el cliente espera. Ese intervalo entre el cambio y el descubrimiento es donde se acumula la deuda técnica más cara del sector.
Mapear dependencias upstream no es burocracia. Es la única forma de saber, antes de que ocurra el problema, dónde está el riesgo real.
Por qué la mayoría de los equipos no tienen este mapa
La razón más común es simple: la integración se construyó rápido. El desarrollador que la levantó sabía qué hacía la API, probó los endpoints que necesitaba, y siguió adelante. Ese conocimiento nunca salió de su cabeza.
Seis meses después, ese desarrollador puede estar en otro proyecto, en otra empresa, o simplemente haber olvidado los detalles. Y si nadie documentó qué campos son críticos, qué endpoints tienen comportamiento variable según el plan contratado, o qué parámetros implícitos asumió el código, cualquier cambio upstream se convierte en un incendio.
El segundo motivo es que los equipos suelen documentar el qué —"llamamos a este endpoint, recibimos este JSON"— pero no el por qué ni el bajo qué condiciones. Esa diferencia importa cuando el proveedor actualiza su API y la respuesta cambia de forma.
Qué debe contener un mapa de dependencias upstream
Un mapa de dependencias útil no es un diagrama de arquitectura de alto nivel. Es un inventario operativo. Para cada integración con una API externa, el equipo necesita responder con precisión a estas preguntas:
¿Qué endpoints consume el pipeline y con qué frecuencia? No basta con listar URLs. Hay que registrar la cadencia real de llamadas, los parámetros que se envían de forma variable y los que son fijos, y si hay lógica de reintentos o fallback cuando el endpoint falla.
¿Qué campos de la respuesta son críticos para el negocio? Aquí la granularidad importa. Si el pipeline consume un campo published_at para ordenar señales por relevancia temporal, ese campo es crítico. Si el campo desaparece o cambia de formato, el fallo no será un error 500 —será un resultado silenciosamente incorrecto.
¿Qué supuestos implícitos tiene el código sobre el comportamiento de la API? Este es el punto más difícil de documentar porque requiere auditar código que ya funciona. Supuestos típicos: que la paginación siempre devuelve el mismo número máximo de resultados, que los identificadores son estables, que el orden de los elementos en el array es determinista.
¿Qué SLA real tiene el proveedor y cómo se mide internamente? No el SLA del contrato —el SLA observado en producción. Si la API del proveedor tiene una disponibilidad real del 99,1% pero el SLA contratado es del 99,5%, ese gap necesita estar en el mapa porque afecta al diseño de los fallbacks.
Cómo construir el mapa sin paralizar al equipo
El error habitual es intentar documentar todo a la vez antes de seguir construyendo. Ese enfoque siempre fracasa porque genera resistencia y el mapa queda incompleto desde el primer día.
Una aproximación más sostenible: usar cada incidente —o casi-incidente— como disparador de documentación. Cuando la API de un proveedor falla o produce un resultado inesperado, la primera tarea antes de cerrar el ticket es actualizar el mapa con lo que se aprendió. Con tres o cuatro ciclos así, el equipo tiene un inventario que refleja los riesgos reales, no los teóricos.
Complementariamente, vale la pena introducir una revisión trimestral de dependencias upstream. No para auditarlo todo, sino para identificar qué integraciones han recibido menos atención y cuáles han tenido cambios en el proveedor que podrían no haber quedado reflejados.
Para equipos que consumen APIs de datos de análisis —como las que ofrece FeedScale para acceso al universo público de fuentes— este inventario también ayuda a dimensionar correctamente el consumo. Saber qué parte del pipeline es sensible a la latencia versus cuál tolera respuestas en batch cambia el diseño de la integración y el coste operativo.
Automatizar la detección de cambios upstream
El mapa documental es necesario, pero no suficiente. La documentación no avisa cuando la API cambia. Para eso hace falta instrumentación.
Dos mecanismos con relación coste-beneficio favorable:
Schema validation en el punto de entrada. Antes de que los datos lleguen a la lógica de negocio, un validador de esquema —Pydantic, JSON Schema, Avro, según el stack— comprueba que la respuesta tiene la forma esperada. Si el proveedor añade un campo sin avisar, el pipeline lo ignora de forma controlada. Si elimina un campo crítico, el error es explícito e inmediato, no silencioso.
Alertas por distribución estadística. Un cambio en la API no siempre produce un error de esquema. A veces produce un resultado técnicamente válido pero estadísticamente anómalo: el volumen de señales cae un 40%, la distribución de fechas cambia de forma brusca, ciertos valores empiezan a repetirse con frecuencia inusual. Monitorizar estas distribuciones —con ventanas cortas de comparación— es más caro de implementar pero detecta los cambios más insidiosos.
Cuándo revisar el mapa, no solo consultarlo
El mapa de dependencias tiene que evolucionar con el sistema. Hay cuatro momentos no negociables para actualizarlo:
- Cuando el proveedor anuncia una deprecación o una nueva versión de la API.
- Cuando se incorpora un nuevo consumidor downstream del pipeline.
- Cuando el equipo detecta un comportamiento inesperado, aunque haya quedado sin impacto visible.
- Cuando se renegocia el contrato con el proveedor —porque los términos de uso, los límites de llamadas y los SLAs pueden cambiar junto con el precio.
El pipeline que no tiene este mapa no está roto todavía. Pero está construido sobre supuestos que nadie ha explicitado. La integración B2B robusta no empieza por el código —empieza por saber exactamente de qué depende ese código y bajo qué condiciones esa dependencia deja de cumplirse.