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 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 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 ou com a API do Identity. 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 no guia da API, ou no Console. 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

   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:

   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. Para as recusas ao criar ou alterar um parceiro, veja os códigos de erro no guia da API.