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

> CloudEvents que o Lerian BC Correios publica no Kafka para correspondências, envios ao BACEN e análise de IA.

O Lerian BC Correios publica nove fatos de negócio JSON como CloudEvents 1.0 em modo binário de conteúdo via Kafka. O serviço precisa de um broker Kafka em todo ambiente: defina `STREAMING_BROKERS` e as outras [variáveis do broker](https://docs.lerian.studio/pt/rails/bc-correios/bc-correios-environment-variables.md#kafka-broker-events). 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` | `br-correios` |
| Tópico | `lerian.streaming.br-correios` |
| Tópico de dead letters | `lerian.streaming.br-correios.dlq` |
| `ce-type` | `studio.lerian.br-correios.<event-key>` |
| `ce-tenantid` | `default` |
| Versão do schema | `1.0.0` para todo evento |
| Tipo de conteúdo | `application/json` |
| Entrega | Definida por evento. Veja [Entrega](#delivery). |
| Manifesto em runtime | `GET /v1/streaming/manifest` |

O manifesto lista o catálogo de eventos. Ele é servido na raiz do serviço, não em `/api/v1/correios`. A rota exige o recurso `streaming-manifest` do Access Manager com a ação `get`, que o grupo editor possui.

## Entrega

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

* **Outbox**: o serviço escreve o evento no seu outbox do PostgreSQL, na mesma transação da mudança que o causou, e um relay o publica no Kafka. Se o broker estiver fora do ar, o relay tenta de novo por 7 dias.
* **Direta, com fallback para o outbox**: o serviço publica o evento no Kafka. Se o broker estiver indisponível, o serviço escreve o evento no outbox.
* **Melhor esforço**: o serviço publica o evento no Kafka, sem outbox e sem dead letter.

Um broker fora do ar não interrompe o serviço. 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

| Chave do evento | Dispara quando | Entrega |
| - | - | - |
| `mail.received` | O Lerian BC Correios armazena uma nova correspondência do BC Correio. Dispara uma vez para cada mensagem do BC Correio. | Outbox |
| `sync.initial_completed` | O primeiro ciclo de polling termina. Dispara uma vez. | Direta, com fallback para o outbox |
| `mail.read` | Um usuário marca uma correspondência como lida. `idempotentNoOp` é `true` quando a correspondência já estava lida. | Outbox |
| `mail.archived` | Um usuário arquiva uma correspondência. | Outbox |
| `mail.restored` | Um usuário restaura uma correspondência arquivada para a pasta de onde ela foi arquivada. | Outbox |
| `transmission.confirmed` | O BC Correio aceita uma mensagem que você envia, e o envio passa para `CONFIRMED`. | Outbox |
| `transmission.failed` | Um envio não é confirmado. O envio passa para `FAILED`, ou para `AMBIGUOUS` quando o BC Correio pode ter a mensagem. | Outbox |
| `ai.analysis_completed` | A análise de IA de uma correspondência termina. | Melhor esforço |
| `ai.analysis_failed` | A análise de IA de uma correspondência falha. | Melhor esforço |

O serviço não inicia quando `STREAMING_EVENT_POLICIES` desliga um evento com entrega `Outbox`.

## Campos do payload

| Chave do evento | Campos |
| - | - |
| `mail.received` | `mailId`, `bcbMessageId`, `folder`, `bcbPasta`, `mailType`, `subject`, `sender`, `receivedAt`, `hasAttachments`, `ementa`, `contentType` |
| `sync.initial_completed` | `firstSyncedAt`, `syncStatus` |
| `mail.read` | `mailId`, `userId`, `readAt`, `folder`, `idempotentNoOp` |
| `mail.archived` | `mailId`, `userId`, `archivedAt`, `priorFolder`, `currentFolder` |
| `mail.restored` | `mailId`, `userId`, `restoredAt`, `priorFolder`, `restoredToFolder` |
| `transmission.confirmed` | `mailId`, `userId`, `bcbConfirmationId`, `idempotencyKey`, `sentAt`, `destination`, `subject`, `inReplyToMailId` |
| `transmission.failed` | `mailId`, `idempotencyKey`, `failedAt`, `reason`, `errorClassification`, `originalError` |
| `ai.analysis_completed` | `mailId`, `aiProvider`, `aiModel`, `completedAt`, `insightLengthChars`, `retryCount`, `source` |
| `ai.analysis_failed` | `mailId`, `aiProvider`, `aiModel`, `failedAt`, `aiError`, `failureClass`, `retryCount`, `source` |

`errorClassification` é `BCC-2011` quando o envio passou para `FAILED`, e `BCC-2010` quando passou para `AMBIGUOUS`. Os eventos de IA não carregam o texto do insight. Leia o insight com `GET /mails/{id}/ai-status`.


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