> ## 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 e integração com o ledger

> Integração com o Lerian SPB: famílias de eventos de operação do STR, integração com o ledger e convenções da API.

O Lerian SPB é orientado a eventos. A emissão de eventos não é garantida para cada operação ou mudança de ciclo de vida: alguns emissores são opcionais ou best effort, e `EMISSION_REQUIRED` tem `false` como padrão. Defina `EMISSION_REQUIRED=true` em um deploy cujos sistemas downstream dependem desses eventos. O bootstrap então falha fechado, a menos que a emissão de eventos esteja totalmente conectada.

O Lerian SPB publica todas as famílias de eventos no backbone de streaming. Os sistemas downstream leem o estado de liquidação dos eventos de streaming `settlement.*` e `spb.ldl.*` e não fazem polling.

## Famílias de eventos

***

| Família | Emitido em |
| - | - |
| `str.operation.*` | Ciclo de vida da operação: `accepted`, `received`, `returnRequested`, `cancelRequested` |
| `str.readiness.changed` | O estado de readiness do trilho muda |
| `str.certificate.*` | Ciclo de vida do certificado: `rotated`, `expiring`, `counterpartyChanged`, `activationRequested` |
| `str.approval.*` | Uma aprovação na fila emite `signed` ou `denied`; quando atinge o quórum e muda de `PENDING_APPROVAL` para `SUBMITTED`, emite `quorumReached` uma vez |
| `str.reconciliation.*` | Um caso de conciliação é `opened` ou `resolved` |
| `str.schedule.changed` | As grades da janela de funcionamento mudam |
| `str.message.*` | No nível da mensagem: `received`, `submitted`, `rejected` |
| `str.emoney.transferAdvised` | Um novo aviso de moeda eletrônica de terceiros (`SME0001R2`, `SME0002R2` ou `SME0004R2`) é registrado |
| `spb.ldl.*` | Fatos de aviso e de comando de depósito do SILOC, incluindo `deposit-commanded`, `deposit-confirmed` e `deposit-failed`. Fatos de liquidação LDL e LTR: `settlement-confirmed`, `settlement-failed` e `third-party-settlement-received` |
| `settlement.*` | A posição final de liquidação: `settled` quando a perna R de entrada confirma a transferência, `failed` em uma rejeição ou no cancelamento de um original que nunca liquidou |

Os avisos de entrada do BACEN também publicam eventos dedicados. Consulte [Mensageria de entrada do BACEN](https://docs.lerian.studio/pt/rails/spb/spb-inbound-messaging.md).

## Integração com o ledger

***

O seu consumidor de ledger deve receber as famílias `str.operation.*`, `settlement.*` e `spb.ldl.*` no backbone de streaming. O evento `str.operation.accepted` sinaliza a aceitação do despacho, não a liquidação no BACEN, então use-o para registrar um lançamento pendente.

Registre a posição final a partir dos fatos `settlement.*` no backbone de streaming. A transição de negócio por trás de `settlement.settled` acontece quando a perna R de entrada move a mensagem STR da transferência para `CONFIRMED`. A entrega pelo broker é pelo menos uma vez e pode reentregar o fato. O `ce-id` é determinístico, então deduplique pelo par `(ce-source, ce-id)`.

As liquidações LDL, os depósitos LDL0022, o pagamento LTR0004 e os avisos LDL e LTR0005R2 não solicitados não têm fato `settlement.*`. Registre-os a partir dos fatos `spb.ldl.*`:

* A resposta R1 ao seu comando: `deposit-confirmed` ou `deposit-failed` para um depósito OT, e `settlement-confirmed` ou `settlement-failed` para todos os outros comandos.
* Um crédito LDL0020R2 que corresponde a um crédito OT esperado: `credit-received`.
* Todos os outros avisos: `third-party-settlement-received`.

Um crédito de entrada que não responde a nenhuma operação sua chega como `str.operation.received`, então registre esse crédito a partir desse evento. Uma devolução de uma TED que você enviou chega da mesma forma. O campo `numCtrlSTROr` traz o número de controle da sua TED original.

Uma devolução devolve um crédito TED que você recebeu, como uma transferência própria. `str.operation.returnRequested` sinaliza a aceitação do despacho da devolução, e o `settlement.settled` ou o `settlement.failed` da própria devolução dá a sua posição final. O Lerian SPB não mantém posição contábil. O trilho carrega a mensagem e o seu estado de liquidação, e o seu ledger registra o dinheiro.

## Convenções da API

***

* **A autenticação** é um bearer token.
* **As escritas são idempotentes** pelo header `X-Idempotency`. Um reenvio não despacha em duplicidade.
* **As leituras do log de mensagens não expõem o frame assinado que trafega na rede.** Você lê uma única mensagem pelo seu NUOp para obter dados estruturados. Quando o trilho reteve um frame, leia o XML reconstruído pela rota de frame dedicada, autorizada separadamente. Ele não retém separadamente os bytes literais enviados.
* **Ids desconhecidos retornam um not-found uniforme.** A resposta nunca revela se existe uma operação que a sua instituição não possui.


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