Es fácil demostrar una integración cuando ambos sistemas responden rápido y todas las solicitudes funcionan. El diseño difícil empieza cuando un proveedor acepta un pedido pero su respuesta desaparece, un límite de solicitudes interrumpe una importación grande o un evento llega dos veces. Son condiciones habituales de los sistemas conectados, no excepciones extrañas que puedan dejarse para después.
Una integración fiable da a cada operación de negocio un estado comprensible, limita el trabajo que realiza y ofrece una vía para resolver la incertidumbre. El objetivo no es ocultar todos los fallos. Es evitar que los problemas temporales se conviertan silenciosamente en pedidos perdidos, registros duplicados o confusión permanente para las personas que utilizan la aplicación.
Define el contrato de negocio antes del transporte
Empieza por el significado del intercambio. ¿Qué evento provoca la solicitud? ¿Qué sistema controla el registro resultante? ¿Qué significa aceptarla y cómo se confirmará su finalización? Una respuesta HTTP correcta puede significar que el trabajo ha terminado o solo que otro sistema lo ha colocado en una cola.
Escribe ejemplos de resultados normales y excepcionales con el responsable del negocio. Incluye un cliente inválido, un producto no disponible y una operación que tarda más de lo previsto. Distingue los fallos que puede corregir el usuario de aquellos que requieren que los sistemas se recuperen.
Registra los límites del contrato externo: autenticación, frecuencia permitida, tamaño de mensajes y expectativas de versionado. Estas restricciones influyen en la experiencia del usuario. Un proveedor que procesa lentamente las solicitudes puede exigir un estado pendiente visible en lugar de una interfaz que prometa resultados inmediatos.
Da una identidad estable a cada operación importante
Cuando un cliente agota el tiempo de espera, no siempre puede saber si el servidor realizó la acción. Repetir ciegamente la solicitud puede duplicar sus efectos. Utiliza un identificador de operación estable y un mecanismo acordado para gestionar duplicados cuando el servicio externo lo admita.
En una exportación hipotética de pedidos, conserva un registro local que conecte el pedido interno, su revisión y el identificador del envío externo. Repetir el mismo envío debe recuperar el resultado conocido o reconocerse como la misma operación de negocio. Un pedido modificado puede necesitar una revisión nueva en lugar de reutilizar la identidad original.
Una clave de idempotencia no hace magia por sí sola. Define cuánto tiempo es válida, qué detalles de la solicitud representa y cómo se gestionan los conflictos. Si un proveedor no ofrece protección adecuada contra duplicados, la integración puede necesitar consultas y conciliación antes de reintentar una escritura incierta.
Reintenta solo cuando otro intento pueda ayudar
Algunos fallos son temporales, como una breve interrupción de conectividad. Otros, como datos inválidos o falta de permisos, no mejorarán al repetirlos. Clasifica las respuestas antes de decidir si reintentar. El patrón Retry de Microsoft trata los fallos transitorios, las pausas entre intentos y la importancia de la idempotencia.
Establece un máximo de intentos y un plazo total. Aumenta las pausas cuando corresponda y evita que todos los clientes reintenten exactamente a la vez. Respeta las indicaciones del proveedor y sus límites de solicitudes, en lugar de crear demanda adicional cuando ya tiene dificultades.
Comprueba si varias capas realizan reintentos. Un navegador, una puerta de enlace y un cliente de servicio pueden repetir la misma operación y multiplicar los intentos por encima de lo previsto por cualquier desarrollador. Decide qué capa controla la política y expón suficiente información para conocer el número real de llamadas externas.
Deja de presionar una dependencia que no funciona
Una caída persistente necesita una respuesta distinta de una interrupción breve. Seguir enviando solicitudes puede consumir recursos sin producir nada útil. Un mecanismo de cortacircuitos puede detener temporalmente las llamadas tras un patrón de fallos y permitir intentos controlados para comprobar si la dependencia se ha recuperado.
La experiencia del usuario sigue necesitando un resultado definido. Puede ser apropiado dejar una solicitud pendiente, ofrecer una vía manual o mostrar una indisponibilidad temporal explícita. Devolver un resultado aparentemente correcto mientras se descarta el trabajo normalmente no lo es.
Contén el alcance del fallo. Que un proveedor de conversión documental no esté disponible no debería impedir consultar registros de clientes existentes, salvo que esa dependencia sea realmente necesaria. Revisa qué operaciones requieren el servicio externo y cuáles pueden continuar con limitaciones descritas con claridad.
Mantén un registro duradero del trabajo sin terminar
Si una operación debe sobrevivir al reinicio de un proceso, guarda su estado en un lugar duradero. Registra cuándo se aceptó, qué intentos se hicieron y qué pruebas confirman su finalización. Una lista en memoria no conserva de forma fiable los compromisos del negocio cuando la aplicación se detiene.
Considera la separación entre guardar un cambio de negocio y comunicarlo a otro sistema. Si ocurren por separado, un fallo intermedio puede dejar un registro sin su mensaje correspondiente. El patrón outbox permite registrar el mensaje previsto junto al cambio de negocio y publicarlo después de forma asíncrona; la entrega y los duplicados siguen necesitando su propio diseño.
Haz visibles las excepciones para un operador. Una cola de elementos fallidos debe incluir un motivo útil, el registro de negocio relacionado y una siguiente acción segura. Evita un único botón genérico de «reintentar todo» que repita efectos caros o irreversibles sin revisión.
Diseña para duplicados y eventos fuera de orden
Los consumidores de webhooks y mensajes no deben asumir que cada evento llega una sola vez o en orden cronológico. Una actualización retrasada puede llegar después de otra más reciente, y el emisor puede repetir un aviso si no recibió confirmación. Utiliza los identificadores de evento y la información de orden del proveedor cuando estén disponibles.
Comprueba si la integración debe aplicar el evento directamente o recuperar el registro actual de referencia. La elección depende del contrato externo y de si importan los estados intermedios. Documenta cómo se gestionan registros eliminados, correcciones y avisos retrasados.
Valida el emisor y el contenido antes de procesar. Separa autenticación y validación de negocio: una solicitud del proveedor esperado puede contener un evento no admitido o una relación inválida. Registra pruebas suficientes para investigar sin conservar credenciales ni contenidos sensibles innecesarios.
Concilia los resultados, además de las solicitudes correctas
Compara periódicamente los registros importantes de ambos sistemas. En una integración de pedidos, confirma que los pedidos internos aceptados tienen los identificadores y estados externos esperados. Investiga los registros sin correspondencia y las discrepancias, incluidas operaciones que parecían correctas en la capa de transporte.
Prueba fallos ambiguos en un entorno controlado: una respuesta perdida tras la aceptación, un límite de solicitudes, un webhook repetido y un reinicio durante el procesamiento. Estos ejercicios muestran si el modelo de estados sigue siendo comprensible cuando se rompe el recorrido previsto.
Worktechlabs construye integraciones entre aplicaciones con responsables explícitos, procesamiento recuperable y resultados verificables. Acompáñalas de supervisión en producción para que un problema temporal del proveedor genere un estado sobre el que se pueda actuar, en lugar de un error de negocio oculto.
