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

> A sequência de habilitação, os fluxos de envio e recebimento, as devoluções, as chaves e reivindicações do DICT, as cobranças BR Code, o Pix Automático e as disputas MED que compõem a superfície de mensageria do Pix.

O Lerian SPI expõe a superfície de mensageria do Pix como um conjunto de operações tipadas. Cada fluxo persiste o seu trabalho antes de despachar, retorna um estado aceito-mas-não-liquidado e reconcilia contra a resposta assíncrona do BACEN.

## Habilitação e prontidão

***

Um participante é cadastrado pelo seu ISPB e ativado antes de poder operar. A prontidão então segue uma ordem obrigatória, e um envio tentado antes de ela passar é recusado.

1. **Envie** um certificado Pix — apenas o `.cer` público. Uma chave privada enviada é recusada.
2. Confirme que o trilho reporta que está pronto (`ready`).
3. Passe por um **teste de conectividade**.
4. Os envios já estão permitidos.

Os participantes são suspensos e descadastrados ao longo do seu ciclo de vida pela mesma superfície Core.

## Enviar um Pix

***

Você cria uma ordem de pagamento; a plataforma monta a mensagem ISO 20022 de transferência de crédito (`pacs.008`), persiste a operação e a despacha. O BACEN retorna um callback de status assíncrono (`pacs.002`) que o trilho valida e aplica, movendo o pagamento para `settled` ou `rejected`. Um pagamento é lido pelo seu end-to-end ID, junto com o seu histórico e uma linha do tempo por operação.

## Receber um Pix

***

O BACEN publica um callback XML `pacs.008` assinado para um Pix recebido. O trilho valida a assinatura, aplica o pagamento e retorna uma resposta `pacs.002` assinada. Os participantes listam os Pix que receberam.

## Devolução

***

Sobre um pagamento liquidado, você inicia uma devolução (`pacs.004`) como subrecurso da operação pai e depois lê o status da devolução. Uma devolução é o caminho de movimentação de dinheiro do MED — a forma como os fundos voltam a um pagador por uma disputa concluída ou um erro.

## Ciclo de vida das chaves DICT

***

As chaves Pix são gerenciadas diretamente contra o diretório DICT: registrar, listar, buscar, consultar, atualizar e excluir uma chave, e verificar em lote se um conjunto de chaves existe. O trilho também lê as estatísticas de chaves do DICT e as 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 titularidade. Você inicia uma reivindicação contra um participante e depois a move pelo seu ciclo de vida — acknowledge, confirmar ou rejeitar, completar ou cancelar — entre os lados doador e reivindicante. Os prazos das reivindicações são processados automaticamente para que nenhuma fique parada além da sua janela do BACEN.

## BR Code e cobranças

***

Um QR sempre aponta para uma cobrança, então você cria a cobrança primeiro e depois gera o payload que resolve para ela.

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

A geração de QR estático, a decodificação, a validação e o cadastro do perfil do recebedor também fazem parte da superfície.

## Pix Automático (recorrente)

***

O Pix Automático autoriza pagamentos recorrentes e agendados por meio da família recorrente do ISO 20022:

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

## Disputas MED

***

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

* **Abra** um caso MED, **analise-o** e depois **resolva-o**, **feche-o** ou **cancele-o** com evidência anexada.
* Registre **relatos de infração**, **solicitações de devolução**, **marcações de fraude** e pedidos de **recuperação de fundos** do DICT, cada um rastreado ao longo do seu grafo de ciclo de vida.
* Reporte os Pix liquidados internamente por meio do relatório de liquidação do MED 2.0.

## Reporte da Conta PI

***

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