> ## 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 Pix Lerian

> Integração com o Lerian SPI: eventos de streaming, integração com o ledger e convenções de API para Pix.

O Lerian SPI é orientado a eventos. Operações e mudanças de liquidação circulam como eventos de domínio no backbone de streaming da plataforma. Sistemas downstream reagem a essas mudanças sem polling. O trilho nativo não tem consumidores de webhook voltados ao cliente. A coordenação dele é interna à plataforma.

## Fluxo de eventos

***

Cada contexto do trilho publica e consome os eventos que ele possui:

* O contexto **BR Code** publica eventos de cobrança e os eventos da família de recorrência (Pix Automático). Ele consome `spi.payment.settled` para fechar uma cobrança depois que o Pix dela liquida e `spi.mandate.resolved` para tirar um mandato de Pix Automático de `CRIADA`.
* O contexto **Core** consome eventos de confirmação de participante e eventos de conclusão e de término de liquidação. Ele mantém o estado de participante e de operação em sincronia com o BACEN.

## Integração com o ledger

***

O Lerian SPI não mantém posição contábil própria. O trilho emite eventos de liquidação no backbone de streaming, e o seu consumidor do ledger registra a posição correspondente. O trilho repassa cada valor liquidado sem alteração. Cada evento de liquidação carrega um `ce-id` estável que identifica a liquidação. A entrega é pelo menos uma vez, então o seu consumidor do ledger deve deduplicar reentregas por `ce-id`.

## Convenções de API

***

* **Auth** segue o esquema padrão de bearer token da plataforma.
* **Os pagamentos carregam um end-to-end ID.** Você lê um pagamento e o histórico dele pelo E2EID.
* **As devoluções são sub-recursos.** Você cria e lê uma devolução sob o pagamento de entrada que ela estorna. Você deve solicitar uma devolução em até 90 dias da liquidação desse pagamento. Uma devolução não pode levar a soma das devoluções do Pix acima do valor do próprio Pix. A contraparte emite a devolução de um Pix que o seu cliente enviou. Essa devolução chega como entrada.
* **A devolução se conclui com a resposta do BACEN.** Um `pacs.004` que o trilho despachou fica em andamento até o BACEN responder. Uma requisição duplicada de uma devolução já em andamento recebe uma resposta de andamento. Um identificador de devolução em colisão recebe uma resposta de conflito, nunca um recibo.
* **As mensagens de entrada do trilho passam por validação de assinatura.** O trilho não aplica uma mensagem que falha na validação.