Cómo decidir qué datos incluir en un evento de integración

Diseñar un evento de integración parece una decisión técnica, pero determina la autonomía de los equipos, la resiliencia operativa y la calidad de la información que recibe cada proceso. Cuando un CRM, un ERP, un ecommerce y una plataforma de atención intercambian eventos, surge una pregunta recurrente: ¿debe el mensaje incluir todos los datos necesarios o solo una referencia para consultarlos en el sistema origen?

No existe una respuesta universal. Un evento demasiado escueto obliga a realizar consultas encadenadas y convierte al sistema origen en una dependencia constante. Uno excesivamente rico duplica información, puede propagar datos personales innecesarios y corre el riesgo de contener una versión ya obsoleta. La alternativa eficaz es decidir campo por campo, según el uso real del consumidor y las condiciones de operación.

Las tres alternativas para transportar contexto

Un evento puede entregar contexto de tres maneras. Cada modelo resuelve problemas distintos y también introduce costes que deben asumirse explícitamente.

Evento con datos completos

El mensaje incluye la información que el consumidor necesita para ejecutar su acción. Por ejemplo, un evento de pedido confirmado puede transportar líneas de pedido, dirección de entrega, canal de venta y una instantánea de los importes confirmados.

• Conviene usarlo cuando el consumidor debe actuar de inmediato, cuando el valor enviado debe conservarse como evidencia histórica o cuando el sistema origen no tendrá disponibilidad garantizada.
• Reduce llamadas posteriores, latencia y acoplamiento en tiempo de ejecución.
• Exige definir qué representa la información: normalmente una instantánea en el momento del evento, no el estado vivo actual del registro.
• Aumenta el tamaño del mensaje, la complejidad del contrato y la superficie de exposición de datos.

Evento con identificador y consulta posterior

El mensaje contiene un identificador, el tipo de evento y metadatos mínimos; el consumidor consulta después una API o una réplica autorizada. Es apropiado si necesita el dato vigente y no una fotografía histórica.

• Conviene usarlo para atributos volátiles, catálogos extensos o información que el consumidor solo necesita en casos excepcionales.
• Evita distribuir copias de datos que cambian con frecuencia.
• Introduce dependencia de disponibilidad, permisos, límites de consumo y latencia del sistema origen.
• Puede producir consultas en cascada: un servicio consulta el pedido, luego el cliente, después el producto y finalmente el inventario. Esa cadena suele ser frágil y difícil de diagnosticar.

Modelo híbrido

En la mayoría de integraciones maduras, el mejor resultado es híbrido: el evento transporta un núcleo autosuficiente para ejecutar el flujo y referencias para enriquecerlo cuando sea necesario. Un pedido puede incluir su identificador, fecha, estado confirmado, importes, artículos y destino logístico, pero aportar solo el identificador de cliente para consultar preferencias actuales de contacto si una comunicación lo requiere.

La regla no es “enviar poco” ni “enviar todo”: envíe lo necesario para completar de forma fiable la decisión desencadenada, y entregue referencias para los datos que deban ser actuales, sean costosos o no estén autorizados para todos los receptores.

Criterios para decidir cada campo

La unidad correcta de decisión no es el evento completo, sino cada atributo. Un mismo evento puede contener datos inmutables, volátiles, sensibles y derivados, que requieren tratamientos opuestos.

• Inmediatez: si el consumidor debe actuar antes de poder consultar una API, el dato debe viajar. Logística no debería esperar una consulta adicional para conocer la dirección validada que debe usar en el despacho.
• Actualidad: si la decisión requiere el último valor disponible, es preferible una referencia. Las preferencias de comunicación o el estado actual de una cuenta pueden cambiar después del pedido.
• Valor histórico: si interesa reconstruir qué se sabía cuando ocurrió un hecho, incluya una instantánea con fecha. El precio aceptado y los impuestos aplicados no deben reinterpretarse con el catálogo actual.
• Volumen y frecuencia: imágenes, descripciones extensas, documentos o estructuras masivas rara vez pertenecen al mensaje principal. Envíe una referencia estable, una versión y, si procede, un resumen.
• Disponibilidad: si una caída del sistema origen bloquearía un proceso crítico, el evento debe aportar el mínimo necesario para degradar con seguridad.
• Permisos: no todos los consumidores que conocen un identificador deben recibir datos personales, financieros o internos. El evento no debe eludir el modelo de autorización de los sistemas.
• Trazabilidad: todo valor decisivo debe indicar de qué versión o momento procede. Un campo sin contexto temporal puede inducir decisiones erróneas.

Clasifique además los datos. Los inmutables, como un identificador de pedido o una fecha de creación, son candidatos claros para viajar. Los volátiles, como disponibilidad de inventario, suelen requerir consulta o un evento específico de actualización. Los sensibles deben minimizarse, limitarse por audiencia y protegerse según las políticas aplicables. Los derivados, como una segmentación o una puntuación, necesitan indicar su regla, versión o vigencia para que no parezcan hechos permanentes.

Matriz práctica y patrones de diseño

Antes de añadir un campo al contrato, el equipo de negocio, producto y tecnología puede evaluarlo con estas preguntas. Si varias respuestas son afirmativas en la primera parte, probablemente debe incluirse; si predominan las de la segunda, conviene referenciarlo.

1. ¿El consumidor no puede completar su acción sin este valor?
2. ¿Debe conservarse la versión exacta válida al producirse el evento?
3. ¿Una consulta posterior puede fallar o llegar demasiado tarde?
4. ¿Es pequeño y estable dentro del ciclo de vida del proceso?
5. ¿Cambia frecuentemente o solo es necesario en casos particulares?
6. ¿Contiene datos sensibles que el consumidor no necesita de forma explícita?
7. ¿Existe una fuente autorizada y disponible para consultarlo después?
8. ¿El consumidor puede tolerar una respuesta diferida, una caché o una revisión manual?

De esta evaluación derivan tres patrones útiles:

• Instantánea trazable: transporte el dato y añada occurred_at, un identificador de evento, la versión del esquema y, cuando aplique, la versión del recurso. Es idóneo para importes, condiciones aceptadas y destino operativo.
• Referencia enriquecible: envíe un identificador estable, el tipo de recurso y, si existe, una versión. El consumidor consulta solo cuando lo necesita y registra qué respuesta utilizó.
• Datos mínimos con caché controlada: incluya una selección mínima y permita enriquecer desde una copia de lectura con caducidad definida. Es útil para catálogos o perfiles no sensibles donde una ligera demora es admisible.

Un contrato sencillo puede expresar con claridad la diferencia entre hecho e información de consulta:

{
  "event_id": "evt_123",
  "event_type": "order.confirmed",
  "occurred_at": "2025-03-08T10:30:00Z",
  "order": {
    "id": "ord_456",
    "total_confirmed": 125.00,
    "delivery_address_snapshot": { "country": "ES" }
  },
  "customer_ref": { "id": "cus_789" }
}

La dirección incluida es una instantánea operativa; el identificador de cliente permite consultar atributos actuales con autorización. No debe interpretarse que todos los campos del cliente eran válidos o estaban aprobados en el instante del pedido.

Disponibilidad, fallos y degradación operativa

Elegir la consulta posterior obliga a diseñar qué ocurrirá cuando esa consulta falle. No basta con implementar un reintento automático: una indisponibilidad persistente puede generar duplicados, saturar la API origen y bloquear colas completas.

Defina el comportamiento de degradación antes de publicar el evento. Para cada consumidor, acuerde si puede procesar con datos mínimos, reintentar más tarde, pasar a una cola de excepciones o requerir intervención manual. Atención al cliente puede abrir un caso con información parcial; logística quizás deba retener el despacho si falta una dirección verificable.

• Use identificadores de evento e idempotencia para que un reintento no ejecute dos veces la misma acción.
• Separe los errores temporales de los permanentes, como una referencia inexistente o permisos insuficientes.
• Evite reintentos sincronizados y sin límite que amplifiquen una incidencia del sistema origen.
• Observe retraso de colas, errores de enriquecimiento, edad del último dato consultado y porcentaje de procesamiento degradado.
• Conserve una ruta de revisión para decisiones bloqueadas, con el motivo y el evento original disponibles para auditoría.

Versionado, seguridad y gobierno del contrato

Los contratos de eventos evolucionan. Añadir un campo opcional suele ser menos riesgoso que cambiar el significado de uno existente, convertir un campo opcional en obligatorio o retirar información que un consumidor asumía disponible. La compatibilidad no consiste solo en que el mensaje se pueda leer; también exige que conserve su significado de negocio.

Establezca un responsable para cada campo y documente su origen, clasificación, semántica, formato, vigencia y consumidores autorizados. Incluya una versión de esquema y trate los cambios semánticos importantes como nuevas versiones o nuevos tipos de evento. No reutilice un nombre para expresar otra cosa: un campo llamado status sin un catálogo de valores y una definición temporal es una fuente habitual de interpretaciones incompatibles.

En seguridad, aplique minimización de datos. Un evento difundido por una infraestructura compartida puede alcanzar más consumidores de los previstos inicialmente. No incluya datos personales “por si acaso”, secretos, credenciales ni atributos que no tengan una finalidad concreta. Si un proceso necesita información sensible, valore un canal restringido o una consulta autorizada en lugar de propagarla en un evento general.

Ejemplo: pedido para logística, atención y comunicaciones

Imagine que un pedido confirmado activa tres flujos. Logística necesita artículos, cantidades, dirección de envío validada, método de entrega y fecha de confirmación. Esos datos deben viajar como instantánea porque permiten preparar el envío incluso si el ecommerce deja de estar disponible.

Atención al cliente necesita el identificador de pedido, su estado y la referencia del cliente. Puede consultar el historial actualizado del cliente cuando atienda una incidencia, siempre que disponga de permisos. Las comunicaciones transaccionales requieren el tipo de evento y una referencia autorizada al destinatario, pero no necesitan recibir todo el pedido ni el perfil completo del cliente.

Esta separación reduce exposición y evita que un único evento se convierta en una réplica accidental del CRM o del ERP. También aclara responsabilidades: el ecommerce emite el hecho confirmado, logística usa la instantánea de cumplimiento y cada canal consulta únicamente el contexto actual que le corresponde.

Checklist de decisión antes de publicar

• ¿El evento describe un hecho ocurrido o intenta replicar el estado completo de otro sistema?
• ¿Cada campo tiene un consumidor, una finalidad y un responsable identificados?
• ¿Está claro qué campos son instantáneas y cuáles deben consultarse como estado actual?
• ¿Se han minimizado los datos sensibles y definido los permisos de acceso?
• ¿El proceso sigue funcionando, se difiere o escala manualmente si falla el enriquecimiento?
• ¿Existen identificador de evento, fecha de ocurrencia, idempotencia y versión de esquema?
• ¿Los consumidores pueden ignorar campos nuevos sin romperse?
• ¿Hay métricas y alertas para detectar consultas fallidas, retrasos y mensajes no procesados?

La decisión correcta convierte el evento en un contrato de negocio fiable, no en un contenedor arbitrario de datos. Envíe contexto suficiente para que el hecho pueda producir valor de forma autónoma; consulte lo que deba estar actualizado, sea sensible o no sea imprescindible. Así se reduce el acoplamiento sin sacrificar trazabilidad ni continuidad operativa.