> ## 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. # Visão geral do streaming de eventos > Contrato compartilhado de streaming de eventos para os produtos Lerian: o envelope do CloudEvents, as convenções de tópico e tipo, o versionamento de schema e as garantias de entrega. Os produtos Lerian emitem eventos de domínio em um backbone de streaming compartilhado. Um evento de domínio é um fato de negócio no passado, por exemplo a criação de uma conta ou a emissão de uma credencial. Qualquer serviço ou subscriber downstream os consome sem se acoplar às APIs internas do produtor. Esta página descreve o envelope de transporte comum e as convenções da plataforma. As páginas de cada produto são a referência definitiva para os tipos de evento concretos, os identificadores e a política de entrega de cada produtor. O [Streaming Hub](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) entrega esses mesmos eventos para sua própria infraestrutura (webhooks, SQS, RabbitMQ, EventBridge ou pull) com novas tentativas gerenciadas. ## Transporte Os eventos trafegam como mensagens **CloudEvents 1.0** em **modo binário de conteúdo**. O modo binário coloca os atributos de contexto do CloudEvents em headers de transporte, cada um prefixado com `ce-`, e o corpo do evento no valor da mensagem como JSON. Um consumidor lê o roteamento e a identidade a partir dos headers sem desserializar o payload. A maioria dos produtores publica via **Kafka**: Midaz, Tracer (no Midaz), Lender, Matcher e Consignado. O [Reporter](https://docs.lerian.studio/pt/reference/events/reporter.md) publica o mesmo envelope via **RabbitMQ** quando `STREAMING_ENABLED=true`. Ele roteia cada evento para um exchange configurado, usando a chave do evento como chave de roteamento. Quando `STREAMING_KAFKA_BROKERS` também está definido, o Reporter publica `report.finished` e `report.partial` também no Kafka. Os dois transportes compartilham as convenções de tipo e versionamento do CloudEvents. A página de cada produtor continua sendo a referência definitiva para ids, schemas, destinos e política de entrega exatos. O produtor Kafka do Tracer é o componente dentro do Midaz. ## O envelope Todo registro carrega estes headers do CloudEvents. | Header | Presente | Carrega | | - | - | - | | `ce-specversion` | Sempre | Versão do spec do CloudEvents: `1.0`. | | `ce-id` | Sempre | ID de evento opaco, estável e definido pelo produtor. Deduplique pelo par `(ce-source, ce-id)`; não presuma um formato UUID. | | `ce-source` | Sempre | O serviço produtor. | | `ce-type` | Sempre | Produtores v3 usam `studio.lerian...`. | | `ce-time` | Sempre | Timestamp (RFC 3339). | | `ce-resourcetype` | Sempre | O recurso, por exemplo `account`. | | `ce-eventtype` | Sempre | O evento, por exemplo `created`. | | `ce-schemaversion` | Sempre | Versão do schema do payload. | | `ce-subject` | Quando definido | O ID do agregado a que o evento se refere. | | `ce-tenantid` | Definido pelo produtor | O tenant proprietário. O Midaz sempre o envia: o seu tenant, ou o literal `default` quando o evento não tem tenant. Outros produtores definem seu próprio comportamento. | | `ce-datacontenttype` | Quando definido | Media type do corpo: `application/json`. | ## Tipo de evento O contrato v3 usa a forma qualificada por source `studio.lerian...`. O mesmo valor de `` aparece em `ce-source`. `ce-resourcetype` e `ce-eventtype` carregam a chave de despacho como headers separados. Verifique a página específica do produtor ou o manifesto antes de rotear. ## Nomenclatura de tópicos Produtores Kafka no contrato v3 de application stream (incluindo Midaz, `components/tracer` do Midaz, Matcher, Lender e Consignado) enviam seus fatos de negócio JSON públicos para: ``` lerian.streaming. ``` Comandos usam `lerian.streaming..commands`. Os dead letters do produtor usam `lerian.streaming..dlq`. Não existe um tópico `.commands.dlq` separado. O tipo de recurso, o tipo de evento e a versão do schema permanecem nos headers do CloudEvents, então mudanças major de schema não renomeiam o tópico. Exemplos: * Fatos JSON públicos do ledger, CRM e Fees do Midaz: `lerian.streaming.ledger` * Fatos do `components/tracer` do Midaz: `lerian.streaming.tracer` * Fatos do Matcher: `lerian.streaming.matcher` * Fatos e comandos do Lender: `lerian.streaming.lender` e `lerian.streaming.lender.commands` * Fatos do gateway do Consignado: `lerian.streaming.consignado-gw` Sinais internos de metering do produto ficam fora deste contrato público de integração e podem usar destinos e codificações separados. O Reporter mantém um destino RabbitMQ explícito: seu exchange configurado, com a chave do evento como chave de roteamento. Seus valores de `ce-type` continuam qualificados por source. ## Fonte `ce-source` identifica o serviço produtor e faz parte do contrato de wire. Os exemplos atuais de produtos v3 usam `ledger`, `tracer` (`components/tracer` do Midaz), `matcher`, `lender`, `consignado-gw` ou `reporter`. Todos, exceto o Matcher, fixam ou validam esse valor exato do roster. O Matcher deriva sua identidade de wire a partir do valor configurado. Produtores Kafka v3 embutem a fonte no tópico de aplicação, e todos os produtores v3 a embutem em `ce-type`. Alterá-la, portanto, muda o roteamento e a identidade do consumidor. Trate isso como uma mudança que quebra compatibilidade. ## Assunto e tenant `ce-subject` carrega o ID do agregado a que o evento se refere (a conta, a transação ou a credencial a que o fato diz respeito). `ce-tenantid` carrega o tenant proprietário. Quando um evento não tem tenant, o comportamento é específico de cada produtor: o Midaz envia o literal `default`, enquanto outros produtores documentam seu próprio comportamento. Siga o contrato específico do produtor. ## Versionamento de schema Cada evento declara sua própria versão de schema do payload em `ce-schemaversion`, independente dos demais eventos da mesma fonte. O padrão é `1.0.0`. Um incremento minor é aditivo e retrocompatível. Um incremento major introduz uma mudança que quebra compatibilidade. No application stream Kafka v3, a versão do schema nunca muda o nome do tópico. Um incremento de schema também deixa inalterados os exchanges e as chaves de roteamento explícitos do RabbitMQ. Uma mudança aditiva não afeta um consumidor que lê os payloads como um [leitor tolerante](https://docs.lerian.studio/pt/reference/tolerant-reader.md) e ignora campos desconhecidos. ## Garantias de entrega A entrega é **pelo menos uma vez**. Um consumidor confirma sua posição apenas depois de terminar de processar um registro. Uma falha durante o processamento reproduz o registro em vez de descartá-lo, então o mesmo evento pode chegar mais de uma vez. Deduplique pelo par `(ce-source, ce-id)` (o CloudEvents define a identidade do evento por essa combinação, e o `ce-id` sozinho pode colidir entre fontes) e mantenha os handlers idempotentes. Do lado do produtor, a política de entrega pertence a cada definição de evento, não à plataforma. Uma política **apoiada em outbox** garante relay e nova tentativa duráveis. Por si só, ela não prova que a escrita de estado de negócio e a inserção no outbox compartilham uma única transação de banco de dados. O Lender e o Consignado fazem essa escrita atômica para seus eventos de catálogo. O Reporter emite depois do commit de estado, e suas políticas críticas então usam um outbox Mongo durável em uma operação separada. Uma falha ou uma inserção de outbox malsucedida nessa janela pós-commit perde o evento do Reporter. Nenhuma conciliação o recupera, e apenas um log de erro e uma métrica registram a perda. O Matcher e o Reporter também publicam sinais operacionais diretamente, com fallback de outbox. Verifique a própria página de eventos do produto tanto para sua política quanto para seu limite transacional. Onde o produto expõe um manifesto de streaming, leia o manifesto na inicialização. ## Catálogos por produto | Produtor | Página | Transporte | Manifesto de streaming | | - | - | - | - | | Midaz (ledger, CRM, Fees) | [Eventos do Midaz](https://docs.lerian.studio/pt/reference/events/midaz.md) | Kafka | `GET /v1/streaming/manifest` | | `components/tracer` do Midaz | [Eventos do Tracer](https://docs.lerian.studio/pt/reference/events/tracer.md) | Kafka | `GET /v1/streaming/manifest` | | Lender | [Eventos do Lender](https://docs.lerian.studio/pt/reference/events/lender.md) | Kafka | `GET /api/v1/streaming/manifest` | | Matcher | [Eventos do Matcher](https://docs.lerian.studio/pt/reference/events/matcher.md) | Kafka | `GET /system/matcher/streaming/manifest` | | Consignado | [Eventos do Consignado](https://docs.lerian.studio/pt/reference/events/consignado.md) | Kafka | `GET /v1/streaming/manifest` | | Pix Direct via JD | [Eventos do Pix Direct via JD](https://docs.lerian.studio/pt/reference/events/pix-direct-jd.md) | Kafka | — | | Pix Indirect via BTG | [Eventos do Pix Indirect via BTG](https://docs.lerian.studio/pt/reference/events/pix-btg.md) | Kafka | `GET /v1/streaming/manifest` | | Pix Lerian | [Eventos do Pix Lerian](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-events.md) | Kafka | `GET {prefix}/v1/streaming/manifest` | | TED Lerian | [Eventos do TED Lerian](https://docs.lerian.studio/pt/interfaces/ted-lerian/ted-lerian-events.md) | Kafka | `GET /streaming/manifest` | | TED JD | [Eventos do TED JD](https://docs.lerian.studio/pt/reference/events/ted-jd.md) | Kafka | `GET /streaming/manifest` | | Lerian SPI | [Eventos do Lerian SPI](https://docs.lerian.studio/pt/reference/events/spi.md) | Kafka | `GET /v1/streaming/manifest` em cada binário | | Lerian SPB | [Eventos do Lerian SPB](https://docs.lerian.studio/pt/rails/spb/spb-events-and-ledger-integration.md) | Kafka | `GET /v1/streaming/manifest` | | Lerian SLC | [Eventos do Lerian SLC](https://docs.lerian.studio/pt/rails/slc/slc-integration.md) | Kafka | `GET /v1/streaming/manifest` | | Lerian SILOC | [Eventos do Lerian SILOC](https://docs.lerian.studio/pt/rails/siloc/siloc-integration.md) | Kafka | `GET /v1/streaming/manifest` | | Lerian STA | [Eventos do Lerian STA](https://docs.lerian.studio/pt/rails/sta/sta-integration.md) | RabbitMQ; Kafka quando `STREAMING_ENABLED` é `true` | `GET /streaming/manifest` | | Lerian SISBAJUD Mensageria | [Eventos do Lerian SISBAJUD](https://docs.lerian.studio/pt/rails/sisbajud/sisbajud-integration.md#events) | Kafka | — | | Lerian CCS | [Eventos do Lerian CCS](https://docs.lerian.studio/pt/rails/ccs/ccs-integration.md) | Kafka | `GET /v1/streaming/manifest` | | Lerian SCR | [Eventos do Lerian SCR](https://docs.lerian.studio/pt/rails/scr/scr-integration.md) | Kafka | `GET /v1/streaming/manifest` | | Lerian SRC | [Eventos do Lerian SRC](https://docs.lerian.studio/pt/rails/src/src-integration.md#polling-and-events) | Kafka | `GET /v1/streaming/manifest` | | Reporter | [Eventos do Reporter](https://docs.lerian.studio/pt/reference/events/reporter.md) | RabbitMQ; Kafka para `report.finished` e `report.partial` quando `STREAMING_KAFKA_BROKERS` está definido | [`GET /v1/streaming/events`](https://docs.lerian.studio/pt/reference/products/reporter/get-streaming-events) | Outros trilhos do Brasil também publicam eventos neste contrato. Use a página de eventos de um trilho ou o manifesto em runtime apenas quando o trilho expõe explicitamente seu catálogo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.