Publicador de eventos

Por qué es importante

La publicación de eventos permite que tus sistemas reaccionen a las transacciones en el momento en que ocurren: activa notificaciones a clientes, sincroniza tu ERP, alimenta tableros de análisis o inicia flujos de trabajo de cumplimiento. Todo esto sin acoplar estrechamente tus sistemas entre sí. Las secciones a continuación cubren la configuración técnica. Para una visión general orientada al negocio, consulta Sobre Midaz.

Habilitar eventos de transacción

La publicación de eventos de transacción está habilitada por defecto: Midaz trata la variable como habilitada salvo que la definas explícitamente en false. La configuración de ejemplo incluida la establece en false, así que en un stack iniciado desde ese ejemplo, asegúrate de que la variable no esté en false (o defínela en true) en la aplicación de transacciones:

RABBITMQ_TRANSACTION_EVENTS_ENABLED=true

Con la variable habilitada, Midaz publica eventos en el siguiente intercambio en RabbitMQ:

transaction.transaction_events.exchange

Tipos de eventos

Midaz emite uno de los siguientes tipos de eventos dependiendo del ciclo de vida de la transacción:

Acción	Descripción
`APPROVED`	La transacción se completó exitosamente. Esto incluye transacciones de un solo paso y transacciones de dos fases que se han confirmado.
`PENDING`	Se creó una transacción de dos fases y está esperando confirmación o cancelación.
`CANCELED`	Una transacción de dos fases fue cancelada antes de la confirmación.
`CREATED`	Se inició una transacción de reversión. Este es un estado transitorio que progresa a `APPROVED` una vez completado el procesamiento.
`NOTED`	Se registró una transacción de anotación. La transacción queda registrada en el libro contable sin afectar los saldos de las cuentas.

Ejemplo de carga útil del evento

{
  "source": "midaz",
  "eventType": "transaction",
  "action": "APPROVED",
  "timestamp": "0000-00-00T18:09:03.757330233Z",
  "version": "v3.0.0",
  "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7",
  "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc",
  "payload": {
    "id": "0198575f-a8f9-7924-a6d7-8122f2c77ddd",
    "status": {
      "code": "APPROVED",
      "description": "APPROVED"
    },
    "amount": "1",
    "assetCode": "BRL",
    "source": ["account:1"],
    "destination": ["account:2"],
    "metadata": {
      "key": "value"
    },
    "operations": [
      {
        "type": "DEBIT",
        "amount": { "value": "1" },
        "accountAlias": "account:1"
      },
      {
        "type": "CREDIT",
        "amount": { "value": "1" },
        "accountAlias": "account:2"
      }
    ]
  }
}

La carga útil completa incluye marcas de tiempo, instantáneas de saldo y otros identificadores usados para auditoría y trazabilidad.

Modelo de enrutamiento de eventos

Para garantizar flexibilidad y escalabilidad, Midaz usa un intercambio de tipo topic para publicar mensajes en lugar de enviarlos directamente a colas específicas. Esto significa que controlas qué eventos recibir configurando tus propios enlaces.

Cómo funciona el enrutamiento

Cada evento publicado por Midaz se etiqueta con una routingKey usando el formato:

midaz.transaction.<status>

Donde <status> corresponde al estado actual de la transacción (APPROVED, PENDING, CANCELED, CREATED o NOTED). Para consumir eventos, tu aplicación debe:

Crear una cola en RabbitMQ.

Vincular tu cola al intercambio de Midaz usando el patrón de routingKey que coincida con tu interés.

Resumen visual

Modelo de enrutamiento de eventos de Midaz, que muestra cómo los eventos publicados llegan a las colas de suscriptores enlazadas al exchange mediante patrones de routing key — Figura 1. Representación visual del modelo de enrutamiento de eventos.

Puedes configurar múltiples colas con diferentes enlaces para servir a equipos o servicios específicos de forma independiente.

Ejemplo de cola y enlace

Crear una nueva cola

{
  "queues": [
    {
      "name": "new_queue_name.queue",
      "vhost": "/",
      "durable": true
    }
  ]
}

Vincular la cola para recibir todos los eventos

{
  "bindings": [
    {
      "source": "transaction.transaction_events.exchange",
      "vhost": "/",
      "destination": "new_queue_name.queue",
      "destination_type": "queue",
      "routing_key": "midaz.transaction.*"
    }
  ]
}

El comodín * coincide con los cinco estados: APPROVED, PENDING, CANCELED, CREATED y NOTED. Para suscribirte solo a eventos específicos, reemplaza el comodín por el estado exacto — por ejemplo, midaz.transaction.NOTED para recibir solo eventos de anotación.

Midaz no gestiona ni crea colas de RabbitMQ por ti. Eres responsable de aprovisionar las colas y configurar los enlaces correctos.

Midaz Core

CRM

Fees

Publicador de eventos

Por qué es importante

Habilitar eventos de transacción

Tipos de eventos

Ejemplo de carga útil del evento

Modelo de enrutamiento de eventos

Cómo funciona el enrutamiento

Resumen visual

Ejemplo de cola y enlace

Crear una nueva cola

Vincular la cola para recibir todos los eventos

​Por qué es importante

​Habilitar eventos de transacción

​Tipos de eventos

​Ejemplo de carga útil del evento

​Modelo de enrutamiento de eventos

​Cómo funciona el enrutamiento

​Resumen visual

​Ejemplo de cola y enlace

​Crear una nueva cola

​Vincular la cola para recibir todos los eventos

Por qué es importante

Habilitar eventos de transacción

Tipos de eventos

Ejemplo de carga útil del evento

Modelo de enrutamiento de eventos

Cómo funciona el enrutamiento

Resumen visual

Ejemplo de cola y enlace

Crear una nueva cola

Vincular la cola para recibir todos los eventos