Publicação de eventos

Por que isso importa

A publicação de eventos permite que seus sistemas reajam às transações no momento em que acontecem — dispare notificações para clientes, sincronize seu ERP, alimente dashboards de analytics ou inicie workflows de conformidade. Tudo isso sem criar acoplamento rígido entre seus sistemas. As seções abaixo cobrem a configuração técnica. Para uma visão geral orientada a negócios, veja Sobre o Midaz.

Habilitando eventos de transação

A publicação de eventos de transação está habilitada por padrão — o Midaz trata a variável como habilitada, a menos que você a defina explicitamente como false. A configuração de exemplo incluída a define como false, portanto, em um stack iniciado a partir desse exemplo, garanta que a variável não esteja como false (ou defina-a como true) na aplicação de transação:

RABBITMQ_TRANSACTION_EVENTS_ENABLED=true

Com a variável habilitada, o Midaz publica eventos no seguinte exchange do RabbitMQ:

transaction.transaction_events.exchange

Tipos de evento

O Midaz emite um dos seguintes tipos de evento dependendo do ciclo de vida da transação:

Ação	Descrição
`APPROVED`	A transação foi concluída com sucesso. Isso inclui transações de etapa única e transações de duas fases que foram confirmadas (committed).
`PENDING`	Uma transação de duas fases foi criada e está aguardando confirmação (commit) ou cancelamento.
`CANCELED`	Uma transação de duas fases foi cancelada antes da confirmação.
`CREATED`	Uma transação de reversão foi iniciada. Esse é um status transitório que progride para `APPROVED` assim que o processamento é concluído.
`NOTED`	Uma transação de anotação foi registrada. A transação é registrada no ledger sem afetar os saldos das contas.

Exemplo de payload de 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"
      }
    ]
  }
}

O payload completo inclui timestamps, snapshots de saldo e outros identificadores usados para auditoria e rastreabilidade.

Modelo de roteamento de eventos

Para garantir flexibilidade e escalabilidade, o Midaz usa um topic exchange para publicar mensagens em vez de enviá-las diretamente para filas específicas. Isso significa que você controla quais eventos receber configurando seus próprios bindings.

Como o roteamento funciona

Cada evento publicado pelo Midaz é marcado com uma routingKey usando o formato:

midaz.transaction.<status>

Onde <status> corresponde ao status atual da transação (APPROVED, PENDING, CANCELED, CREATED ou NOTED). Para consumir eventos, sua aplicação deve:

Criar uma fila no RabbitMQ.

Vincular sua fila ao exchange do Midaz usando o padrão de routingKey que corresponde ao seu interesse.

Visão geral visual

Modelo de roteamento de eventos do Midaz, mostrando como os eventos publicados chegam às filas de assinantes vinculadas ao exchange por padrões de routing key

Você pode configurar múltiplas filas com diferentes bindings para atender equipes ou serviços específicos de forma independente.

Exemplo de fila e binding

Criando uma nova fila

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

Vinculando a fila para receber todos os eventos

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

O wildcard * corresponde aos cinco status: APPROVED, PENDING, CANCELED, CREATED e NOTED. Para assinar apenas eventos específicos, substitua o wildcard pelo status exato — por exemplo, midaz.transaction.NOTED para receber apenas eventos de anotação.

O Midaz não gerencia nem cria filas do RabbitMQ para você. Você é responsável por provisionar as filas e configurar os bindings corretos.

​Por que isso importa

​Habilitando eventos de transação

​Tipos de evento

​Exemplo de payload de evento

​Modelo de roteamento de eventos

​Como o roteamento funciona

​Visão geral visual

​Exemplo de fila e binding

​Criando uma nova fila

​Vinculando a fila para receber todos os eventos

Por que isso importa

Habilitando eventos de transação

Tipos de evento

Exemplo de payload de evento

Modelo de roteamento de eventos

Como o roteamento funciona

Visão geral visual

Exemplo de fila e binding

Criando uma nova fila

Vinculando a fila para receber todos os eventos