> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Publicação de eventos

> Publique eventos de transações no RabbitMQ em tempo real para que sistemas externos reajam sem acoplar fortemente ao Midaz.

## 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](/pt/midaz/about-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:

<CodeGroup>
  ```bash JSON theme={null}
  RABBITMQ_TRANSACTION_EVENTS_ENABLED=true
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash JSON theme={null}
  transaction.transaction_events.exchange
  ```
</CodeGroup>

## 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

***

<CodeGroup>
  ```json JSON expandable theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</CodeGroup>

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

## 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:

<Steps>
  <Step>
    **Criar uma fila** no RabbitMQ.
  </Step>

  <Step>
    **Vincular sua fila** ao exchange do Midaz usando o padrão de routingKey que corresponde ao seu interesse.
  </Step>
</Steps>

### Visão geral visual

<Frame caption="Figura 1. Representação visual do modelo de roteamento de eventos.">
  <img src="https://mintcdn.com/lerian-49cb71fc/ZrZBZTM4DWnrahSd/images/pt/d2/event-publisher.svg?fit=max&auto=format&n=ZrZBZTM4DWnrahSd&q=85&s=42f0f2d1a16e0e285eac1767475216c9" alt="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" width="1947" height="714" data-path="images/pt/d2/event-publisher.svg" />
</Frame>

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

## Exemplo de fila e binding

***

### Criando uma nova fila

<CodeGroup>
  ```json JSON theme={null}
  {
    "queues": [
      {
        "name": "new_queue_name.queue",
        "vhost": "/",
        "durable": true
      }
    ]
  }
  ```
</CodeGroup>

### Vinculando a fila para receber todos os eventos

<CodeGroup>
  ```json JSON theme={null}
  {
    "bindings": [
      {
        "source": "transaction.transaction_events.exchange",
        "vhost": "/",
        "destination": "new_queue_name.queue",
        "destination_type": "queue",
        "routing_key": "midaz.transaction.*"
      }
    ]
  }
  ```
</CodeGroup>

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.

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