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

# Integrar com o Pix Lerian

> Configure uma integração Pix Lerian, aplique as convenções de requisição e siga os fluxos da API pública sem chamar callbacks exclusivos do adaptador.

Sua aplicação chama as APIs públicas DICT, SPI, COB e Pix Automático. O plugin chama o Midaz e um adaptador de conectividade: o adaptador de conectividade Lerian para o Lerian SPI ou o provedor simulado para testes de integração. O adaptador retorna callbacks assíncronos ao plugin.

> [!NOTE]
>
> As rotas de callback são exclusivas do adaptador. Não as chame de uma aplicação cliente.

## Criar seu caminho de integração

1. Faça o deploy das dependências do plugin, incluindo o Midaz e o adaptador de conectividade do seu ambiente.
2. Obtenha um token de acesso quando a autenticação estiver habilitada e identifique a conta proprietária de cada requisição.
3. Execute um fluxo público: [uma chave](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-dict.md), [uma transferência](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md) ou [uma cobrança](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-cob.md).
4. Mantenha o identificador da operação retornado pela requisição de criação. Leia essa operação até ela chegar a um estado terminal depois do callback do adaptador.
5. Registre juntos o lançamento no Midaz e o resultado da operação.

## Convenções de requisição

Use a referência de cada operação como autoridade final. Estas convenções se repetem no plugin:

| Questão | Uso |
| - | - |
| Autenticação | Envie um token bearer em `Authorization` quando a autenticação do Access Manager estiver habilitada. |
| Escopo da conta | Envie `X-Account-Id` nas operações públicas com escopo de conta. O plugin usa esse valor para impor a titularidade da conta. |
| Replay de mutação | Envie um novo valor de `X-Idempotency` para cada gravação pretendida e reutilize esse valor exato somente para repetir a mesma requisição. A maioria das operações públicas POST exige esse valor. Um replay responde com o status original e o header `X-Idempotency-Replayed: true`. Um reenvio que responde `412` (`PIX-0031`) com `Retry-After: 1` chegou ao plugin enquanto a primeira requisição ainda roda: espere e reenvie. |
| Justificativa de negócio | Envie `X-Reason` quando a operação de DICT exigir um motivo, como na mutação de uma entrada. |
| Tipo de conteúdo | Use `application/json` para corpos JSON. Um merge patch JSON exige `application/merge-patch+json`. |

Um cabeçalho de idempotência ausente ou inválido é um erro do cliente. Reutilizar uma chave com um payload diferente é uma falha de pré-condição, exceto quando você cria uma cobrança imediata ou com vencimento: essas duas rotas retornam a cobrança existente com o `201` original.

## Ler o estado depois de uma gravação assíncrona

Uma requisição bem-sucedida pode significar que o plugin aceitou o trabalho, não que o pagamento ou a cobrança externa foi concluído. No SPI, use o identificador de transferência ou devolução retornado com o endpoint de leitura de [transferência](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-transfer.md) ou [devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/get-refund.md). Para cobranças, leia a cobrança pelo identificador.

Trate estes resultados de forma diferente:

* **Erro de validação ou autorização:** corrija a requisição ou o token. Não repita uma entrada inalterada.
* **Resposta de replay:** mantenha o resultado original. Não crie uma segunda operação de negócio.
* **Conflito:** leia o recurso e escolha a próxima transição permitida.
* **Erro temporário de dependência:** preserve o valor de idempotência antes de repetir. Uma rota que documenta uma dependência que falha de forma fechada continuará recusando a gravação até que essa dependência seja restaurada.

## Manter os limites claros

Seu cliente é responsável pelas chamadas e leituras da API pública. O adaptador de conectividade é responsável pelos resultados do provedor. O plugin é responsável pelo processamento de callbacks e pelo lançamento no Midaz. Essa separação impede que um cliente fabrique estados de liquidação ou contorne as verificações de conta e provedor.

Continue com [Fluxos do SPI](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md) para o sequenciamento de pagamentos, [Fluxos do DICT](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-dict.md) para chaves e MED 2.0 ou [Fluxos do COB](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-cob.md) para BR Codes e cobranças.


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