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

# Integração com o Lerian SPB

> As famílias de eventos, o ponto de contato com o ledger Midaz, a entrega por webhooks e as convenções da API para construir sobre o Lerian SPB.

O Lerian SPB é orientado a eventos. Cada operação e cada mudança de ciclo de vida emite um evento de domínio, entregue tanto aos webhooks registrados quanto ao backbone de streaming da plataforma, de modo que os sistemas a jusante reagem ao estado de liquidação sem fazer polling.

## Famílias de eventos

***

| Família                 | Emitida em                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `str.operation.*`       | Ciclo de vida da operação — `accepted`, `received`, `confirmed`, `sent`, `submitted`, `observed`, `progress` |
| `str.readiness.changed` | O estado de disponibilidade do trilho muda                                                                   |
| `str.certificate.*`     | Certificado de assinatura `rotated` ou `expiring`                                                            |
| `str.approval.*`        | Uma emissão na fila é `signed` ou `denied`                                                                   |
| `str.reconciliation.*`  | Um caso de conciliação é `opened` ou `resolved`                                                              |
| `str.schedule.changed`  | As faixas da janela operacional mudam                                                                        |
| `str.message.*`         | No nível da mensagem: `received`, `sent`, `submitted`, `failed`, `rejected`                                  |

## Ponto de contato com o Midaz

***

O plugin de ledger do Midaz assina a família `str.operation.*` e baseia os seus lançamentos contábeis nela — `str.operation.accepted` é o gatilho do lançamento. O Lerian SPB não mantém **nenhuma** posição contábil; a posição vive inteiramente no Midaz. O trilho transporta a mensagem e o seu estado de liquidação, e o Midaz registra o dinheiro.

## Entrada a partir do BACEN

***

O Lerian SPB consome as respostas de liquidação de entrada do STR (as R-legs) e os avisos da família GEN vindos do BACEN pela RSFN. Uma operação enviada permanece aberta até que a sua R-leg chegue e a mova para `SETTLED` ou `REJECTED`, com os campos de liquidação do BACEN projetados literalmente.

## Webhooks

***

Os consumidores de webhooks se autorregistram sobre as constantes canônicas de eventos e negociam os formatos de payload a partir de um catálogo de eventos compartilhado. A entrega é durável: uma entrega que falha pode ser retentada manualmente, e uma rota de dead-letter trata as entregas que esgotam as suas tentativas.

## Convenções da API

***

* A **autenticação** é um bearer token.
* As **escritas são idempotentes** por meio de uma chave de idempotência, de modo que um envio retentado não despacha duas vezes.
* As **leituras nunca vazam payloads de protocolo em bruto.** Uma mensagem pode ser lida pelo seu NUOp, com uma visão XML reconstruída no momento da leitura; os bytes literais enviados não são retidos separadamente.
* Os **ids desconhecidos retornam um not-found uniforme**, que nunca revela se existe uma operação que a sua instituição não possui.