Conectar una API externa parece sencillo cuando el ejemplo de documentación muestra una petición y una respuesta. En producción, la integración también debe resolver autenticación, expiración de credenciales, respuestas inválidas, tiempos de espera, cambios de versión, reintentos y diagnóstico.
La API externa no debería definir el dominio interno
Si todo el sistema utiliza directamente los nombres, estados y estructuras de un proveedor, cambiar esa integración puede convertirse en una modificación transversal. Una capa intermedia permite traducir el contrato externo al modelo propio y concentrar en un lugar la lógica específica del servicio.
Diseñar para el error
Una integración robusta asume que el servicio puede fallar. Conviene distinguir errores temporales de errores definitivos, registrar la respuesta relevante y decidir cuándo un reintento automático es seguro. Repetir una operación financiera o fiscal sin idempotencia, por ejemplo, puede ser peor que dejarla pendiente para revisión.
Autenticación y secretos
Tokens, certificados, claves y contraseñas no deberían quedar hardcodeados en el repositorio. Se administran por entorno o cliente, con permisos restringidos y mecanismos de renovación cuando el proveedor lo exige.
Observabilidad
Los logs deben permitir reconstruir qué endpoint se llamó, en qué momento, para qué entidad interna y cuál fue el resultado, evitando almacenar secretos o información sensible innecesaria. Sin esa trazabilidad, cada incidencia termina investigándose a ciegas.
Un ejemplo: integración fiscal multiempresa
En el caso de la integración fiscal ARCA, la capa central administra configuración por cliente, certificados, autenticación, endpoints y registros de transacción. Las aplicaciones consumidoras no necesitan replicar toda esa complejidad.
La misma lógica puede aplicarse a correo, pagos, videollamadas y otros servicios: encapsular la dependencia, hacer visibles los errores y conservar un contrato interno estable.