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

# Eventos do Pix Indirect via BTG

> CloudEvents que o Pix Indirect via BTG publica para cobranças, chaves e reivindicações DICT, disputas MED, recuperação de fundos, pagamentos, agendamentos e Pix Automático.

O Pix Indirect via BTG publica 63 fatos de negócio JSON como CloudEvents 1.0 em modo binário de conteúdo via Kafka. Estes eventos estão disponíveis em deploys BYOC. O streaming é opcional e fica desligado por padrão. Para ligá-lo, defina `STREAMING_ENABLED=true` e as outras [variáveis de eventos de negócio](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-environment-variables.md#business-events) no componente da API. A [visão geral de streaming de eventos](https://docs.lerian.studio/pt/reference/events/overview.md) descreve o envelope comum.

## Contrato de transporte

| Campo | Valor |
| - | - |
| `ce-source` | O valor de `STREAMING_CLOUDEVENTS_SOURCE`. O padrão é `plugin-br-pix-indirect-btg`. |
| Tópico | `lerian.streaming.<ce-source>` |
| `ce-type` | `studio.lerian.<ce-source>.<event-key>` |
| `ce-tenantid` | O valor de `STREAMING_TENANT_ID`. O padrão é `default`. |
| Versão do schema | `1.0.0` para todo evento |
| Tipo de conteúdo | `application/json` |
| Entrega | Definida por evento. Veja [Entrega](#delivery). |
| Tópico de comandos | Nenhum |
| Manifesto em runtime | `GET /v1/streaming/manifest` |

Se você mudar `STREAMING_CLOUDEVENTS_SOURCE`, o tópico e cada `ce-type` mudam junto. Quando o streaming está ligado, a API serve o catálogo de eventos em `GET /v1/streaming/manifest`. A rota exige o recurso `streaming` do Access Manager com a ação `get`.

## Entrega

Cada evento tem um destes três modos de entrega:

* **Outbox**: a API escreve o evento no seu outbox do PostgreSQL, e um relay o publica no Kafka.
* **Direta, com fallback para o outbox**: a API publica o evento no Kafka. Se os brokers estiverem indisponíveis ou lentos, a API escreve o evento no outbox.
* **Melhor esforço**: a API publica o evento no Kafka, sem outbox.

A publicação de um evento nunca faz falhar a operação de negócio que o produziu. Um evento pode chegar mais de uma vez: deduplique por `(ce-source, ce-id)` e mantenha os consumidores idempotentes. Não dependa da ordem de chegada.

## Catálogo de eventos

### Cobranças

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `collection.created` | O BTG registra uma cobrança Pix, e a API a guarda como `ACTIVE`. Dispara para cobranças imediatas e com vencimento. O campo `type` as diferencia. | Direta, com fallback para o outbox |
| `collection.updated` | O BTG aceita uma alteração em uma cobrança `ACTIVE`, e a API guarda a cobrança com uma nova revisão. | Direta, com fallback para o outbox |
| `collection.deleted` | O BTG aceita a exclusão de uma cobrança imediata `ACTIVE`, e a API a guarda como `DELETED`. | Direta, com fallback para o outbox |
| `collection.completed` | Uma cobrança passa de `ACTIVE` para `COMPLETED`: o pagamento dela é liquidado, ou o endpoint de operador a conclui. | Outbox |

### Chaves DICT e reivindicações

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `dict_entry.created` | Uma chave Pix é guardada como `ACTIVE` para uma das suas contas: pela API, pela conciliação, ou quando uma reivindicação é concluída a seu favor. | Direta, com fallback para o outbox |
| `dict_entry.updated` | O DICT aceita uma alteração nos dados da conta ou do dono de uma chave, e a API a guarda. | Direta, com fallback para o outbox |
| `dict_entry.deleted` | Uma chave sai da sua conta: você a exclui, a conciliação a remove, ou o doador confirma uma reivindicação sobre ela. | Direta, com fallback para o outbox |
| `claim.created` | Existe uma reivindicação de portabilidade ou de posse para uma chave: você a abre como reivindicador, ou o BTG informa uma reivindicação que outro participante abriu sobre a sua chave. | Outbox |
| `claim.acknowledged` | O doador reconhece a reivindicação, e a reivindicação passa para `WAITING_RESOLUTION`. | Direta, com fallback para o outbox |
| `claim.confirmed` | O doador confirma a reivindicação. | Outbox |
| `claim.completed` | A reivindicação chega a `COMPLETED`, e a chave pertence ao reivindicador no DICT. | Outbox |
| `claim.cancelled` | A reivindicação chega a `CANCELLED`, e a chave fica com o doador. | Outbox |

### Recuperação de fundos do MED 2.0

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `funds_recovery.created` | Existe uma recuperação de fundos: você a cria, ou o BTG informa uma que a API não tinha. | Outbox |
| `funds_recovery.tracked` | A recuperação de fundos passa para `TRACKED`, e o grafo de rastreamento dela fica disponível. | Direta, com fallback para o outbox |
| `funds_recovery.awaiting_analysis` | A recuperação de fundos passa para `AWAITING_ANALYSIS`. | Outbox |
| `funds_recovery.analysed` | A recuperação de fundos passa para `ANALYSED`. | Outbox |
| `funds_recovery.refund_requested` | A recuperação de fundos passa para `REFUNDING`. | Outbox |
| `funds_recovery.completed` | O BTG informa a recuperação de fundos como `COMPLETED`. | Outbox |
| `funds_recovery.cancelled` | A recuperação de fundos passa para `CANCELLED`. | Outbox |

### Relatos de infração e solicitações de devolução do MED

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `infraction.created` | Existe um relato de infração: você o abre, ou o BTG entrega um que uma contraparte abriu contra o seu cliente. | Outbox |
| `infraction.acknowledged` | Um relato de infração passa de `OPEN` para `ACKNOWLEDGED`. | Direta, com fallback para o outbox |
| `infraction.closed` | Um relato de infração chega a `CLOSED` com o resultado da análise. | Outbox |
| `infraction.cancelled` | Um relato de infração chega a `CANCELLED`. | Outbox |
| `refund_request.created` | Existe uma solicitação de devolução do MED: você a cria, ou o BTG entrega uma que uma contraparte criou. | Outbox |
| `refund_request.closed` | Uma solicitação de devolução chega a `CLOSED` com o resultado e o valor devolvido. | Outbox |
| `refund_request.cancelled` | Uma solicitação de devolução chega a `CANCELLED`. | Outbox |

### Cash-in e devoluções

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `cashin.received` | A API aceita um Pix recebido e o guarda como `CREATED`. Nenhum crédito acontece nesta etapa. | Direta, com fallback para o outbox |
| `cashin.completed` | Um Pix recebido é liquidado, e a API o credita na conta no Midaz. | Outbox |
| `cashin.failed` | O BTG informa um erro para um Pix recebido aceito, e a API o guarda como `REJECTED`. Nada é creditado. | Outbox |
| `refund.created` | Existe uma devolução para uma das suas contas. O campo `type` (`CASHOUT` ou `CASHIN`) dá a direção dela. | Direta, com fallback para o outbox |
| `refund.processing` | Uma devolução que você envia (`CASHOUT`) passa para `PROCESSING`. | Direta, com fallback para o outbox |
| `refund.completed` | Uma devolução é liquidada e passa para `COMPLETED`. | Outbox |
| `refund.rejected` | O BTG ou a liquidação intra-PSP rejeita uma devolução em andamento, e a API a guarda como `REJECTED`. | Outbox |
| `refund.failed` | Uma devolução que você envia (`CASHOUT`) não pode ser executada, e a API a guarda como `FAILED`. | Outbox |

### Cash-out, iniciação de pagamento e agendamentos

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `payment_initiation.created` | Uma iniciação de pagamento (`MANUAL`, `KEY` ou `QR_CODE`) passa na validação, e a API a guarda como `PENDING`. | Direta, com fallback para o outbox |
| `cashout.created` | A API guarda um cash-out como `CREATED`. | Direta, com fallback para o outbox |
| `cashout.processing` | O provedor aceita o cash-out, e a API o guarda como `PROCESSING`. | Direta, com fallback para o outbox |
| `cashout.completed` | O cash-out é liquidado, e a API o guarda como `COMPLETED`. | Outbox |
| `cashout.rejected` | O BTG ou a liquidação intra-PSP rejeita um cash-out que chegou ao provedor, e a API o guarda como `REJECTED`. | Outbox |
| `cashout.failed` | O cash-out falha antes de o provedor aceitá-lo, e a API o guarda como `FAILED`. | Outbox |
| `schedule.created` | A API guarda um Pix agendado como `SCHEDULED`. | Direta, com fallback para o outbox |
| `schedule.cancelled` | Um agendamento `SCHEDULED` é cancelado. | Direta, com fallback para o outbox |
| `schedule.attempt_failed` | Uma tentativa falha por saldo insuficiente, e o agendamento espera uma nova tentativa no mesmo dia. | Melhor esforço |
| `schedule.executed` | Um Pix agendado é executado e liquidado. | Outbox |
| `schedule.failed` | Um Pix agendado chega a `FAILED` depois da última tentativa. | Outbox |

### Autorizações do Pix Automático

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `authorization_request.created` | A API guarda uma solicitação de autorização para uma conta pagadora: o BTG a entrega, ou você confirma um QR Code do Pix Automático para o pagador. | Direta, com fallback para o outbox |
| `authorization_request.approved` | O BTG reconhece a aprovação do pagador, e a solicitação passa para `APPROVING`. O mandato não existe nesta etapa. | Direta, com fallback para o outbox |
| `authorization_request.confirmed` | O BTG confirma a aprovação, e a solicitação chega a `CONFIRMED`. | Outbox |
| `authorization_request.rejected` | A solicitação chega a `REJECTED`: o pagador a rejeita, ou o BTG informa uma rejeição. | Outbox |
| `authorization_request.cancelled` | O BTG informa o cancelamento de uma solicitação antes da confirmação dela. | Outbox |
| `authorization_request.expired` | A solicitação chega a `EXPIRED` sem uma decisão. | Outbox |
| `authorization_request.reply_failed` | A API não consegue entregar a decisão do pagador ao BTG, e a solicitação chega a `REPLY_FAILED`. | Direta, com fallback para o outbox |
| `authorization_request.payment_failed` | O Pix imediato de uma solicitação de pay-and-confirm não é liquidado, e a solicitação chega a `PAYMENT_FAILED`. Nenhum mandato é criado. | Outbox |
| `recurring_authorization.authorized` | Um mandato do Pix Automático passa a valer para uma conta pagadora. | Outbox |
| `recurring_authorization.cancelled` | Um mandato é cancelado pela API, e as cobranças agendadas futuras dele são canceladas junto. | Outbox |
| `recurrence.completed` | A última cobrança permitida de uma recorrência é executada, e a recorrência termina. | Outbox |
| `recurrence.expired` | Uma recorrência chega à data final, e ela termina. | Outbox |

### Cobranças do Pix Automático

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `recurring_charge.received` | Uma cobrança do Pix Automático chega do BTG, e a API a guarda como `RECEIVED`. | Direta, com fallback para o outbox |
| `recurring_charge.scheduled` | A API agenda uma tentativa de débito para uma cobrança: a cobrança passa nas verificações de aceite, ou uma tentativa com falha tem novas tentativas restantes. | Direta, com fallback para o outbox |
| `recurring_charge.rejected` | As verificações de aceite recusam uma cobrança recebida. O pagador não é debitado. | Outbox |
| `recurring_charge.executed` | O pagador é debitado por uma cobrança. | Outbox |
| `recurring_charge.failed` | A última tentativa de débito permitida falha. O pagador não é debitado. | Outbox |
| `recurring_charge.cancelled` | Uma cobrança agendada é cancelada: o mandato dela é cancelado, ou o agendamento dela é cancelado. | Direta, com fallback para o outbox |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.