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

# Gerenciar parceiros pela API

> Crie, leia, altere e exclua parceiros com a Identity API, emita as credenciais deles e trate os códigos de erro que as operações retornam.

<Warning>
  Esta funcionalidade está disponível apenas em Staging para testes e ainda não está disponível em Produção.
</Warning>

A Identity API gerencia [parceiros](/pt/platform/access-manager/features/partners/overview) e as credenciais deles. Use-a quando você gerencia parceiros pelas suas próprias ferramentas em vez do Console.

## As operações

***

| Operação | O que faz | Referência |
| - | - | - |
| `GET /v1/partners` | Lista os seus parceiros, uma página por vez, com `applicationsCount` para cada um. | [Listar parceiros](/pt/reference/platform/access-manager/list-partners) |
| `POST /v1/partners` | Cria um parceiro. Retorna `201` com o novo parceiro e o `id` dele. Nenhuma credencial é criada. | [Criar um parceiro](/pt/reference/platform/access-manager/create-a-partner) |
| `GET /v1/partners/{id}` | Retorna um parceiro completo. | [Consultar um parceiro](/pt/reference/platform/access-manager/retrieve-a-partner) |
| `PATCH /v1/partners/{id}` | Altera um parceiro: o acesso, a janela de validade, a lista de IPs permitidos ou o estado dele. | [Atualizar um parceiro](/pt/reference/platform/access-manager/update-a-partner) |
| `DELETE /v1/partners/{id}` | Exclui um parceiro sem aplicações. Retorna `204`. | [Excluir um parceiro](/pt/reference/platform/access-manager/delete-a-partner) |
| `GET /v1/partners/ceiling` | Retorna o máximo que você pode dar a um parceiro em um produto. | — |

Toda operação precisa de um bearer token com a permissão `partners`. O Access Manager identifica o seu tenant pelo token. Não existe campo de tenant no caminho nem no corpo, e você nunca vê os parceiros de outro tenant.

Para saber quais restrições um produto aceita, leia o catálogo de escopo dele com `GET /v1/scope-catalog/{product}`.

## Os campos do parceiro

***

| Campo | Obrigatório na criação | Significado |
| - | - | - |
| `displayName` | Sim | O nome do parceiro, de 1 a 128 caracteres, único no seu tenant. |
| `permissions` | Sim | Uma ou mais entradas por produto, cada uma com seus próprios `product`, `resources` e `actions`. Cada entrada precisa de pelo menos um recurso e uma ação. |
| `scope` | Não | Uma entrada por restrição: `product`, `field` e `values`. `field` é uma dimensão do catálogo de escopo do produto, como `organizationId` ou `ledgerId`. |
| `ipAllowlist` | Não | A lista de IPs permitidos própria do parceiro. Cada entrada tem um `cidr` e uma `description` opcional. |
| `validFrom` | Não | O início da janela de validade, como um instante RFC 3339. Ausente significa "válido agora". |
| `validUntil` | Não | O fim da janela de validade, como um instante RFC 3339. Ausente significa "sem data de fim". |
| `state` | Não | `active` ou `suspended`. Todo parceiro novo é `active`. Você o altera com `PATCH`. |

A resposta também traz `id`, `applicationsCount`, `createdAt` e `updatedAt`.

Regras que valem para os campos:

* `product` é um slug de produto de [Listar aplicações disponíveis](/pt/reference/platform/access-manager/list-available-applications), como `midaz`.
* `actions` são verbos HTTP em minúsculas: `get`, `post`, `put`, `patch`, `delete`. `head` vem junto com `get`.
* O curinga `*` não é aceito em `resources` nem em `actions`. Liste os valores.
* Um produto em `scope` também precisa estar em `permissions`.
* O Midaz exige um `organizationId` para cada parceiro com permissões no Midaz. Uma dimensão que o catálogo não marca como de vários valores aceita só um valor.
* O Access Manager não confere se os `values` existem no produto. Use os IDs que a própria API do produto retorna.
* `state` nunca mostra `expired`. Depois de `validUntil`, o parceiro continua `active`, com um `validUntil` no passado.

## O campo de lista de IPs permitidos

***

`ipAllowlist` tem três significados no `PATCH`, e eles não são iguais:

| Você envia | O que acontece |
| - | - |
| O campo omitido | A lista guardada continua como está. |
| `null` | A lista própria do parceiro é excluída. O parceiro volta a usar a lista do seu tenant. |
| Uma lista de entradas | A lista própria do parceiro é substituída por estas entradas. |
| `[]` | Recusado com `IDE-1048`. Para bloquear um parceiro por completo, suspenda-o. |

No `POST`, omita o campo ou envie `null` para usar a lista do seu tenant. A lista própria de um parceiro substitui a lista do seu tenant. Ela não se soma a ela.

`validFrom` e `validUntil` funcionam de forma parecida no `PATCH`: omita um limite para mantê-lo, envie um instante para defini-lo ou envie `null` para removê-lo.

## Exemplos

***

Troque os placeholders pela URL base da sua Identity API, por um bearer token que tenha a permissão `partners` e por IDs da sua própria organização do Midaz.

<CodeGroup>
  ```bash Create a partner theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

  curl -sS -X POST "${IDENTITY_BASE_URL}/v1/partners" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "Partner A",
      "permissions": [
        { "product": "midaz", "resources": ["accounts"], "actions": ["get", "post", "patch"] },
        { "product": "midaz", "resources": ["transactions"], "actions": ["get", "post"] }
      ],
      "scope": [
        { "product": "midaz", "field": "organizationId", "values": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"] },
        { "product": "midaz", "field": "ledgerId", "values": ["9c858901-8a57-4791-81fe-4a34d4dd8ab5"] }
      ],
      "ipAllowlist": [
        { "cidr": "203.0.113.10", "description": "Partner A gateway" }
      ]
    }'
  ```

  ```bash Create its application theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
  PARTNER_ID="paste-the-partner-id-here"

  curl -sS -X POST "${IDENTITY_BASE_URL}/v1/applications" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "midaz",
      "description": "Partner A access to Midaz",
      "partnerId": "'"${PARTNER_ID}"'"
    }'
  ```

  ```bash Suspend it theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
  PARTNER_ID="paste-the-partner-id-here"

  curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{ "state": "suspended" }'
  ```

  ```bash Go back to the tenant's IP list theme={null}
  IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
  IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
  PARTNER_ID="paste-the-partner-id-here"

  curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
    -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{ "ipAllowlist": null }'
  ```
</CodeGroup>

## Emitir as credenciais do parceiro

***

Um parceiro sem aplicação não consegue chamar nada. Depois de criar o parceiro:

1. Crie uma aplicação com [Criar uma aplicação](/pt/reference/platform/access-manager/create-an-application) e envie o `id` do parceiro em `partnerId`. Defina `name` como o slug do produto, como `midaz`. Crie uma aplicação por produto.
2. Copie `clientId` e `clientSecret` da resposta. A resposta é a única vez em que o segredo aparece.
3. Envie os dois valores ao parceiro por um canal seguro.

Para listar as aplicações de um parceiro, envie o `id` dele no parâmetro de consulta `partnerId` de [Listar aplicações](/pt/reference/platform/access-manager/list-applications). Se `partnerId` não nomear um parceiro do seu tenant, as duas operações retornam `404` com `IDE-1046`, e nada é criado.

## Alterar, suspender ou excluir um parceiro

***

* No `PATCH`, envie só os campos que você altera. Uma lista `permissions` ou `scope` substitui a lista guardada inteira. Leia o parceiro antes e depois envie a nova lista completa.
* Para suspender um parceiro, envie `"state": "suspended"`. Para reativá-lo, envie `"state": "active"`.
* Uma alteração vale a partir da próxima requisição do parceiro. Uma suspensão também recusa os tokens que o parceiro já tem.
* Você não pode excluir um parceiro que ainda tem aplicações. A resposta é `409` com `IDE-1049`, e a lista `errors` dela nomeia cada aplicação que bloqueia, com o client ID. Exclua essas aplicações antes.

## Códigos de erro

***

Erros nas operações de parceiro:

| Código | Status | Título | Quando |
| - | - | - | - |
| `IDE-0001` | 400 | Missing Fields in Request | Falta um campo obrigatório, ou o escopo não tem entrada para uma dimensão que o produto exige. |
| `IDE-0002` | 400 | Invalid Field Type in Request | Vários valores em uma dimensão de valor único, ou um `state` diferente de `active` ou `suspended`. |
| `IDE-0036` | 400 | Invalid IP Allowlist Entry | Uma entrada de `ipAllowlist` não é um endereço ou uma faixa CIDR válida. |
| `IDE-1040` | 409 | Partner Display Name Already Exists | Outro parceiro do seu tenant tem o mesmo `displayName`. |
| `IDE-1042` | 400 | Unknown Scope Field | Um `field` de escopo não está no catálogo de escopo do produto. |
| `IDE-1043` | 400 | Permission Above Product Ceiling | Uma permissão está acima do que o papel de editor do produto tem no seu tenant. |
| `IDE-1044` | 400 | Scope Without Permissions | Um produto está em `scope`, mas não em `permissions`. |
| `IDE-1045` | 400 | Invalid Validity Window | `validUntil` não é posterior a `validFrom`. |
| `IDE-1046` | 404 | Partner Not Found | Não existe parceiro com este `id` no seu tenant. |
| `IDE-1047` | 400 | Wildcard Not Allowed | `*` está em `resources` ou em `actions`. |
| `IDE-1048` | 400 | Empty IP Allowlist | `ipAllowlist` é um array vazio. |
| `IDE-1049` | 409 | Partner Has Applications | O parceiro ainda tem aplicações, então não pode ser excluído. |
| `IDE-1050` | 400 | Duplicate IP Allowlist Entry | A mesma rede aparece duas vezes em `ipAllowlist`. |
| `IDE-1054` | 400 | Product Not Ready For Partners | O produto ainda não publicou o catálogo de escopo dele. |
| `IDE-1055` | 400 | Product Not Opted In To Partners | O produto tem catálogo de escopo, mas não aceita parceiros. |
| `IDE-1056` | 400 | Partner Write Exceeds Its Scope | Uma escrita atua em um nível mais amplo que o escopo do parceiro, como criar ledgers para um parceiro restrito a um ledger. |

Erros que o próprio sistema do parceiro recebe:

| Código | Status | Quando |
| - | - | - |
| `AUT-0021` | 403 | A requisição vem de um endereço fora da lista de IPs permitidos do parceiro. |
| `AUT-1009` | 401 | O parceiro está suspenso. Retornado nas requisições aos produtos e nos pedidos de token novo. |
| `AUT-1010` | 401 | O parceiro está fora da janela de validade dele. Retornado nas requisições aos produtos e nos pedidos de token novo. |
| Nenhum | 403 | As permissões ou o escopo não permitem a requisição. O produto não diz qual dos dois. |

Para qualquer outro código, consulte a [lista de erros do Access Manager](/pt/reference/platform/access-manager/access-manager-error-list).


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