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

# Parceiros no Pix Lerian

> Restrinja as credenciais de Pix Lerian de um parceiro às contas em que ele atua, informe a conta em cada requisição e entenda as recusas que ele recebe.

Um [parceiro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/overview) pode chamar o Pix Lerian com a sua própria credencial. Você restringe essa credencial a algumas contas do seu tenant. Isso é necessário quando o parceiro atua para alguns dos seus clientes e não pode agir nas contas dos outros.

Todo parceiro de Pix Lerian precisa de um escopo.

## Passo a passo

***

**1. Escolha os produtos que o parceiro usa**

O Pix Lerian é composto de quatro produtos no Access Manager. Dê ao parceiro apenas os produtos de que ele precisa:

| Produto | Slug do produto | O que ele atende |
| - | - | - |
| **SPI** | `plugin-br-pix-lerian-spi` | Cash-out e cash-in, devoluções, Pix Agendado e bloqueios de saldo. |
| **DICT hub** | `plugin-br-pix-lerian-dict` | Chaves, reivindicações e MED. |
| **COB hub** | `plugin-br-pix-lerian-cob` | Cobranças e BR Codes. |
| **Pix Automático** | `plugin-br-pix-lerian-pixauto` | As autorizações do pagador e os pagamentos delas. |

O adaptador de conectividade não aceita parceiros. Apenas os serviços do Pix Lerian o chamam.

**2. Escolha as contas em que o parceiro atua**

O Pix Lerian tem uma restrição, a mesma nos quatro produtos:

| Restrição | Campo da API | O que o parceiro alcança | O que é recusado |
| - | - | - | - |
| **Conta** | `accountId` | Os registros de Pix de cada conta da lista: o ID da conta na Midaz do pagador ou do cliente, o mesmo ID que o seu cliente envia em `X-Account-Id`. | Todas as outras contas, e as rotas que não levam conta (veja [Rotas que nenhum parceiro alcança](#routes-that-no-partner-reaches)). |

O Pix Lerian não tem restrição de organização nem de ledger. Cada tenant opera uma organização e um ledger da Midaz. A configuração do tenant os define, e nenhuma requisição os informa. Para restringir um parceiro a um ledger, dê a ele também um [escopo na Midaz](https://docs.lerian.studio/pt/platform/access-manager/features/partners/midaz.md). Veja [As regras do parceiro na Midaz valem para as suas chamadas](#the-partners-midaz-rules-apply-to-its-calls).

**3. Dê ao parceiro as permissões e o escopo**

Crie o parceiro, ou altere-o, no [Console](https://docs.lerian.studio/pt/platform/access-manager/features/partners/console.md) ou com a [API de Identity](https://docs.lerian.studio/pt/platform/access-manager/features/partners/api.md). Use os slugs de produto do primeiro passo. A restrição aceita várias contas.

* Adicione a entrada de escopo `accountId` em cada produto do Pix Lerian que você der. Sem ela, o Access Manager recusa o parceiro com `400` e `IDE-1060`.
* Confira os recursos e as ações. O máximo que você pode dar é o que o papel de editor de cada produto tem no seu tenant. Acima disso, o Access Manager recusa com `IDE-1043`.

Algumas escritas agem em rotas que não levam conta:

* Os bloqueios de saldo.
* A caixa de saída de notificações.
* As rotas de operador que executam e recuperam trabalhos.
* A recuperação de uma transferência ou de uma devolução: `transfer-recovery` e `refund-recovery`, ação `post`.
* As configurações de runtime.

O Access Manager as recusa com `400` e `IDE-1056`, e o Console marca a linha como **Fora do escopo**.

O Access Manager também recusa, com o mesmo código, as escritas que alteram uma chave, abrem uma recuperação de valores ou criam um pagamento recorrente. Veja [Rotas que nenhum parceiro alcança](#routes-that-no-partner-reaches).

**4. Crie as aplicações de Pix Lerian**

Crie as aplicações do parceiro com os produtos do Pix Lerian que você deu a ele. Veja [Crie as aplicações do parceiro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/api.md#create-the-partners-applications) no guia da API, ou [no Console](https://docs.lerian.studio/pt/platform/access-manager/features/partners/console.md#create-the-partners-applications). Envie o client ID e o client secret ao parceiro por um canal seguro.

**5. Informe a conta em cada requisição**

Toda requisição informa a conta em um campo que o Pix Lerian já tem. O valor precisa estar no escopo do parceiro. Um parceiro precisa enviar a conta em todas as rotas desta tabela, também onde o campo é opcional para outros chamadores. Uma requisição sem ela é recusada.

| Produto | Rotas | Onde vai a conta |
| - | - | - |
| SPI | Transferências: `POST /spi/v1/transfers/cashout/initiate`, `POST /spi/v1/transfers/cashout/process`, `GET /spi/v1/transfers`, `GET /spi/v1/transfers/{id}`, `POST /spi/v1/transfers/{id}/refunds` | Cabeçalho `X-Account-Id` |
| SPI | Devoluções: `GET /spi/v1/refunds`, `GET /spi/v1/refunds/{id}` | Cabeçalho `X-Account-Id` |
| SPI | Escritas de Pix Agendado: `POST /spi/v1/scheduled-payments`, `POST /spi/v1/scheduled-payment-recurrences` | Corpo `accountId` |
| SPI | Listas de Pix Agendado: `GET /spi/v1/scheduled-payments`, `GET /spi/v1/scheduled-payment-totals`, `GET /spi/v1/scheduled-payment-limit-impact`, `GET /spi/v1/scheduled-payment-recurrences` | Query `account_id` |
| DICT hub | Chaves: `GET` e `POST /dict-hub/v1/entries`, `GET` e `DELETE /dict-hub/v1/entries/{entry_id}`, `GET /dict-hub/v1/keys/{key}` | Cabeçalho `X-Account-Id` |
| DICT hub | Reivindicações: `GET` e `POST /dict-hub/v1/claims`, `GET /dict-hub/v1/claims/{claim_id}`, `POST /dict-hub/v1/claims/{claim_id}/cancel`, `/complete` e `/confirm` | Cabeçalho `X-Account-Id` |
| DICT hub | Recuperações de valores do MED: `GET /dict-hub/v1/dict/funds-recoveries` | Query `account_id` |
| COB hub | `POST /cob-hub/v1/brcodes/static`, `GET` e `POST /cob-hub/v1/collections/immediate`, `GET` e `DELETE /cob-hub/v1/collections/immediate/{id}`, `GET` e `POST /cob-hub/v1/collections/duedate`, `GET /cob-hub/v1/collections/duedate/provider-status`, `GET`, `PATCH` e `DELETE /cob-hub/v1/collections/duedate/{id}` | Cabeçalho `X-Account-Id` |
| Pix Automático | Solicitações de autorização: `GET /pixauto/v1/payer/authorization-requests`, `GET /pixauto/v1/payer/authorization-requests/{authorization_request_id}`, `POST .../{authorization_request_id}/decide` | Cabeçalho `X-Account-Id` |
| Pix Automático | Autorizações: `GET /pixauto/v1/payer/authorizations`, `GET` e `PATCH /pixauto/v1/payer/authorizations/{authorization_id}`, `GET .../{authorization_id}/history`, `POST .../{authorization_id}/cancel` | Cabeçalho `X-Account-Id` |
| Pix Automático | Pagamentos agendados: `GET /pixauto/v1/payer/scheduled-payments`, `GET /pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}`, `POST .../{scheduled_payment_id}/cancel`, `POST .../{scheduled_payment_id}/unblock` | Cabeçalho `X-Account-Id` |
| Pix Automático | `POST /pixauto/v1/payer/authorization-requests/from-qr` | Corpo `payerAccountId` |

Uma requisição que informa um registro de outra conta responde `404`, como se o registro não existisse. Nada é lido ou alterado.

**6. Confirme que funciona**

Esta verificação supõe que o parceiro tem o recurso `transfers` com a ação `get` em `plugin-br-pix-lerian-spi`, e um escopo com uma ou mais contas. Use a credencial do parceiro. Liste as transferências de uma conta do escopo do parceiro. A resposta é `200`:

```bash theme={null}
PIX_LERIAN_SPI_BASE_URL="https://pix.<your-domain>"          # your Pix Lerian SPI base URL
PIX_LERIAN_BEARER_TOKEN="paste-the-partner-access-token-here"
OWN_ACCOUNT_ID="paste-an-account-in-the-scope"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${PIX_LERIAN_BEARER_TOKEN}" \
  -H "X-Account-Id: ${OWN_ACCOUNT_ID}" \
  "${PIX_LERIAN_SPI_BASE_URL}/spi/v1/transfers"
```

Envie a mesma requisição com uma conta fora do escopo do parceiro. A resposta é `403` com `PIX-0010`.

## As regras do parceiro na Midaz valem para as suas chamadas

***

Alguns produtos do Pix Lerian chamam a Midaz enquanto atendem a requisição do parceiro:

* O SPI lança os débitos e os créditos no ledger, e lê a conta e o seu titular.
* O DICT hub e o Pix Automático leem o titular e a conta no CRM embutido na Midaz.

Quando o parceiro também tem permissões na Midaz, a Midaz aplica o escopo do parceiro na Midaz a essas chamadas. Por exemplo, considere um parceiro restrito na Midaz à organização do tenant e a um ledger. Ele consegue iniciar e processar um cash-out de uma conta desse ledger. Com o mesmo parceiro restrito na Midaz a outro ledger, o Pix Lerian recusa a iniciação e o processamento com `403` e `PIX-0005`, e o saldo da conta não muda.

* Um parceiro sem permissões na Midaz é decidido apenas pelas suas permissões e escopo no Pix Lerian.
* Você pode dar ao parceiro as regras da Midaz no mesmo fluxo do Console, ou depois, no produto Midaz.
* As varreduras agendadas, os callbacks do provedor e os outros trabalhos em segundo plano rodam sem parceiro. As regras do parceiro não se aplicam a eles.

> [!WARNING]
>
> Não conte com as regras da Midaz com um CRM 3.x independente. Se o seu deploy lê titulares de um CRM 3.x independente, esse CRM não aplica as regras do parceiro. Apenas o CRM embutido na Midaz as aplica.

## Rotas que nenhum parceiro alcança

***

Um parceiro com escopo no Pix Lerian é recusado com `403` e `PIX-0010` nas rotas que não levam conta:

* SPI: todas as rotas de `/spi/v1/balance-locks`, as rotas de um pagamento agendado ou de uma recorrência (`/spi/v1/scheduled-payments/{schedule_id}` e `/spi/v1/scheduled-payment-recurrences/{recurrence_id}`, com as rotas abaixo delas), e as rotas de operador.
* DICT hub: `POST /dict-hub/v1/claims/{claim_id}/acknowledge`, `POST /dict-hub/v1/keys/check`, as rotas de uma recuperação de valores, e as rotas de notificações de infração, devoluções, marcações de fraude e VSync.
* COB hub: `POST /cob-hub/v1/brcodes/decode`, `GET /cob-hub/v1/brcodes/static` e `GET /cob-hub/v1/brcodes/static/{id}`.
* Pix Automático: `POST /pixauto/v1/payer/recurring-consents` e `POST /pixauto/v1/payer/recurring-consents/{recurring_consent_id}/revoke`.

Essas rotas agem sobre registros que nenhuma conta informa.

O Pix Lerian também recusa um parceiro, com a mesma resposta, em três rotas em que a conta da requisição não vincula o que a rota altera:

* `PATCH /dict-hub/v1/entries/{entry_id}`: a requisição pode mover a chave para outra conta.
* `POST /dict-hub/v1/dict/funds-recoveries`: a rota abre a recuperação sobre uma transação que a conta não vincula.
* `POST /pixauto/v1/payer/recurring-payments`: a rota aceita o pagamento sob um consentimento que a conta não vincula.

O Pix Lerian também recusa um parceiro, com a mesma resposta, nas quatro rotas de recuperação do SPI. Isso vale também quando a requisição informa uma conta do escopo do parceiro:

* `POST /spi/v1/transfers/{id}/unblock` e `POST /spi/v1/transfers/{id}/credit`.
* `POST /spi/v1/refunds/{id}/unblock` e `POST /spi/v1/refunds/{id}/credit`.

A sua equipe de operações usa essas rotas para corrigir uma transação presa em processamento, ou um crédito que falhou no ledger. Elas agem pelo tenant inteiro, então a conta da requisição não as restringe.

Use uma aplicação da sua própria instituição para todas essas rotas.

## Se algo falhar

***

| Código | Status | O que significa | O que fazer |
| - | - | - | - |
| `PIX-0010` | 403 | A requisição informa uma conta fora do escopo do parceiro, não informa nenhuma, ou está fora das permissões ou da lista de IPs do parceiro. | Envie a conta no campo daquela rota, com uma conta do escopo do parceiro. Confira também as permissões e a lista de IPs do parceiro. |
| `PIX-0010` | 401 | O parceiro está suspenso, ou a requisição está fora do seu período de validade. | Reative o parceiro, ou altere o seu período de validade. |
| `PIX-0005` | 403 | A Midaz recusou o parceiro em uma chamada que o Pix Lerian fez para ele: a chamada está fora das permissões ou do escopo do parceiro na Midaz. Nada é movimentado. | Confira as permissões e o escopo do parceiro na Midaz. |
| `PIX-0320` | 404 | A iniciação pertence a outra conta. Nada é lido ou alterado. | Confira o ID da iniciação e a conta. |
| `PIX-0340` | 404 | A transferência pertence a outra conta. Nada é lido ou alterado. | Confira o ID da transferência e a conta. |

O `PIX-0010` não diz se foram as permissões ou o escopo que recusaram a requisição. Isso é intencional: um parceiro não consegue usar uma recusa para descobrir quais contas existem fora do seu escopo.

Uma alteração em um parceiro, como uma suspensão ou um novo escopo, vale a partir da próxima requisição dele, também com um token que ele já tem.

Para todos os outros códigos, veja a [lista de erros do Pix Lerian](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/pix-lerian-error-list.md). Para as recusas ao criar ou alterar um parceiro, veja [Códigos de erro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/api.md#error-codes) no guia da API.


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