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

# Usar o SPI com o Pix Lerian

> Teste o comportamento de cash-out, callback de cash-in, devolução e retenção de saldo do MED 2.0 do Pix Lerian v1.0.0 com o Midaz e o provedor simulado fornecido.

O SPI gerencia transferências Pix, devoluções, resultados assíncronos e o Block Balancer do MED 2.0. Ele chama o Midaz para a ação contábil correspondente à operação.

<Note>
  As rotas de callback de cash-in e cash-out são exclusivas do adaptador. Nesta release, o provedor simulado fornecido é a forma compatível de exercê-las. Uma aplicação cliente não deve enviar um callback nem declarar um resultado de liquidação do provedor.
</Note>

## Enviar um cash-out em duas etapas

Um cash-out é intencionalmente dividido entre iniciação e processamento.

1. Chame [Iniciar transferência](/pt/reference/interfaces/pix-lerian/spi/initiate-transfer) com um novo valor de `X-Idempotency`. O plugin valida a requisição e cria uma iniciação de transferência.
2. Chame [Processar transferência](/pt/reference/interfaces/pix-lerian/spi/process-transfer) para essa iniciação. O plugin executa o débito necessário no Midaz e envia o trabalho ao provedor simulado.
3. Leia a transferência com [Obter transferência](/pt/reference/interfaces/pix-lerian/spi/get-transfer). A aceitação do processamento não é um resultado final de pagamento.
4. Deixe o provedor simulado entregar o callback terminal. Leia novamente até a transferência ser concluída, rejeitada ou chegar a outro estado terminal conforme o contrato da resposta.

Mantenha o mesmo valor de idempotência somente para repetir a mesma chamada. Um novo pagamento de negócio exige um novo valor.

## Receber um cash-in pelo limite do adaptador

O adaptador recebe o evento do lado externo, chama os callbacks internos de aprovação e liquidação do plugin, e o plugin valida e credita o destino por meio do Midaz. Sua aplicação observa esse fluxo pelas leituras públicas da transferência; ela não chama os callbacks de aprovação ou liquidação.

Um cash-in que não pode ser aprovado ou liquidado não é uma decisão de retry do lado do cliente. Inspecione o estado público da operação e as evidências do teste com mock antes de tomar outra ação.

## Criar e observar uma devolução

Use [Criar devolução](/pt/reference/interfaces/pix-lerian/spi/create-refund) para uma transferência elegível e leia-a por meio de [Obter devolução](/pt/reference/interfaces/pix-lerian/spi/get-refund). Uma devolução segue seu próprio ciclo de vida assíncrono. Não a marque como concluída até que o plugin registre o resultado terminal do provedor e o efeito correspondente no Midaz.

## Usar o Block Balancer do MED 2.0

O Block Balancer retém fundos de uma transação contestada antes de uma decisão de devolução. Esse é um fluxo operacional controlado, não um atalho para transferências comuns.

1. Crie uma retenção para a transação contestada. O plugin coloca uma retenção pendente do Midaz do saldo disponível na conta de bloqueio configurada. Um replay do mesmo `request_ref` retorna a retenção existente.
2. Se o caso terminar antes da liquidação, libere uma retenção `PENDING`. Uma retenção que já está em liquidação não pode ser liberada.
3. Inicie a liquidação da **Fase 1** para uma retenção ou um grupo elegível. A retenção se torna `SETTLING`; o ramo retorna a retenção pendente e envia uma devolução ou confirma a retenção, trata qualquer excedente e envia o pagamento necessário.
4. Conclua a **Fase 2** somente a partir do resultado observado da operação vinculada. Um sucesso torna a retenção `SETTLED`; uma falha a compensa para `PENDING`.
5. Use o fechamento manual, a devolução de excedente e as funções de auditoria somente pelos controles operacionais autorizados. Elas não são endpoints normais da aplicação.

O Block Balancer impõe um teto sobre suas próprias liquidações e as devoluções regulares de saída para a mesma transação original. Não tente contornar essa proteção calculando no cliente.

Para o fluxo de infração e recuperação de fundos no DICT, consulte [DICT](/pt/interfaces/pix-lerian/pix-lerian-dict).