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

> Restrinja a credencial de um parceiro no Midaz a uma organização e, dentro dela, aos ledgers, contas, aliases, carteiras, segmentos, titulares ou rotas que você escolher, e leia as recusas que ele recebe.

Um [parceiro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/overview) pode chamar o Midaz com uma credencial própria. No Midaz, você restringe essa credencial a uma organização e, se quiser, a alguns itens dentro dela. Esta página mostra como escolher esse escopo, o que cada escolha alcança e o que o parceiro recebe quando sai dele.

Todo parceiro do Midaz precisa de escopo. A organização é sempre obrigatória.

## Passo a passo

***

**1. Escolha onde o parceiro atua**

Escolha o escopo mais estreito que cobre o que o parceiro precisa. Cada linha é uma restrição que você pode adicionar. O **campo na API** é o `field` de uma entrada de escopo; o Console mostra o nome da primeira coluna.

| Restrição | Campo na API | O que o parceiro alcança | O que é recusado |
| - | - | - | - |
| **Organização do Midaz** (obrigatória, um valor) | `organizationId` | Sem outra restrição: tudo o que as permissões dele dão dentro dessa organização, em qualquer ledger. | Todas as outras organizações. |
| **Ledger** | `ledgerId` | Os próprios ledgers por ID, e as contas, saldos e transações dentro deles. Ele também lê a organização dele. | Outros ledgers, a lista de ledgers da organização, titulares, instrumentos sem ledger, os registros de auditoria do CRM e as rotas de operação e de transação (veja a última linha). |
| **Conta** | `accountId` | Cada conta listada, os saldos e as operações dela, pelo ID da conta. | Listar as contas do ledger, um saldo pelo próprio ID dele, transações (lista e por ID) e as rotas endereçadas por alias. |
| **Alias de conta** | `accountAlias` | Cada conta listada e os saldos dela, pelas rotas endereçadas por alias. Ele pode criar transações a partir dos próprios aliases. | As rotas endereçadas por ID de conta. |
| **Carteira** ou **Segmento** | `portfolioId`, `segmentId` | Listar contas filtradas pela própria carteira ou segmento, e criar contas nela. | Uma conta por ID, saldos e transações. |
| **Titular** | `holderId` | Os próprios titulares, as contas deles e a lista de contas filtrada pelo próprio titular. | Listar todos os titulares. |
| **Rota de operação** ou **Rota de transação** | `operationRouteId`, `transactionRouteId` | Só as rotas cujos IDs você lista, lidas por ID sob o ledger do parceiro. | Listar rotas, e ler uma rota sob a organização em vez do ledger quando o parceiro também é restrito por ledger. |

O catálogo de escopo lista todas as restrições do Midaz, inclusive as que não estão nesta tabela. Leia-o com [Consultar o catálogo de escopo de um produto](https://docs.lerian.studio/pt/reference/platform/access-manager/retrieve-a-product-s-scope-catalog.md) para `midaz`.

Algumas regras valem para todo escopo:

* Uma requisição que não nomeia um item de um tipo restrito é recusada quando atua sobre o que essa restrição limita. Por exemplo, um parceiro restrito a alguns ledgers não pode listar todos os ledgers da organização dele. Uma requisição fora do que a restrição limita só precisa da organização.
* Uma requisição que lista vários valores, como vários aliases num corpo ou numa query, é recusada quando qualquer um deles está fora do escopo.
* As rotas que atuam sobre o tenant inteiro, como listar organizações ou ler configurações do tenant, são recusadas a todo parceiro.

**2. 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 do Identity](https://docs.lerian.studio/pt/platform/access-manager/features/partners/api.md). O identificador do produto é `midaz`.

* Adicione a entrada de escopo da organização, com exatamente um valor. Sem ela, o Access Manager recusa o parceiro com `400` e `IDE-0001`. Com duas organizações, recusa com `IDE-0002`.
* Adicione as outras restrições que você escolheu no passo 1.
* Marque os recursos e as ações. O máximo que você pode dar é o que o papel `midaz-editor-role` tem no seu tenant. Acima disso, o Access Manager recusa com `IDE-1043`.

O Access Manager confere cada escrita que você dá contra o escopo:

* Uma escrita que atua sobre o tenant inteiro, como criar uma organização, nunca é dada a um parceiro.
* Uma escrita que atua acima do escopo do parceiro é recusada. Por exemplo, um parceiro restrito a um ledger não pode receber o direito de criar, alterar ou excluir ledgers, titulares, ou rotas de operação e de transação: essas escritas atuam sobre a organização inteira.
* As duas recusas respondem `400` com `IDE-1056`. O Console marca a linha como **Fora do escopo**.

Para dar leitura das rotas de operação ou de transação, liste os IDs das rotas no escopo. Sem eles, o Access Manager recusa o parceiro com `400` e `IDE-1052`. O Access Manager não confere se o ID de uma rota pertence ao ledger do parceiro: o parceiro lê toda rota cujo ID você lista. Liste só as rotas dos ledgers dele.

Não dê `transactions` com `post` a um parceiro restrito só por carteira, segmento ou titular. O Access Manager aceita, mas toda transação desse parceiro é recusada.

**3. Crie a aplicação dele no Midaz**

Crie a aplicação do parceiro com o produto `midaz`. Veja [Criar 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.

**4. Diga ao parceiro como nomear os itens dele**

Na maioria das rotas do Midaz, a organização e o ledger já estão no path, então o parceiro não envia nada extra. O parceiro nomeia os outros itens dele nos paths, queries e corpos que o Midaz já tem. Todo valor tem que estar dentro do escopo do parceiro.

Na tabela, `…/ledgers/{ledger_id}` representa `/organizations/{organization_id}/ledgers/{ledger_id}`, depois de `/v1` ou `/v2`.

| Rotas | Escritas | Leituras e rotas por ID |
| - | - | - |
| Organizações e ledgers: `/v1` e `/v2` `/organizations/{organization_id}`, `/organizations/{organization_id}/ledgers` | Path `organization_id` para criar um ledger, e `ledger_id` para alterá-lo, excluí-lo ou alterar as configurações dele | Path `organization_id`, e `ledger_id` para um ledger e as configurações dele |
| Contas: `/v1` e `/v2` `…/ledgers/{ledger_id}/accounts` | Para criar: corpo `portfolioId`, `segmentId` e `parentAccountId`, e na `/v2` também `holderId`. Para alterar, excluir ou encerrar (só na `/v2`): path `account_id` | Para listar: query `portfolio_id`, `segment_id` ou `holder_id`. Uma conta: path `account_id`, ou `alias` em `…/accounts/alias/{alias}` |
| Contas de um titular: `/v2/organizations/{organization_id}/holders/{holder_id}/accounts`, `/v2/…/ledgers/{ledger_id}/holders/{holder_id}/accounts` | Para criar uma conta para o titular: path `holder_id`, e corpo `portfolioId`, `segmentId` e `parentAccountId` | Path `holder_id`, e query `ledger_id`. A resposta traz só as contas desse ledger |
| Exceções de bloqueio de conta: `/v2/…/ledgers/{ledger_id}/accounts/block-exceptions` | Corpo `exceptions[].accountAlias` | Nenhuma: a rota só escreve |
| Saldos: `/v1` e `/v2` `…/ledgers/{ledger_id}/balances`, `…/accounts/{account_id}/balances`, `…/accounts/alias/{alias}/balances` | Para criar: path `account_id`. Para alterar ou excluir: path `balance_id` | Path `account_id` ou `alias` para os saldos de uma conta, e `balance_id` para um saldo e o histórico dele |
| Operações: `/v1` e `/v2` `…/accounts/{account_id}/operations`, `…/transactions/{transaction_id}/operations/{operation_id}` | Para alterar: path `transaction_id` e `operation_id` | Path `account_id`, e `operation_id` para uma operação |
| Transações na `/v1`: `/v1/…/ledgers/{ledger_id}/transactions` | Para criar com `json`, `outflow`, `annotation`, `block` ou `unblock`: corpo `send.source.from[].accountAlias`. `inflow` nomeia só o ledger. Para confirmar, cancelar, reverter ou alterar: path `transaction_id` | Path `transaction_id` |
| Transações na `/v2`: `/v2/transactions`, `/v2/…/ledgers/{ledger_id}/transactions` | Para criar com `direct`, `hold`, `block` ou `unblock`: corpo `debits[].organizationId`, `debits[].ledgerId` e `debits[].alias`, e os mesmos três em `credits[]`. Com `batch`, os mesmos campos em cada item de `transactions[]`. Para confirmar, cancelar, reverter ou alterar: path `transaction_id` | Path `transaction_id` |
| Titulares e instrumentos: `/v2/organizations/{organization_id}/holders`, `/v2/organizations/{organization_id}/holders/{holder_id}/instruments`, `/v2/organizations/{organization_id}/instruments` | Para alterar ou excluir um titular: path `holder_id`. Para criar um instrumento: path `holder_id`, e corpo `ledgerId` e `accountId`, sempre. Para alterar ou excluir um: path `holder_id` e `instrument_id` | Path `holder_id`, e `instrument_id` para um instrumento. Para listar instrumentos: query `holder_id`, `account_id` ou `ledger_id` |
| Rotas de operação e de transação: `/v1` e `/v2` `…/ledgers/{ledger_id}/operation-routes`, `…/ledgers/{ledger_id}/transaction-routes`, e na `/v2` também sob `/organizations/{organization_id}` | Path `organization_id`, e `ledger_id` nas rotas sob o ledger | Path `ledger_id`, com `operation_route_id` ou `transaction_route_id`. As rotas sob a organização não nomeiam o ledger |
| Tarifas e cobrança: `/v2/…/ledgers/{ledger_id}/packages`, `…/billing-packages`, `…/fee-debts` | Pacote de tarifas: corpo `segmentId`. Pacote de cobrança: corpo `accountTarget.segmentId`, `accountTarget.portfolioId` e `accountTarget.aliases[]`. Para cobrar dívidas de tarifa: corpo `accountAlias` | Pacotes de tarifas: query `segmentId`. Dívidas de tarifa: query `account_alias`. Um item: path `package_id`, `billing_package_id` ou `fee_debt_id` |
| Planos de tarifas e cobranças de tarifas: `/v2/…/ledgers/{ledger_id}/account-plans`, `…/accounts/{account_id}/account-plan`, `…/accounts/{account_id}/fee-charges` | Para criar um plano: path `ledger_id`. Para alterar ou excluir um: path `account_plan_id`. Para atribuir um plano: path `account_id` e corpo `accountPlanId`. Para terminar uma atribuição ou cobrar tarifas de serviço: path `account_id` | Path `account_plan_id` para um plano, as versões dele e as contas dele. Path `account_id` para a atribuição, o uso e as cobranças, e `fee_charge_id` para uma cobrança |
| Configuração do ledger e dashboard: ativos, taxas de câmbio, tipos de conta, carteiras, segmentos e `…/ledgers/{ledger_id}/dashboard` | Path `ledger_id`. Para alterar ou excluir um item: path `asset_id`, `account_type_id`, `portfolio_id` ou `segment_id` | Path `ledger_id`. Um item: path `asset_id`, `account_type_id`, `portfolio_id` ou `segment_id` |

> [!WARNING]
>
> Nas rotas de transação da `/v1`, só as contas de origem são conferidas. Um parceiro restrito por alias pode enviar dinheiro dos próprios aliases para qualquer conta do ledger dele. Para mantê-lo entre as próprias contas, não dê a ele `transactions` com `post`.

Nas rotas `/v2/transactions`, todo débito e todo crédito nomeia uma organização e um ledger dentro do escopo. Um parceiro restrito por alias só pode usar os próprios aliases nos dois lados.

Um parceiro restrito por conta ou alias não pode usar estas rotas de transação: `inflow` na `/v1`, e confirmar, cancelar, reverter, alterar, ler por ID ou listar. Um parceiro restrito por alias pode criar uma retenção. Um parceiro restrito por ID de conta não pode criar transações. Para deixá-lo mover dinheiro de contas específicas, restrinja-o por alias.

Um campo de corpo que aceita um item aceita um valor, como `portfolioId` ou o `alias` de um débito. Não envie uma lista nele.

**5. Confirme que funciona**

Esta conferência supõe que o parceiro tem o recurso `accounts` com a ação `get` no Midaz, e um escopo restrito a uma organização e a um ou mais ledgers dela. Use a credencial do parceiro. Liste as contas de um ledger dentro do escopo dele. A resposta é `200`:

```bash theme={null}
MIDAZ_BASE_URL="https://midaz.<your-domain>"              # your Midaz ledger API base URL
MIDAZ_BEARER_TOKEN="paste-the-partner-access-token-here"
ORGANIZATION_ID="paste-the-organization-id-here"          # the organization in the partner's scope
LEDGER_ID="paste-a-ledger-id-in-the-scope-here"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${MIDAZ_BEARER_TOKEN}" \
  "${MIDAZ_BASE_URL}/v1/organizations/${ORGANIZATION_ID}/ledgers/${LEDGER_ID}/accounts"
```

Envie a mesma requisição com um ledger da mesma organização que está fora do escopo. A resposta é `403` com o código `AUT-1020`.

## Se algo falhar

***

| Código | Status | O que significa | O que fazer |
| - | - | - | - |
| `AUT-1020` | 403 | A requisição está fora das permissões ou fora do escopo do parceiro, ou não nomeia um item que o escopo exige. A mensagem nomeia o recurso e a ação: "the credential is not allowed to perform `<resource>:<action>` on this request". | Confira se a requisição nomeia a organização e os itens dela, e se eles estão no escopo do parceiro. Confira também se o parceiro tem a permissão dessa rota. |
| `0047` | 400 | O Midaz não pode ler o escopo da requisição: um campo de que ele precisa está ausente, vazio ou não é uma string. | Envie cada campo de que o escopo precisa, como uma string não vazia. |
| `AUT-1009` | 401 | O parceiro está suspenso. | Reative o parceiro. |
| `AUT-1010` | 401 | A requisição está fora da janela de validade do parceiro. | Altere a janela de validade. |
| `AUT-0021` | 403 | A requisição vem de um endereço fora da lista de IPs do parceiro, ou da lista do seu tenant quando o parceiro não tem uma. | Adicione o endereço à lista de IPs do parceiro. |

A resposta não diz se foram as permissões ou o escopo que recusaram a requisição. Isso é proposital: um parceiro não consegue usar uma recusa para descobrir quais itens existem fora do escopo dele.

Para todos os outros códigos, veja a [lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md). Para as recusas ao criar ou alterar um parceiro, veja os [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.