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

# Como o Lerian SPI funciona

> Como o Lerian SPI funciona: onboarding no Pix, fluxos de envio e recebimento (pacs.008 e pacs.002), devoluções, chaves e reivindicações do DICT, cobranças BR Code, Pix Automático e MED.

O Lerian SPI expõe a superfície de mensagens do Pix como um conjunto de operações tipadas. A maioria dos fluxos persiste seu trabalho antes do despacho. O despachante de devolução apenas tenta registrar um `pacs.004` de saída antes de despachá-lo. Uma falha no registro não bloqueia necessariamente o despacho. As operações retornam um estado de aceito-mas-não-liquidado e se reconciliam com a resposta assíncrona do BACEN.

## Onboarding e prontidão

***

Você registra um participante pelo seu ISPB. Um participante indireto entra como `PENDING`. O trilho envia a solicitação de registro, e apenas a confirmação do BACEN pode torná-lo ativo. A ação de ativação apenas reativa um participante já suspenso. O trilho executa a prontidão em uma ordem obrigatória. Um teste de conectividade aprovado é o pré-requisito para um envio.

1. **Faça upload** de um certificado Pix, apenas o `.cer` público. O trilho rejeita uma chave privada enviada.
2. Confirme que o trilho reporta **pronto**.
3. Passe em um **teste de conectividade**.
4. Agora você pode enviar pagamentos.

A mesma superfície Core também suspende e encerra um participante ao longo do seu ciclo de vida.

## Enviar um Pix

***

Você cria uma ordem de pagamento. A plataforma monta a mensagem de transferência de crédito ISO 20022 (`pacs.008`), persiste a operação e a despacha. O BACEN retorna um callback de status assíncrono (`pacs.002`). O trilho valida e aplica o callback, então move o pagamento para `completed` ou `rejected`. Você consulta um pagamento pelo seu ID fim a fim, com seu histórico e uma linha do tempo por operação.

## Receber um Pix

***

O consumidor ICOM recebe mensagens assinadas do BACEN e as repassa para a ingestão interna autenticada do trilho. Para um `pacs.008` de entrada, o trilho valida a mensagem e registra o Pix como pendente. O cliente então fornece a decisão de financiamento para esse Pix já recebido. Um pagamento de saída não pode receber financiamento como dinheiro de entrada. Os participantes listam os Pix que recebem.

## Devolução

***

Você inicia uma devolução (`pacs.004`) apenas para um Pix liquidado que o trilho recebeu do BACEN, e depois consulta o status da devolução. A devolução debita o recebedor original e credita o pagador original. Você não pode iniciar uma devolução para um Pix que seu cliente enviou. A contraparte emite uma devolução desse Pix, e ela chega ao trilho como uma mensagem de entrada. Uma devolução é o caminho de movimentação de dinheiro do MED, a forma como os fundos retornam a um pagador em uma disputa concluída ou erro.

Existem duas superfícies de devolução, e o trilho registra qual delas criou uma devolução em vez de inferir isso depois. Uma devolução **total** reverte o Pix inteiro e move o pagamento pai para fora de `completed`. Uma devolução **parcial** usa o `devolucaoId` que você escolhe como chave e nunca move o pagamento pai. Várias devoluções parciais podem coexistir para um mesmo Pix.

Três validações se aplicam a toda devolução, nas duas superfícies:

* **O pai deve ser um Pix de entrada que liquidou.** Apenas um pagamento recebido que chegou a `completed` (ou que já carrega uma devolução) pode ser devolvido.
* **A janela de devolução do BACEN.** Uma devolução deve ser solicitada em até **90 dias da liquidação do Pix original**. O trilho mede a janela a partir do instante de liquidação, nunca da criação ou da última atualização. Um Pix sem instante de liquidação registrado não fica bloqueado: o trilho registra a lacuna e encaminha a solicitação.
* **O teto de soma.** Os valores de todas as devoluções de um Pix não podem exceder o valor do próprio Pix. O trilho lê apenas o valor daquele pagamento e suas próprias devoluções. Não computa nenhuma posição entre pagamentos.

Uma devolução nasce como `EM_PROCESSAMENTO` e chega a `DEVOLVIDO` ou `NAO_REALIZADO` apenas com a resposta do BACEN. Uma aceitação de transporte não é uma conclusão. Uma devolução que falha libera o teto que ocupava. Uma devolução total que falha retorna o pagamento pai para `completed` sem reativar sua janela de 90 dias.

Você solicita uma devolução como `ORIGINAL` (o padrão quando você não envia nenhuma natureza) ou `RETIRADA`, a etapa de Pix Saque e troco. As duas naturezas do MED (falha operacional e suspeita fundada de fraude) existem apenas do lado da resposta. Elas decorrem do motivo que o trilho coloca no `pacs.004`, e você nunca as solicita.

## Ciclo de vida da chave DICT

***

Você gerencia chaves Pix diretamente no diretório DICT: registrar, listar, pesquisar, consultar, atualizar e excluir uma chave. Você também verifica em lote se um conjunto de chaves existe. O trilho lê estatísticas de chave do DICT e estatísticas antifraude do BACEN, tanto por chave quanto por pessoa.

## Reivindicações do DICT

***

Uma reivindicação move uma chave Pix entre participantes por portabilidade ou posse. Você inicia uma reivindicação contra um participante e depois a avança pelo seu ciclo de vida. O ciclo de vida abrange reconhecer, confirmar ou rejeitar, e concluir ou cancelar, nos lados do doador e do reivindicante. Quando tanto `SCHEDULER_ENABLED=true` quanto `SCHEDULER_CLAIM_DEADLINE_ENABLED=true` estão definidos, o trilho registra o processamento periódico de prazo de reivindicação. Ele tenta avançar reivindicações dentro das janelas do BACEN, mas uma reivindicação ainda pode exigir atenção.

## BR Code e cobranças

***

Um QR dinâmico resolve para uma cobrança persistida, então você cria a cobrança primeiro e depois gera o payload que resolve a ela. Um QR estático é gerado a partir de dados de pagamento estáticos. Ele não exige nem aponta para uma cobrança.

* Crie uma cobrança: **Cob** (imediata), **CobV** (com vencimento, com juros e multa), ou um **lote** de cobranças com vencimento.
* Gere o payload do **QR EMV dinâmico**, que vincula à cobrança pelo seu txid ou localizador e resolve como um JWS assinado.

Você também gera um QR estático, decodifica um payload, valida-o e registra um perfil de recebedor.

## Pix Automático (recorrente)

***

O Pix Automático autoriza pagamentos recorrentes e agendados por meio da família ISO 20022 de recorrência:

* **Crie** uma autorização recorrente (recorrência) ou uma solicitação para uma.
* **Solicite a confirmação** do mandato (`pain.009`), **cancele-o** (`pain.011`), ou **aceite / rejeite-o** (`pain.012`).
* **Agende** uma instrução (`pain.013`) e **aceite / rejeite-a** (`pain.014`).
* **Solicite o cancelamento** de uma instrução agendada (`camt.055`) e **resolva** um cancelamento recebido (`camt.029`).
* **Solicite uma nova tentativa de liquidação** (retentativa) quando uma cobrança agendada falha.

## Disputas MED

***

A superfície do MED (Mecanismo Especial de Devolução) trata casos de fraude e erro:

* **Abra** um caso MED, **analise-o**, depois **resolva**, **feche** ou **cancele-o** com evidências anexadas.
* Registre **relatórios de infração** do DICT, **solicitações de reembolso**, **marcadores de fraude** e solicitações de **recuperação de fundos**, cada um rastreado por seu grafo de ciclo de vida.
* Reporte Pix liquidados internamente por meio do relatório de liquidação do MED 2.0.

## Relatórios da Conta PI

***

Você solicita um relatório de conta (`camt.060`), depois lê o saldo (`camt.053`), o extrato (`camt.052`) ou o detalhe de lançamento (`camt.054`) que o BACEN retorna. Relatórios síncronos e apenas de contagem de volumetria, pagamentos rejeitados, saldo e extrato completam a superfície de relatórios, cada um limitado ao seu período de referência.