Una integración no es solo una conexión entre dos herramientas. Es un acuerdo operativo sobre cuál sistema controla cada dato, quién puede cambiarlo, qué ocurre cuando falla una dependencia y cómo reconstruir un evento después. Esta guía ofrece una arquitectura de referencia para tomar esas decisiones antes de implementar.
Empiece por el límite operativo
Enumere actores, decisiones, registros, excepciones y entregas del flujo. Después identifique qué debe permanecer en un producto existente y qué corresponde al sistema interno. Un límite útil reduce propiedad duplicada: la identidad del cliente puede vivir en un sistema, las facturas en otro y el estado operativo en la aplicación interna.
No comience con un diagrama de tecnologías. Comience con una tabla de responsabilidad: registro, sistema de verdad, escritores permitidos, lectores, reglas de validación, necesidad de retención e impacto de un fallo.
Tabla mínima de responsabilidad
| Pregunta | Decisión a registrar | Por qué importa |
|---|---|---|
| Fuente de verdad | Un sistema autoritativo por dato de negocio | Evita valores contradictorios |
| Autoridad de cambio | Roles o sistemas que pueden escribir | Limita cambios accidentales o no autorizados |
| Expectativa de sincronización | Inmediata, programada o manual | Define latencia y manejo de fallos |
| Responsable del fallo | Persona o equipo que recupera | Evita deuda operativa silenciosa |
| Necesidad de auditoría | Eventos y contexto que se conservan | Permite investigar y rendir cuentas |
Defina el contrato, no solo el endpoint
Un contrato API debe definir campos, formatos, valores obligatorios, autenticación, errores y versiones. OpenAPI ofrece una forma estándar e independiente del lenguaje para describir API HTTP. El contrato debe revisarse junto con las reglas de negocio: un dato técnicamente válido aún puede ser operativamente incorrecto.
Use una forma de error consistente, haga explícitos los reintentos y decida qué operaciones deben ser idempotentes. RFC 9457 define un formato legible por máquinas para detallar problemas en API HTTP; es una base útil cuando los sistemas participantes pueden soportarlo.
Diseñe el fallo antes del camino ideal
- Defina tiempos límite y reintentos acotados.
- Use idempotencia o deduplicación cuando repetir una solicitud pueda crear acciones duplicadas.
- Registre identificadores de correlación para seguir una operación entre sistemas.
- Envíe eventos irrecuperables a una cola de revisión con contexto suficiente para una decisión humana.
- Muestre estados parciales a los operadores; no presente datos desactualizados como sincronizados.
- Defina procedimientos de reproducción y conciliación antes del lanzamiento.
Permisos y trazabilidad son controles diferentes
La autorización determina si un actor puede ejecutar una acción. La trazabilidad registra lo ocurrido: actor, momento, acción, registro afectado y contexto relevante antes/después. Un control no reemplaza al otro.
Use privilegio mínimo y separe acciones administrativas de los roles cotidianos. Aplique controles según los datos y riesgos reales. El proyecto OWASP API Security es una lista útil orientada a amenazas, pero no reemplaza una revisión de seguridad específica del proyecto.
La observabilidad debe responder preguntas operativas
Logs, métricas y alertas sirven cuando alguien puede actuar. Defina señales como sincronizaciones fallidas, antigüedad del evento pendiente, reintentos agotados, cargas inválidas y diferencias de conciliación. Asigne dueño y acción a cada alerta.
Evite colocar datos sensibles completos en logs. Conserve solo lo que la investigación y el contexto regulatorio requieran, con acceso y retención documentados.
Planifique migración y conciliación juntas
Antes de importar, examine duplicados, identificadores faltantes, formatos contradictorios, registros huérfanos y campos sin responsable. Establezca reglas de mapeo y un flujo para filas rechazadas. Mantenga un registro reproducible de la migración.
En lanzamientos por fases, defina qué sistema puede escribir en cada etapa. Un periodo temporal en paralelo puede validar comportamiento, pero dos escritores sin control crean ambigüedad. Criterios de conciliación y reversión deben acordarse antes del corte.
¿Construir, comprar o integrar?
| Opción | Mejor encaje | Riesgo principal a probar |
|---|---|---|
| Configurar un producto existente | Flujo común y restricciones aceptables | Distorsión del proceso o dependencia del proveedor |
| Integrar productos existentes | Las capacidades encajan, pero los datos están fragmentados | Límites API, responsabilidad y recuperación |
| Construir un sistema interno | Reglas o flujo diferenciador no caben en herramientas estándar | Alcance, adopción, mantenimiento y ciclo de vida |
Lista de revisión de arquitectura
- Nombre la fuente de verdad para cada registro importante.
- Defina escritores, lectores, roles y aprobaciones excepcionales.
- Documente contratos API y supuestos de versiones.
- Especifique tiempos límite, reintentos, idempotencia, reproducción y conciliación.
- Defina eventos de auditoría sin recolectar datos sensibles en exceso.
- Asigne alertas de monitoreo y responsabilidad de recuperación.
- Pruebe migración, corte, reversión y conciliación continua.
- Registre qué se configura, integra y construye—y por qué.
Referencias técnicas primarias
Estas fuentes respaldan los estándares y conceptos de seguridad utilizados. Las recomendaciones de arquitectura son una síntesis editorial de The Agency Costa Rica.
- OpenAPI SpecificationOpenAPI Initiative
- RFC 9457: Problem Details for HTTP APIsRFC Editor
- OWASP API Security ProjectOWASP Foundation
Un sistema interno confiable hace visibles la responsabilidad, el estado, las excepciones y la recuperación. La arquitectura correcta es la más pequeña que maneja el flujo real y sus fallos sin crear una segunda fuente de confusión operativa.