Contrato, errores y trazabilidad: definir la API antes de integrar

Antes de conectar dos sistemas, la mayoría de los equipos discute endpoints, formatos y autenticación. Pocos discuten qué pasa cuando algo falla a las 3 de la mañana, quién puede diagnosticarlo y con qué evidencia. Esa omisión convierte una integración razonable en deuda operativa: el sistema funciona en condiciones normales, pero nadie puede explicar por qué dejó de hacerlo.

Este artículo no trata sobre qué exigir a un proveedor ni sobre decisiones de arquitectura en abstracto. Trata sobre tres condiciones que deben quedar definidas antes de integrar: el contrato operativo de la API, la semántica de sus errores y la trazabilidad mínima de extremo a extremo. Si esas tres piezas no están resueltas, la integración se sostiene sobre supuestos que se rompen en el primer incidente.

El contrato de API como acuerdo operativo, no solo técnico

Un contrato de API suele entenderse como la especificación técnica: rutas, métodos, esquemas de datos, códigos de estado. Es necesario, pero insuficiente para una operación empresarial. El contrato que importa para gerencia TI, infraestructura y continuidad es el que define qué se compromete la API a entregar y bajo qué condiciones.

Ese contrato operativo debería cubrir, como mínimo:

• Alcance funcional explícito. Qué operaciones están soportadas y cuáles no. Un consumidor que asume que puede consultar un histórico completo cuando la API solo expone los últimos 90 días descubre el límite en producción.
• Volumetría y límites. Solicitudes por unidad de tiempo, tamaño máximo de payload, ventanas de mantención. Sin esto, el consumidor no puede dimensionar su carga ni anticipar degradaciones.
• Acuerdos de nivel de servicio observables. No basta con "alta disponibilidad". Conviene definir latencia esperada por tipo de operación, comportamiento ante saturación y qué se considera una falla atribuible a la API versus al consumidor.
• Versionamiento y política de cambio. Cómo se comunican cambios incompatibles, con cuánta anticipación y por qué canal. Una integración sin política de versionamiento queda expuesta a que un cambio silencioso rompa un proceso de negocio.
• Dependencias declaradas. Si la API depende de un sistema interno, de un tercero o de un proceso batch, eso debe estar escrito. El consumidor necesita saber qué fallas externas se propagan.

La diferencia entre un contrato técnico y uno operativo es que el segundo permite responder preguntas de negocio: ¿qué proceso se ve afectado si esta API no responde?, ¿cuánto tiempo tolera la operación una degradación?, ¿quién decide si se activa un plan de contingencia?

Cuando el contrato queda solo en la especificación, esas preguntas se responden durante el incidente, con presión y sin información. Definirlas antes es parte del trabajo de diseño y requiere coordinación entre quien construye la API y quienes operan los sistemas que la consumen. En proyectos donde esa coordinación no existe de forma natural, conviene incorporarla explícitamente al alcance, como se hace en un Desarrollo de Software orientado a operación y no solo a entrega funcional.

Semántica de errores: cómo se nombran determina cómo se responde

Un error mal clasificado obliga a operaciones a investigar lo que el sistema ya sabía. Un error bien clasificado permite actuar sin ambigüedad: reintentar, escalar, detener un proceso o registrar para análisis posterior.

El problema frecuente no es la ausencia de códigos de error, sino su falta de semántica operativa. Un 500 genérico no distingue entre una falla transitoria, un error de datos del consumidor o una dependencia caída. Esa distinción es exactamente lo que necesita quien está de turno a las 3 de la mañana.

Criterios que conviene fijar antes de integrar:

• Distinguir error de cliente, de servidor y de dependencia. Un error causado por datos inválidos del consumidor no se resuelve igual que uno causado por un sistema interno caído. Mezclarlos impide automatizar respuestas.
• Marcar explícitamente lo reintentable. Reintentar un error de validación genera carga inútil; no reintentar un error transitorio pierde operaciones recuperables. La API debería declarar cuáles son reintentables y con qué política.
• Evitar mensajes que filtren detalle interno. Un mensaje que expone rutas, nombres de tablas o stack traces confunde al consumidor y expone información que no le corresponde.
• Definir el comportamiento ante errores parciales. En operaciones que afectan múltiples registros, ¿la API falla completa o reporta éxito parcial? Esa decisión cambia cómo el consumidor debe reconciliar.
• Establecer un identificador de correlación en cada respuesta de error. Sin él, el consumidor no puede referenciar el incidente ante el equipo que opera la API.

La semántica de errores no es un detalle de implementación. Es lo que permite que dos equipos distintos —el que opera la API y el que opera el sistema consumidor— hablen del mismo incidente sin reconstruirlo desde cero.

Trazabilidad de extremo a extremo: qué registrar y para qué

La trazabilidad se suele reducir a "tener logs". Pero un log sin correlación entre sistemas no sirve para diagnosticar una integración: muestra eventos aislados que nadie puede ordenar en una secuencia.

La trazabilidad útil responde a una pregunta concreta: dado un fallo, ¿puedo reconstruir qué pasó, en qué orden y con qué datos, sin depender del equipo que construyó la integración?

Eso implica definir, antes de integrar:

• Un identificador de correlación que atraviese todos los sistemas. El mismo identificador debe aparecer en la solicitud del consumidor, en el procesamiento interno de la API y en cualquier sistema downstream. Sin esto, la reconstrucción es manual y lenta.
• Qué se registra y qué no. Registrar todo genera ruido y costo; registrar poco deja incidentes sin evidencia. Conviene acordar qué eventos son relevantes para operación y continuidad: inicio y fin de operaciones críticas, errores, cambios de estado, decisiones de reintento.
• Retención y acceso. ¿Cuánto tiempo se conserva la traza? ¿Quién puede consultarla? ¿Está disponible durante un incidente o solo después? Una traza que tarda horas en ser accesible no sirve para operar.
• Datos sensibles. La trazabilidad no puede convertirse en un canal de exposición. Si la API transporta datos personales o financieros, el registro debe considerar qué se almacena y bajo qué controles. En el contexto de la Ley 21.719, esto se traduce en preparación y controles de tratamiento, no en una garantía de cumplimiento automático.
• Trazabilidad de cambios de contrato. Si la API cambia, la traza debe permitir distinguir si un incidente ocurrió antes o después del cambio. Sin esa referencia, se pierde tiempo descartando causas.

La trazabilidad bien definida reduce el tiempo de diagnóstico y, sobre todo, la dependencia de personas específicas. Una integración cuya operación depende de que esté disponible quien la construyó no es sostenible.

Criterio práctico para evaluar una API antes de integrarla

Antes de aprobar una integración, conviene poder responder estas preguntas con documentación, no con supuestos:

1. ¿El contrato operativo está escrito? Alcance, límites, SLA observables, versionamiento y dependencias declaradas.
2. ¿Los errores tienen semántica? Se distingue cliente, servidor y dependencia; se marca lo reintentable; existe identificador de correlación.
3. ¿La trazabilidad permite reconstruir un incidente sin el equipo constructor? Correlación de extremo a extremo, retención definida, acceso durante el incidente.
4. ¿Quién responde por qué? Está claro qué fallas son atribuibles a la API, cuáles al consumidor y cuáles a dependencias externas.
5. ¿Qué pasa cuando la API cambia? Existe política de versionamiento y comunicación, y la traza permite distinguir antes y después.

Si alguna de estas respuestas no existe antes de integrar, no es un problema que se resuelva en producción. Se resuelve en el diseño, y suele ser más barato hacerlo ahí.

No toda integración requiere el mismo nivel de formalización. Una API interna de bajo impacto puede operar con acuerdos mínimos. Pero cuando la integración sostiene un proceso de negocio, afecta a clientes o cruza áreas con responsabilidades distintas, el contrato, la semántica de errores y la trazabilidad dejan de ser opcionales.

La señal de que conviene detenerse y definirlos no es técnica, es operativa: cuando nadie puede responder con precisión qué pasa si esta API falla, cuánto se tolera y cómo se diagnostica, la integración todavía no está lista para conectarse.