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

# Operar o Pix Lerian

> Opere o Pix Lerian observando estados assíncronos, preservando chaves de replay e separando operações do plugin de operações de conectividade.

Opere o Pix Lerian como uma aplicação com estado, lançamentos no Midaz e resultados assíncronos do provedor.

## Observar a operação, não apenas a resposta HTTP

Uma resposta de criação pode confirmar o trabalho aceito antes de o adaptador de conectividade informar um resultado terminal. Armazene o identificador do recurso, os dados de correlação da requisição e o valor de idempotência. Depois, leia o recurso até seu estado ser terminal.

* Use as [leituras de transferência do SPI](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-transfer.md) e as [leituras de devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-refund.md) para fluxos de pagamento.
* Use as leituras de recursos do DICT e do COB retornadas pela referência gerada para os respectivos fluxos.
* Compare o estado final do plugin com o débito, crédito, retenção, liberação ou estorno esperado no Midaz.

Não deduza a liquidação apenas de um envio bem-sucedido.

## Preservar um comportamento seguro de retry

Mantenha `X-Idempotency` junto do payload e da resposta da requisição original. Reutilize-o somente para repetir essa requisição. O plugin rejeita uma reutilização divergente, exceto nas duas rotas de criação de cobrança: elas retornam a cobrança imediata ou com vencimento existente. Um replay responde com o status original e o header `X-Idempotency-Replayed: true`, e um `412` (`PIX-0031`) com `Retry-After: 1` significa que a primeira requisição ainda roda.

Uma falha de dependência não é um sinal para inventar um estado terminal. Restaure a dependência, preserve a mesma identidade de retry quando o contrato permitir e leia o recurso antes de enviar uma nova requisição de negócio.

## Tratar conciliação e MED 2.0

O DICT pode bloquear temporariamente mutações selecionadas de chaves e reivindicações enquanto o VSync concilia um escopo. Um `503` desse bloqueio significa que a conciliação está ativa. Inspecione o estado e repita somente depois de o escopo ficar disponível. O cancelamento continua separado das mutações que podem introduzir divergências.

As retenções e devoluções do MED 2.0 têm suas próprias transições de estado. Use o [guia de SPI](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md) e o [guia de DICT](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-dict.md) para determinar se uma retenção deve ser liquidada, compensada, liberada ou revisada. Não transforme overrides operacionais em fluxos normais do cliente.

## Respeitar o limite de conectividade

O adaptador de conectividade informa o resultado do provedor e chama callbacks internos. Um cliente não deve chamar diretamente rotas de callback.

O back office da sua instituição pode concluir uma operação parada com as rotas de recuperação que a referência da API publica: desbloquear uma transferência, uma devolução ou um débito agendado do Pix Automático que fica em `PROCESSING`, e creditar um Pix recebido ou uma devolução cujo crédito no ledger o Pix Lerian estacionou (`inbound_transfer.credit_parked`, `refund.credit_parked`). Use-as somente no evento ou no estado que os guias nomeiam. Veja [Usar o SPI com o Pix Lerian](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md).

## Checklist de operação

1. Verifique o escopo da conta autenticada antes de uma gravação.
2. Salve a requisição, o valor de `X-Idempotency` e o identificador do recurso retornado.
3. Aguarde e observe o resultado assíncrono por meio de uma leitura pública.
4. Verifique o lançamento esperado no Midaz ou o lançamento de compensação.
5. Para um resultado não terminal, leia o estado primeiro. Somente depois siga a ação documentada de retry ou recuperação.

Consulte [Integração](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-integration.md) para os limites do cliente e as convenções de requisição.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.