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

> Os callbacks recebidos do BACEN, o backbone orientado a eventos, o ponto de contato com o ledger Midaz e as convenções de API para construir sobre o Lerian SPI.

O Lerian SPI é orientado a eventos. As operações e as mudanças de liquidação fluem como eventos de domínio sobre o backbone de streaming da plataforma, de modo que os sistemas dependentes na plataforma reagem às mudanças de estado sem polling. O trilho nativo **não tem consumidores de webhook voltados ao cliente** — a sua coordenação é interna à plataforma.

## Entrada do BACEN

***

O BACEN publica callbacks XML ISO 20022 assinados sobre a RSFN — uma mensagem de transferência de crédito (`pacs.008`) para um Pix recebido, uma resposta de status (`pacs.002`) para um pagamento que você enviou e uma mensagem de devolução (`pacs.004`) para uma devolução. O trilho valida a assinatura de cada callback antes de aplicá-lo e retorna uma resposta assinada onde o protocolo exige. Um pagamento que você envia permanece aberto até que o seu `pacs.002` chegue e o mova para `settled` ou `rejected`, com os campos do BACEN projetados literalmente.

## Fluxo de eventos

***

Cada contexto do trilho publica e consome os eventos que lhe pertencem:

* O contexto **BR Code** publica eventos de cobrança e os eventos da família recorrente (Pix Automático), e consome eventos de liquidação para encerrar uma cobrança assim que o seu Pix liquida.
* O contexto **Core** consome eventos de confirmação de participante e eventos de conclusão e término de liquidação, mantendo o estado de participantes e operações em sincronia com o BACEN.

## Ponto de contato com o Midaz

***

A liquidação é registrada no ledger **Midaz**. O Lerian SPI não mantém nenhuma posição contábil própria — ele reconcilia o seu estado consumindo eventos de liquidação do Midaz, de modo que a visão do trilho sobre um pagamento e os lançamentos do ledger permanecem alinhados. O trilho transporta a mensagem e o seu estado de liquidação; o Midaz registra o dinheiro.

## Convenções de API

***

* **A autenticação** segue o esquema padrão de token bearer da plataforma.
* **Os pagamentos são endereçados pelo end-to-end ID.** Um pagamento, o seu histórico e a sua linha do tempo de operação são lidos pelo E2EID.
* **As devoluções são subrecursos.** Uma devolução é criada e lida sob o pagamento pai que ela reverte, de modo que uma devolução está sempre atada a uma operação liquidada.
* **Os callbacks recebidos são validados por assinatura.** Um callback que falha na validação de assinatura não é aplicado.