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

> CloudEvents que Lerian BC Correios publica en Kafka para correos, envíos a BACEN y análisis de IA.

Lerian BC Correios publica nueve hechos de negocio JSON como CloudEvents 1.0 en modo de contenido binario sobre Kafka. El servicio necesita un broker Kafka en cada entorno: define `STREAMING_BROKERS` y las demás [variables del broker](https://docs.lerian.studio/es/rails/bc-correios/bc-correios-environment-variables.md#kafka-broker-events). La [visión general del streaming de eventos](https://docs.lerian.studio/es/reference/events/overview.md) describe el envelope común.

## Contrato de transporte

| Campo | Valor |
| - | - |
| `ce-source` | `br-correios` |
| Tema | `lerian.streaming.br-correios` |
| Tema de dead letters | `lerian.streaming.br-correios.dlq` |
| `ce-type` | `studio.lerian.br-correios.<event-key>` |
| `ce-tenantid` | `default` |
| Versión del esquema | `1.0.0` para cada evento |
| Tipo de contenido | `application/json` |
| Entrega | Definida por evento. Consulta [Entrega](#delivery). |
| Manifest en tiempo de ejecución | `GET /v1/streaming/manifest` |

El manifest lista el catálogo de eventos. Se sirve en la raíz del servicio, no en `/api/v1/correios`. La ruta requiere el recurso `streaming-manifest` del Access Manager con la acción `get`, que tiene el grupo editor.

## Entrega

Cada evento tiene uno de estos tres modos de entrega:

* **Outbox**: el servicio escribe el evento en su outbox de PostgreSQL, en la misma transacción del cambio que lo causó, y un relay lo publica en Kafka. Si el broker está caído, el relay reintenta durante 7 días.
* **Directa, con fallback al outbox**: el servicio publica el evento en Kafka. Si el broker no está disponible, el servicio escribe el evento en el outbox.
* **Mejor esfuerzo**: el servicio publica el evento en Kafka, sin outbox y sin dead letter.

Un broker caído no detiene el servicio. Un evento puede llegar más de una vez: deduplica según `(ce-source, ce-id)` y mantén los consumidores idempotentes. No dependas del orden de llegada.

## Catálogo de eventos

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `mail.received` | Lerian BC Correios almacena un correo nuevo de BC Correio. Se dispara una vez por cada mensaje de BC Correio. | Outbox |
| `sync.initial_completed` | Termina el primer ciclo de sondeo. Se dispara una vez. | Directa, con fallback al outbox |
| `mail.read` | Un usuario marca un correo como leído. `idempotentNoOp` es `true` cuando el correo ya estaba leído. | Outbox |
| `mail.archived` | Un usuario archiva un correo. | Outbox |
| `mail.restored` | Un usuario restaura un correo archivado a la carpeta desde la que se archivó. | Outbox |
| `transmission.confirmed` | BC Correio acepta un mensaje que envías, y el envío pasa a `CONFIRMED`. | Outbox |
| `transmission.failed` | Un envío no se confirma. El envío pasa a `FAILED`, o a `AMBIGUOUS` cuando BC Correio puede tener el mensaje. | Outbox |
| `ai.analysis_completed` | Termina el análisis de IA de un correo. | Mejor esfuerzo |
| `ai.analysis_failed` | Falla el análisis de IA de un correo. | Mejor esfuerzo |

El servicio no arranca cuando `STREAMING_EVENT_POLICIES` desactiva un evento con entrega `Outbox`.

## Campos del payload

| Clave del 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` es `BCC-2011` cuando el envío pasó a `FAILED`, y `BCC-2010` cuando pasó a `AMBIGUOUS`. Los eventos de IA no llevan el texto del insight. Lee el insight con `GET /mails/{id}/ai-status`.


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