Preparar una integración de API: qué exigir antes de conectar sistemas

Conectar dos sistemas suele ser la parte visible. Lo que decide si esa conexión sobrevive a la operación real es lo que ocurre antes: qué se acordó, qué se probó y qué evidencia queda cuando algo falla. En organizaciones con sistemas heterogéneos —ERP, CRM, plataformas de facturación, herramientas propias— la integración rara vez falla por falta de conectividad. Falla porque nadie definió con precisión qué significa que esté lista.

Este artículo no trata sobre cómo codificar una API ni sobre cómo reaccionar cuando ya está en producción. Trata sobre el punto de control previo: qué debe quedar definido y verificable antes de habilitar el tráfico entre dos sistemas.

Qué significa preparar una integración antes de conectar sistemas

Preparar una integración es convertir un acuerdo entre equipos en algo verificable. No es documentar por cumplir ni firmar un acta de reunión. Es dejar por escrito y en formato comprobable qué datos se intercambian, bajo qué condiciones, quién responde cuando algo no calza y cómo se demuestra que el intercambio ocurrió.

En un entorno empresarial, el diseño de API e integración de sistemas es una decisión operativa con consecuencias directas: si el contrato es ambiguo, cada equipo interpreta distinto; si los errores no están tipificados, cada falla se investiga desde cero; si no hay trazabilidad, no se puede reconstruir qué pasó ni rendir cuentas ante auditoría o continuidad operativa.

El contrato de API, en este contexto, no es la documentación decorativa que se publica después de codificar. Es el acuerdo que define qué se puede esperar del sistema y qué no. Un contrato verificable permite que dos equipos trabajen en paralelo sin depender de conversaciones informales, y que quien opera la integración sepa qué revisar cuando algo se comporta distinto a lo previsto.

La pregunta que ordena esta fase no es "¿la API funciona?", sino "¿podemos demostrar que funciona bajo las condiciones que nos importan?". Esa diferencia separa una integración que se sostiene de una que genera deuda operativa desde el primer día.

Contrato de API: qué debe quedar definido antes de integrar

Un contrato de API útil para operaciones empresariales cubre al menos cinco dimensiones. No todas requieren el mismo nivel de detalle, pero ninguna debería quedar implícita.

Estructura de datos y semántica. No basta con definir campos y tipos. Hay que acordar qué significa cada campo en el contexto del negocio: qué representa un estado, qué valores son válidos, qué ocurre con campos opcionales, cómo se representan fechas, montos, identificadores y catálogos. Un campo llamado estado sin valores enumerados ni reglas de transición es una fuente garantizada de interpretaciones divergentes.

Versionado y compatibilidad. El contrato debe establecer cómo se introducen cambios y qué se considera un cambio incompatible. Esto incluye política de versionado, período de coexistencia entre versiones y mecanismo de aviso a los consumidores. Sin esto, cualquier modificación se convierte en una negociación caso a caso, y los sistemas que dependen de la API quedan expuestos a rupturas no planificadas.

Responsabilidades entre equipos y sistemas. Quién es dueño del contrato, quién puede modificarlo, quién responde por la disponibilidad, quién gestiona los datos que se intercambian. En integraciones entre áreas o entre proveedores, esta delimitación evita que un incidente quede sin responsable claro.

Condiciones de operación. Límites de tasa, tamaños máximos de payload, timeouts esperados, ventanas de mantención, comportamiento ante indisponibilidad. Estos parámetros determinan si la integración es viable en horarios de alta carga o en procesos batch nocturnos.

Autenticación y autorización. Qué credenciales se usan, cómo se rotan, qué alcance tienen y cómo se revocan. En integraciones empresariales, esto conecta con controles de seguridad y con la capacidad de auditar quién accedió a qué.

Un contrato que cubre estos puntos permite evaluar la integración antes de conectarla. Un contrato que no los cubre traslada esas decisiones a la operación, donde cada ambigüedad se resuelve bajo presión y con impacto en el negocio.

Errores y trazabilidad: las señales que indican si una integración está lista

Si el contrato define qué se espera, el manejo de errores y la trazabilidad definen qué ocurre cuando esa expectativa no se cumple. Aquí es donde muchas integraciones que "funcionan en pruebas" se caen en producción.

Tipos de error y su propagación. Una integración preparada distingue entre errores de validación, de autorización, de negocio, de disponibilidad y de timeout. No los agrupa todos en un "error 500" genérico. Además, define cómo se propagan: qué error ve el sistema consumidor, qué queda registrado internamente y qué se notifica a operaciones. Sin esta distinción, cada incidente se investiga desde cero.

Idempotencia. En procesos que pueden reintentarse —pagos, emisión de documentos, actualización de estados— la integración debe garantizar que repetir una operación no genere duplicados ni efectos secundarios no deseados. Esto se acuerda en el contrato y se verifica antes de conectar, no se descubre cuando un reintento automático genera dos registros.

Correlación de eventos. Cada transacción debe poder rastrearse de extremo a extremo mediante un identificador común. Esto permite reconstruir qué pasó cuando un dato aparece en un sistema y no en otro, y es la base de cualquier investigación operativa seria.

Evidencia auditable. La trazabilidad no es solo para depurar. En sectores regulados, y en preparación para exigencias como la Ley 21.719 en materia de datos personales, la capacidad de demostrar qué se hizo, cuándo y con qué autorización es un control operativo. No se trata de garantizar cumplimiento, sino de contar con registros que permitan responder ante una revisión, una auditoría o una solicitud de un titular de datos.

Comportamiento ante fallas parciales. Qué ocurre si el sistema destino está disponible pero lento, si responde con datos incompletos, si acepta la operación pero no confirma. Una integración lista tiene definido qué hacer en cada escenario y cómo evitar que una falla parcial se convierta en inconsistencia de datos.

Estas señales se verifican con pruebas concretas antes de habilitar el tráfico real, y quedan documentadas como evidencia de preparación.

Errores frecuentes y límites al evaluar una integración

Al revisar si una integración está lista, hay patrones que conviene reconocer a tiempo.

Acoplamiento oculto. Dos sistemas que parecen independientes comparten supuestos no declarados: mismo formato de fecha, misma zona horaria, mismo catálogo de códigos. Cuando uno cambia, el otro falla sin que nadie haya modificado el contrato. No se detecta leyendo la documentación, sino revisando qué supuestos comparten los equipos y no están escritos.

Supuestos no documentados. "Ese campo siempre viene", "ese sistema nunca responde vacío", "el reintento lo maneja el otro equipo". Cada supuesto no documentado es una falla futura con responsable difuso.

Dependencia de comportamiento no especificado. Cuando la integración depende de cómo se comporta hoy un sistema, y no de lo que su contrato garantiza, cualquier cambio interno del proveedor o del equipo dueño puede romperla sin previo aviso.

Deuda operativa acumulada. Integraciones conectadas "para salir del paso" y nunca cerradas: sin versionado, sin manejo de errores tipificado, sin trazabilidad. Funcionan hasta que dejan de hacerlo, y en ese momento el costo de reconstruir el contexto es alto.

Reconocer estos patrones no siempre lleva a detener la integración. A veces lleva a aceptarla con riesgos explícitos y un plan de mitigación. Lo importante es que la decisión sea consciente.

Criterio práctico para evaluar una integración en una operación real

Antes de habilitar una integración en producción, conviene poder responder con evidencia, no con intención, a un conjunto acotado de preguntas:

• ¿El contrato está escrito, versionado y accesible para ambos equipos?
• ¿Están definidos los tipos de error, su propagación y el comportamiento esperado ante cada uno?
• ¿La operación es idempotente donde corresponde y está probado?
• ¿Existe un identificador de correlación que permita rastrear una transacción de extremo a extremo?
• ¿Hay registros suficientes para reconstruir qué pasó ante una falla o una revisión?
• ¿Están acordados los límites de tasa, timeouts y ventanas de mantención?
• ¿Está claro quién responde por qué, tanto en operación normal como en incidentes?
• ¿Se probaron escenarios de falla parcial, no solo el camino feliz?

Si varias de estas respuestas son "no" o "depende", la integración probablemente no está lista para producción, aunque las pruebas funcionales hayan pasado. Ese es el punto de control: no se trata de bloquear por perfeccionismo, sino de decidir con información si el riesgo es aceptable y qué se hará para cubrirlo.

En organizaciones donde la integración entre sistemas es parte de la operación diaria, este criterio se vuelve una práctica recurrente. El Desarrollo de Software orientado a integraciones empresariales suele apoyarse en estos puntos de control para reducir deuda operativa y evitar que cada conexión nueva se convierta en un problema abierto.

Si en tu organización hay integraciones que funcionan pero nadie sabe exactamente por qué, o que se caen sin que quede claro dónde, vale la pena revisar qué quedó definido antes de conectarlas.