Definir eventos, datos y contratos

Un workflow deja de ser un dibujo cuando sus pasos intercambian información concreta. Si dos sistemas interpretan de forma distinta qué significa cliente_id, qué estructura tiene una solicitud o cuándo un evento está completo, el flujo puede fallar aunque cada componente funcione por separado.

Por eso conviene diseñar contratos antes de conectar herramientas. Un contrato define qué información entra, qué información sale, qué campos son obligatorios, qué versión se utiliza y qué errores deben producirse cuando la entrada no cumple lo acordado.

OpenAPI ofrece una forma estandarizada y agnóstica del lenguaje para describir interfaces HTTP. CloudEvents define una forma común de describir datos de eventos. No es obligatorio utilizar estas especificaciones en cada automatización, pero ilustran una idea general: la semántica del intercambio debe estar explícita y ser validable.

Empieza por el evento de negocio

No diseñes primero el payload. Define primero qué hecho representa el intercambio.

solicitud_recibida significa que existe una nueva solicitud que debe empezar a procesarse. presupuesto_aprobado significa que una versión concreta ha sido aprobada. documento_clasificado significa que terminó una decisión de clasificación con un resultado y, posiblemente, una confianza asociada.

El nombre del evento debe permitir entender qué ocurrió sin tener que inspeccionar toda la carga de datos.

Anatomía mínima de un evento

Un evento empresarial suele necesitar más que el dato principal. Como mínimo, considera:

• identificador único del evento;
• tipo;
• instante de ocurrencia;
• identificador del caso;
• origen;
• versión del esquema;
• datos del evento;
• identificador de correlación cuando atraviesa varios servicios.

No todos los campos son obligatorios en todos los sistemas. Lo importante es que la identidad, el significado y la versión puedan conservarse a lo largo del workflow.

Ejemplo conceptual:

{
  "event_id": "evt_123",
  "type": "solicitud_recibida",
  "case_id": "REQ-2026-0042",
  "schema_version": 1,
  "occurred_at": "2026-08-17T10:00:00Z",
  "data": {
    "customer_id": "C-102",
    "requested_items": 3
  }
}

El ejemplo es didáctico. No pretende imponer un estándar de nombres.

Diseña el esquema desde las decisiones reales

Cada campo debe existir porque alguien lo necesita para decidir, ejecutar o auditar. Si una regla de descuento depende del segmento del cliente, necesitas una referencia fiable a ese segmento. Si una aprobación depende del importe, el contrato debe incluir el importe y la moneda con una representación inequívoca.

Evita copiar estructuras completas de un sistema a otro “por si acaso”. Cuantos más datos circulan, más acoplamiento, exposición y dificultad de versionado introduces.

Una técnica útil es recorrer cada transición del workflow y preguntar: ¿qué datos son necesarios para permitirla y cuál es la fuente autorizada de cada uno?

Valida en la frontera

La validación temprana reduce estados corruptos. Si un webhook declara que customer_id es obligatorio, no conviene descubrir tres pasos después que falta.

Distingue entre:

• validez estructural: tipos, campos obligatorios, formato;
• validez semántica: el cliente existe, la moneda está permitida, el estado actual admite esa transición;
• validez de negocio: la operación cumple reglas y autorizaciones.

Un JSON bien formado puede ser semánticamente inválido. La estructura no sustituye las reglas del dominio.

Versiona sin romper consumidores

Los contratos cambian. Aparecen campos nuevos, se retiran otros o cambia el significado de una operación. El problema no es que exista evolución, sino que ocurra de forma implícita.

Define una política de compatibilidad. Añadir un campo opcional suele ser menos disruptivo que cambiar el tipo de uno existente. Si una modificación rompe consumidores, necesita una versión nueva o una transición controlada.

No asumas que “v2” resuelve por sí sola el problema. Debes saber qué productor emite cada versión, qué consumidores la soportan y cuándo puede retirarse la anterior.

Define operaciones, no solo datos

Una integración necesita describir también qué se puede hacer: consultar, crear, actualizar, confirmar, cancelar o aprobar. Para cada operación registra:

• precondiciones;
• entrada;
• salida;
• códigos o categorías de error;
• efecto esperado;
• si produce una mutación;
• si puede repetirse con seguridad;
• timeout esperado.

Esta información será necesaria cuando diseñes reintentos e idempotencia.

Conserva identidad y correlación

Un mismo caso puede atravesar correo, CRM, ERP y servicios internos. Si cada sistema crea su propio identificador sin conservar relación con los demás, investigar un fallo se vuelve costoso.

Diseña una estrategia de correlación. Puede existir un case_id de negocio y, además, identificadores técnicos de petición, evento o traza. No tienen que ser el mismo valor, pero debe ser posible relacionarlos.

Cuando interviene IA

Una salida de IA no debe introducirse como si tuviera la misma naturaleza que un dato maestro. Si un modelo clasifica un mensaje o extrae un campo, el contrato puede necesitar información adicional: modelo o versión cuando sea relevante, confianza o evidencia cuando exista, estado de revisión y texto original de referencia.

No conviertas la “confianza” de un proveedor en una garantía estadística si no sabes qué significa. Diseña el contrato para conservar la incertidumbre de forma explícita.

Ejercicio: especifica tres contratos

Selecciona tres fronteras del workflow y documenta para cada una:

1. evento u operación;
2. productor;
3. consumidor;
4. esquema mínimo;
5. campos obligatorios;
6. validaciones estructurales;
7. validaciones de negocio;
8. errores esperados;
9. estrategia de versión;
10. identificador de correlación.

Incluye al menos una frontera con un sistema externo y otra en la que exista una salida producida por IA o por una persona.

Resultado de la lección

El workflow ya no mueve conceptos vagos: mueve eventos y datos con significado, identidad y reglas de validación. La siguiente lección utilizará esos contratos para formalizar decisiones y separar qué debe resolverse mediante reglas, cálculo, IA o juicio humano.