Aprobar una integración de API: evidencia mínima antes de conectar

Conectar dos sistemas es una decisión operativa, no un hito de proyecto. Necesita un punto de control explícito: alguien con criterio técnico que revise evidencia concreta y firme —o rechace— el paso a producción. Sin ese control, la conexión ocurre porque "ya está el endpoint" o porque llegó la fecha del cronograma, y los problemas aparecen cuando el sistema ya está en la ruta crítica del negocio.

Este artículo no explica qué es un contrato de API ni cómo se diseña un catálogo de errores; ese trabajo está documentado en otros artículos del blog. Aquí se aborda el momento previo a la conexión: qué evidencia debe existir para que gerencia TI, operaciones o continuidad autoricen el paso, y qué señales justifican detenerlo.

Qué se decide antes de conectar dos sistemas

La decisión de integrar no es binaria entre "funciona" y "no funciona". Es una evaluación de riesgo operacional: si esta API falla, ¿qué se degrada?, ¿quién se entera?, ¿cuánto tarda la recuperación?, ¿queda rastro de lo ocurrido?

El área que recibe el sistema —no el equipo que lo construyó— carga con las consecuencias de una integración mal preparada. Por eso el punto de control debe estar en esa área, con criterios acordados antes de que exista presión por salir a producción.

Tres decisiones se toman en este punto:

1. Alcance de la conexión. Qué operaciones quedan habilitadas en el primer corte y cuáles se postergan. Arrancar con el 100% de los casos de uso rara vez es la opción más segura.
2. Modo de falla aceptable. Qué ocurre cuando el sistema destino no responde: ¿se encola, se rechaza, se reintenta?, ¿con qué límite?, ¿quién monitorea?
3. Responsable de la operación. Quién recibe las alertas, quién decide escalar y con qué información cuenta para hacerlo.

Si estas tres decisiones no están documentadas antes de conectar, la integración no está lista, aunque los endpoints respondan.

Evidencia mínima que debe existir para aprobar una integración

La evidencia no es documentación decorativa. Es el conjunto de artefactos que permiten a alguien que no participó en el desarrollo responder: "esto se comporta como esperamos, y si no, lo vamos a saber".

Un conjunto mínimo razonable incluye:

• Contrato versionado y accesible. Publicado donde operaciones pueda consultarlo, con la versión que efectivamente se consumirá y la política de cambios (qué se considera compatible, qué requiere aviso previo).
• Catálogo de errores con significado operacional. Cada código debe indicar qué hacer: reintentar, descartar, alertar, escalar. Un error que solo dice "500" no permite operar.
• Evidencia de pruebas en escenarios de falla. No solo el camino feliz: timeouts, respuestas lentas, errores del sistema destino, reintentos duplicados. La pregunta que responde es: ¿qué vimos cuando algo salió mal?
• Trazabilidad verificable de punta a punta. Un identificador de correlación que permita seguir una transacción desde el origen hasta el destino y volver. Verificable significa que alguien lo probó y mostró el rastro, no que el diseño lo contempla.
• Límites de uso y comportamiento bajo carga. Cuántas llamadas por minuto se esperan, qué pasa al superarlas y cómo se comunica el bloqueo.
• Plan de reversa. Cómo se desconecta la integración si algo sale mal en las primeras horas, y quién tiene la autoridad para activarlo.

Ninguno de estos elementos es exótico. Lo que suele faltar no es el artefacto, sino la verificación de que existe y funciona en el entorno real. Un contrato en un repositorio que nadie revisó no es evidencia; es documentación.

Señales de que la API no está lista: cuándo detener la conexión

Hay condiciones que justifican postergar la conexión aunque el cronograma presione. No son fallas de calidad del código: impiden operar la integración con un riesgo aceptable.

• No se distingue un error transitorio de uno permanente. Si el consumidor no puede decidir si reintentar o alertar, cada incidente se vuelve una investigación manual.
• La trazabilidad depende de que alguien "mire los logs". Sin un identificador que cruce sistemas, el diagnóstico se convierte en una búsqueda a ciegas entre equipos.
• Los reintentos no están acotados. Un reintento sin límite ni backoff puede convertir una falla puntual del destino en una caída sostenida.
• No hay un responsable operativo identificado. Si la alerta llega a un canal compartido sin dueño, la respuesta se diluye.
• El contrato cambió sin aviso durante la preparación. Un contrato que se modifica sin versionado ni comunicación indica que el proceso de cambio no está bajo control, y eso se traslada a producción.
• No se probó el comportamiento bajo falla del sistema destino. Se probó que funciona cuando todo responde, no qué pasa cuando no.

Detener la conexión en cualquiera de estos casos evita que la deuda operativa se consolide en la ruta crítica. Postergar una semana suele costar menos que operar una integración sin trazabilidad durante un trimestre.

Criterio práctico de aceptación para el área de TI y operaciones

El punto de control funciona si es repetible y no depende de la buena voluntad de quien lo aplica. Un criterio práctico se organiza en tres preguntas que el área receptora responde con evidencia en mano:

1. ¿Podemos detectar una falla en menos tiempo del que tarda en afectar al negocio? Exige monitoreo definido, alertas con destinatario y umbrales acordados.
2. ¿Podemos diagnosticar una falla sin depender del equipo que construyó la integración? Exige trazabilidad verificable y documentación operacional accesible.
3. ¿Podemos detener o revertir la integración sin afectar otros procesos? Exige plan de reversa y autoridad definida.

Si las tres respuestas son sí, con evidencia, la integración avanza. Si alguna es no, el paso a producción se posterga hasta que exista la evidencia, no hasta que exista la promesa de resolverlo después.

El mismo criterio sirve para integraciones que ya operan y nunca pasaron por un control formal: revisarlas con estas preguntas identifica dónde está la exposición real sin rehacer la integración completa.

Cuando la integración involucra datos personales, este control es además una oportunidad para verificar que la trazabilidad permite responder a requerimientos de acceso o rectificación. No se trata de garantizar cumplimiento normativo —eso exige un trabajo legal y técnico más amplio—, sino de asegurar que los controles mínimos de registro y evidencia existen antes de que se necesiten.

Qué queda fuera de este control y por qué importa

Este punto de control no reemplaza la revisión de seguridad de la integración, ni el análisis de calidad de datos, ni la validación funcional del negocio. Tampoco garantiza que la API no falle: garantiza que, si falla, la organización puede enterarse, diagnosticar y responder.

Reconocer ese límite es parte del criterio. Un control que se presenta como total genera falsa confianza, y la falsa confianza es más peligrosa que su ausencia, porque desactiva la vigilancia.

El equipo que construye la integración —interno o externo— entrega la evidencia; no la autoevalúa. La aceptación corresponde a quien va a operar el sistema. Esa separación es la que da valor al punto de control.

Si en tu organización las integraciones se aprueban por fecha y no por evidencia, vale la pena revisar dónde se perdió ese criterio. En Desarrollo de Software trabajamos con equipos que necesitan definir estos puntos de control antes de que la integración entre en la ruta crítica.