> ## 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 na TED Lerian

> Restrinja a credencial de TED Lerian de um parceiro à organização e ao ledger da Midaz da sua instalação, informe-os 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 a TED Lerian com a sua própria credencial. Você restringe essa credencial à organização da Midaz e, se quiser, ao ledger em que a TED Lerian trabalha. Esta página trata da TED Lerian. Para a TED JD, veja [Parceiros na TED](https://docs.lerian.studio/pt/platform/access-manager/features/partners/ted.md).

Todo parceiro de TED Lerian precisa de um escopo.

> [!NOTE]
>
> Você precisa do Access Manager v3.20.0 ou posterior. As versões anteriores não aceitam as permissões da TED Lerian.

## Passo a passo

***

**1. Escolha onde o parceiro atua**

A TED Lerian tem duas restrições. As duas valem para os recursos `transfers` e `incoming-transfers`:

| Restrição | Campo da API | O que o parceiro alcança | O que é recusado |
| - | - | - | - |
| **Organização da Midaz** | `organizationId` | Enviar uma TED e obter uma cotação de tarifa, ler e listar transferências e as suas linhas do tempo, cancelar uma transferência, e ler e listar TEDs recebidas e as suas linhas do tempo. | Todas as outras organizações, e as rotas que agem sobre o tenant inteiro (veja [Rotas que nenhum parceiro alcança](#routes-that-no-partner-reaches)). |
| **Ledger da Midaz** | `ledgerId` | Enviar uma TED e obter uma cotação de tarifa. O ledger fica sob a organização. | Todos os outros ledgers. Também as leituras, o cancelamento e as TEDs recebidas (veja [A restrição de ledger cobre apenas o envio](#the-ledger-restriction-covers-only-sending)). |

A TED Lerian trabalha em uma organização e em um ledger: os que estão configurados para a sua instituição. Veja a configuração em [Visão geral da API da TED Lerian](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/ted-lerian-api-overview.md). Coloque essa organização, e esse ledger se você restringir por ledger, no escopo do 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 de Identity](https://docs.lerian.studio/pt/platform/access-manager/features/partners/api.md). O slug do produto é `plugin-br-ted-lerian`.

* Adicione a entrada de escopo da organização. Sem uma entrada de escopo, o Access Manager recusa o parceiro com `400` e `IDE-1060`.
* Para restringir o parceiro a um ledger, adicione também a entrada de escopo do ledger.
* Confira os recursos e as ações. O máximo que você pode dar é o que o papel de editor da TED Lerian tem no seu tenant. Acima disso, o Access Manager recusa com `IDE-1043`.

Um parceiro pode ter apenas estas permissões:

| Permissão | Rotas | Parceiro restrito à organização | Parceiro restrito a um ledger |
| - | - | - | - |
| `transfers:create` | `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | Sim | Sim |
| `transfers:read` | `GET /v1/transfers`, `GET /v1/transfers/{transferId}`, `GET /v1/transfers/{transferId}/timeline` | Sim | Não |
| `transfers:cancel` | `POST /v1/transfers/{transferId}/cancel` | Sim | Não |
| `incoming-transfers:read` | `GET /v1/incoming-transfers`, `GET /v1/incoming-transfers/{incomingTransferId}`, `GET /v1/incoming-transfers/{incomingTransferId}/timeline` | Sim | Não |

O Access Manager recusa todas as outras permissões com `400` e `IDE-1056`. Essas permissões agem sobre o tenant inteiro: o desbloqueio e a decisão da análise de fraude de uma transferência, a devolução e as decisões sobre uma TED recebida, a conciliação, os dashboards, a política e os vínculos de ISPB, a lista de participantes, o catálogo de eventos e as configurações de runtime. O Access Manager também recusa com `IDE-1056` as permissões marcadas com **Não** para um parceiro restrito a um ledger. O Console marca essas linhas como **Fora do escopo**.

**3. Crie a aplicação de TED Lerian**

Crie a aplicação do parceiro com o produto `plugin-br-ted-lerian`. 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.

**4. Informe a organização e o ledger em cada requisição**

O parceiro informa a organização no cabeçalho `X-Organization-Id`, e o ledger no cabeçalho `X-Ledger-Id`. Os dois cabeçalhos são opcionais para os outros chamadores. Um parceiro deve enviá-los como esta tabela mostra. Uma requisição sem eles é recusada.

| Rotas | `X-Organization-Id` | `X-Ledger-Id` |
| - | - | - |
| Envio e cotação de tarifa: `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | Sempre | Quando o parceiro está restrito a um ledger |
| Transferências: `GET /v1/transfers`, `GET /v1/transfers/{transferId}`, `GET /v1/transfers/{transferId}/timeline`, `POST /v1/transfers/{transferId}/cancel` | Sempre | Não é lido |
| TEDs recebidas: `GET /v1/incoming-transfers`, `GET /v1/incoming-transfers/{incomingTransferId}`, `GET /v1/incoming-transfers/{incomingTransferId}/timeline` | Sempre | Não é lido |

Os cabeçalhos não escolhem a organização nem o ledger. A TED Lerian sempre os obtém da sua configuração, e os cabeçalhos apenas os confirmam. A TED Lerian confere cada cabeçalho que lê:

| Cabeçalho | Resposta |
| - | - |
| Ausente | A requisição roda como roda sem parceiros. |
| Igual à configuração | A requisição roda. |
| Outro valor, ou não é um UUID | `400` com `TED-0001`. A mensagem nomeia o cabeçalho. |
| Presente, e a configuração não tem o valor | `503` com `TED-0080`. |

Essa conferência vale para todos os chamadores, também para as aplicações da sua própria instituição.

Quando um envio ou uma cotação de tarifa traz `X-Ledger-Id`, a conta em `X-Account-Id` deve ser uma conta desse ledger. Caso contrário, a resposta é `400` com `TED-0001`. A TED Lerian também faz essa conferência em uma nova tentativa com uma chave `X-Idempotency` que ela já usou. Ela não repete uma resposta guardada para uma conta de outro ledger.

**5. Confirme que funciona**

Use a credencial de um parceiro com `transfers:read`, restrito apenas à organização. Liste as transferências da organização do escopo do parceiro. A resposta é `200`:

```bash theme={null}
TED_LERIAN_BASE_URL="https://ted-lerian.<your-domain>"     # your TED Lerian base URL
TED_LERIAN_BEARER_TOKEN="paste-the-partner-access-token-here"
MIDAZ_ORGANIZATION_ID="paste-the-organization-in-the-scope"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${TED_LERIAN_BEARER_TOKEN}" \
  -H "X-Organization-Id: ${MIDAZ_ORGANIZATION_ID}" \
  "${TED_LERIAN_BASE_URL}/v1/transfers"
```

Envie a mesma requisição sem o cabeçalho `X-Organization-Id`. A resposta é `403` com `TED-0071`.

## A restrição de ledger cobre apenas o envio

***

A TED Lerian lê o ledger apenas quando um parceiro envia uma TED ou obtém uma cotação de tarifa. As leituras, o cancelamento e as TEDs recebidas não trazem ledger. Uma transferência pode estar em um ledger anterior da sua instituição, e uma TED recebida pode estar em qualquer ledger dos vínculos de ISPB. A TED Lerian não as filtra por ledger.

Por isso, um parceiro restrito a um ledger pode apenas enviar e obter cotações de tarifa. O Access Manager se recusa a dar a ele `transfers:read`, `transfers:cancel` ou `incoming-transfers:read`, com `400` e `IDE-1056`. Para permitir que um parceiro leia ou cancele transferências, restrinja-o apenas à organização.

Um parceiro restrito à organização lê todas as transferências e TEDs recebidas da organização, em todos os ledgers. Dê a ele `transfers:read` e `incoming-transfers:read` apenas quando ele puder ver todas elas.

## TEDs recebidas sem organização

***

A TED Lerian atribui cada TED recebida a uma organização. Uma TED recebida que ela ainda não consegue atribuir não tem organização e aguarda em `MANUAL_REVIEW`. Um parceiro não vê essas TEDs recebidas:

* `GET /v1/incoming-transfers` não as lista.
* `GET /v1/incoming-transfers/{incomingTransferId}` e `GET /v1/incoming-transfers/{incomingTransferId}/timeline` respondem `404`, como se a TED não existisse.

As aplicações da sua instituição continuam vendo essas TEDs recebidas quando não agem por um parceiro. Use uma delas para revisar as TEDs recebidas que não têm organização.

## As regras do parceiro na Midaz não valem para as suas transferências

***

A TED Lerian chama a Midaz e o CRM com a sua própria credencial, também quando atende um parceiro. As permissões e o escopo do parceiro na Midaz não se aplicam a essas chamadas.

A TED Lerian não tem restrição de conta. A conta em `X-Account-Id` deve pertencer à organização da TED Lerian, ou a resposta é `403` com `TED-0009`. Quando a requisição traz `X-Ledger-Id`, a conta também deve ser uma conta desse ledger, ou a resposta é `400` com `TED-0001`.

> [!WARNING]
>
> Dê `transfers:create` apenas a um parceiro que possa enviar de todas as contas da organização. Um parceiro com essa permissão pode enviar de qualquer conta da organização que ele informar em `X-Account-Id`.

## Rotas que nenhum parceiro alcança

***

Todas as rotas fora da tabela do passo 2 agem sobre o tenant inteiro. Um parceiro não pode ter as permissões dessas rotas, então a TED Lerian o recusa com `403` e `TED-0071`:

* O desbloqueio e a decisão da análise de fraude de uma transferência.
* A devolução, a decisão de revisão e a decisão da verificação de fraude de uma TED recebida.
* As rotas de conciliação, `/v1/reconciliation/*`.
* Os dashboards de operações, `/v1/operations/*`.
* A política e os vínculos de ISPB, `/v1/policy/*`.
* A lista de participantes, `GET /v1/participants`.
* As configurações de runtime, `/v1/system/*`.

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

## Se algo falhar

***

| Código | Status | O que significa | O que fazer |
| - | - | - | - |
| `TED-0071` | 403 | A requisição informa uma organização ou um ledger fora do escopo do parceiro, ou não envia um cabeçalho que o parceiro deve enviar. Ela também está fora das permissões ou da lista de IPs do parceiro. | Envie `X-Organization-Id`, e `X-Ledger-Id` quando o parceiro estiver restrito a um ledger, com valores do escopo do parceiro. Confira também as permissões e a lista de IPs do parceiro. |
| `TED-0070` | 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. |
| `TED-0001` | 400 | `X-Organization-Id` ou `X-Ledger-Id` não é um UUID, ou informa outra organização ou outro ledger que não os da configuração da TED Lerian. Em um envio ou uma cotação de tarifa, a conta em `X-Account-Id` não é uma conta do ledger em `X-Ledger-Id`. | Envie a organização e o ledger para os quais a TED Lerian está configurada. Um chamador que não é parceiro também pode deixar de enviar o cabeçalho. Debite uma conta desse ledger. |
| `TED-0080` | 503 | A requisição envia um cabeçalho, e a TED Lerian não tem organização ou ledger configurado para comparar com ele. | O administrador configura a organização e o ledger da TED Lerian. |

O `TED-0071` 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 organizações ou ledgers existem fora do seu escopo.

Uma alteração em um parceiro, como uma suspensão ou um novo escopo, vale na sua próxima requisição, também com um token que ele já tem. Quando a TED Lerian guarda as decisões do Access Manager por um tempo, definido em `AUTH_CACHE_TTL`, a alteração vale depois desse tempo.

Para todos os outros códigos, veja a [lista de erros da TED Lerian](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/ted-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.