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

# Enviar e receber TED

> Envie uma TED de uma conta do Midaz ou do seu próprio core, e receba uma TED em uma conta do Midaz, pelo TED Lerian e pelo Lerian SPB.

Envie uma TED de uma conta de cliente no Midaz ou do seu próprio core, e receba uma TED para os seus clientes.

> [!NOTE]
>
> Os manuais do BACEN para o STR prevalecem sobre esta página. Sua instituição valida o fluxo e o implementa sobre as APIs da Lerian. Veja [como ler os diagramas](https://docs.lerian.studio/pt/diagrams/introduction.md).

## Participantes

***

* **Sua instituição.** O seu sistema. Ele envia as TEDs, consulta as TEDs e recebe os eventos.
* **TED Lerian.** A interface de TED entre o Midaz e o Lerian SPB. Ele confere cada TED, movimenta o dinheiro no Midaz e publica os eventos. O [Streaming Hub](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) entrega os eventos ao seu sistema.
* **Midaz.** O ledger. Ele guarda as contas dos clientes e os seus saldos.
* **Lerian SPB.** A mensageria da Lerian para o STR. Ele envia e recebe as mensagens do STR e informa a liquidação delas.
* **STR (BACEN).** O Sistema de Transferência de Reservas do BACEN. Ele liquida cada TED entre as contas Reservas Bancárias.
* **Instituição remetente.** Outra instituição. Ela envia uma TED para um cliente seu.

## Antes de começar

***

* Defina os seus limites de uso com [`PUT /v1/policy/limits`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/set-usage-limits).
* Carregue o calendário nacional de feriados de cada ano com [`PUT /v1/policy/holidays`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/replace-the-holidays-of-a-year), antes de o ano começar. Um ano carregado cobre todas as datas dele. Em uma data cujo ano não está carregado, o TED Lerian recusa a TED.
* Opcionalmente, defina o seu cut-off com [`PUT /v1/policy/window`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/set-the-cut-off). Ele não pode ser posterior ao fechamento oficial.
* Para cobrar uma tarifa, crie no ledger um pacote de tarifas do Midaz que selecione pelos [rótulos de lançamento do TED Lerian](https://docs.lerian.studio/pt/interfaces/ted-lerian/ted-lerian-business-rules.md#fees).
* Para receber TEDs, vincule o seu ISPB à organização e ao ledger do Midaz que recebem os créditos, com [`PUT /v1/policy/ispb-bindings`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/replace-ispb-bindings). O vínculo precisa da organização no Midaz, da conta `@external/BRL` no ledger e do titular da sua instituição com uma conta no CRM.
* Cada conta que recebe TEDs tem um titular e um instrumento no Midaz, com a agência, o número e o tipo da conta em `bankingDetails`. Veja [Cadastrar um titular e abrir uma conta](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-register-a-holder.md).

## Diagrama

***

### Enviar de uma conta do Midaz

![Enviar e receber TED: Enviar de uma conta do Midaz](https://mintcdn.com/lerian-49cb71fc/moPIbGcvckksJUDi/images/pt/d2/id-send-and-receive-ted-1.svg?fit=max\&auto=format\&n=moPIbGcvckksJUDi\&q=85\&s=653199da153f1d8e9edcff150035e3ba)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | TED Lerian | Chamada de API | [`POST /v1/transfers/fee-quotes`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/quote-a-transfer-fee) | Opcional. Envie o recebedor, o valor e o código de finalidade. O header `X-Account-Id` indica a conta de origem. |
| 2 | TED Lerian | Sua instituição | Resposta da API | Resposta ao passo 1 | `200` com a estimativa de tarifa em `feeAmount`, `totalAmount`, `windowOpen` e `nextWindowOpensAt`. A cotação não movimenta dinheiro. |
| 3 | Sua instituição | TED Lerian | Chamada de API | [`POST /v1/transfers`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/send-a-ted) | Envie a TED com `recipient`, `amount`, `purposeCode` e, opcionalmente, `clientReference`. Envie a conta de origem em `X-Account-Id` e uma chave em `X-Idempotency`. |
| 4 | TED Lerian | TED Lerian | Etapa interna | | O TED Lerian confere o código de finalidade, o documento do recebedor, o banco do recebedor na lista de participantes do STR, a janela e os seus limites de uso. |
| 5 | TED Lerian | Midaz | Chamada interna | [`POST /v2/transactions/hold`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-hold) | O TED Lerian cria uma transação pendente pelo valor, marcada como `ted_sent`. O Midaz soma a tarifa que os seus pacotes de tarifas aplicam e retém o valor mais a tarifa na conta de origem. A transferência fica em `RESERVED`. |
| 6 | TED Lerian | Lerian SPB | Chamada interna | [`POST /v1/str/operations/bank-transfers`](https://docs.lerian.studio/pt/reference/rails/spb/create-bank-transfer-operation) | O TED Lerian envia a TED ao Lerian SPB, com o remetente e o recebedor como clientes. |
| 7 | TED Lerian | Sua instituição | Resposta da API | Resposta ao passo 3 | `201` com a transferência em `SUBMITTED`. |
| 8 | Lerian SPB | STR (BACEN) | `STR0008` | | O Lerian SPB envia ao STR a TED entre dois clientes. |
| 9 | STR (BACEN) | Lerian SPB | `STR0008R1` | | O STR liquida a TED e responde. |
| 10 | Lerian SPB | TED Lerian | Evento | | O Lerian SPB informa a liquidação com `settlement.settled`. |
| 11 | TED Lerian | Sua instituição | Evento | Evento `transfer.settled` | A transferência fica em `SETTLED`. |
| 12 | TED Lerian | Midaz | Chamada interna | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit`](https://docs.lerian.studio/pt/reference/products/midaz/v2/commit-transaction) | O TED Lerian confirma a transação pendente. O valor retido vai para `@external/BRL`, e a tarifa vai para a conta que o seu pacote de tarifas credita. |

### Enviar do seu próprio core

![Enviar e receber TED: Enviar do seu próprio core](https://mintcdn.com/lerian-49cb71fc/moPIbGcvckksJUDi/images/pt/d2/id-send-and-receive-ted-2.svg?fit=max\&auto=format\&n=moPIbGcvckksJUDi\&q=85\&s=a91851fef2bb1bd2af853bc183d4b1fc)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | Lerian SPB | Chamada de API | [`POST /v1/str/operations/bank-transfers`](https://docs.lerian.studio/pt/reference/rails/spb/create-bank-transfer-operation) | Envie `sender` e `recipient` com `party` igual a `client`, o `amount` e o `purposeCode`. Envie uma chave em `X-Idempotency`. |
| 2 | Lerian SPB | Sua instituição | Resposta da API | Resposta ao passo 1 | `201` com a operação. O Lerian SPB aceitou a TED para envio. |
| 3 | Lerian SPB | STR (BACEN) | `STR0008` | | O Lerian SPB envia ao STR a TED entre dois clientes. |
| 4 | STR (BACEN) | Lerian SPB | `STR0008R1` | | O STR liquida a TED e responde. |
| 5 | Lerian SPB | Sua instituição | Evento | Evento `settlement.settled` | O Lerian SPB informa a posição final da operação. |
| 6 | Sua instituição | Sua instituição | Etapa interna | | Lance o débito no seu core. |

### Receber e creditar

![Enviar e receber TED: Receber e creditar](https://mintcdn.com/lerian-49cb71fc/moPIbGcvckksJUDi/images/pt/d2/id-send-and-receive-ted-3.svg?fit=max\&auto=format\&n=moPIbGcvckksJUDi\&q=85\&s=007ce787fb91ef57f630c5d3189fdfb6)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Instituição remetente | STR (BACEN) | `STR0008` | | Outra instituição envia uma TED para um cliente seu. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | O STR liquida a TED e informa o crédito à sua instituição. |
| 3 | Lerian SPB | TED Lerian | Evento | | O Lerian SPB repassa o crédito ao TED Lerian com `str.operation.received`. |
| 4 | TED Lerian | Sua instituição | Evento | Evento `incoming_transfer.received` | O TED Lerian registra a TED como `RECEIVED`. Nada foi creditado ainda. |
| 5 | TED Lerian | Midaz | Chamada interna | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-instruments) | O TED Lerian procura a conta na agência e no número da conta do recebedor. Ele procura na organização à qual o seu ISPB está vinculado. |
| 6 | Midaz | TED Lerian | Chamada interna | | O Midaz devolve a conta, o documento do titular e a data de encerramento, se houver. |
| 7 | TED Lerian | TED Lerian | Etapa interna | | O TED Lerian confere se a conta está aberta, se o documento do titular corresponde à TED e se o tipo de conta na TED é o tipo da conta. |
| 8 | TED Lerian | Midaz | Chamada interna | [`POST /v2/transactions/direct`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-transaction-direct) | O TED Lerian lança uma transação, marcada como `ted_received`. Ela debita `@external/BRL` e credita a conta do cliente. Quando o seu pacote de tarifas deduz uma tarifa do crédito, o cliente recebe o valor menos a tarifa. |
| 9 | TED Lerian | Sua instituição | Evento | Evento `incoming_transfer.credited` | A TED fica em `CREDITED`, com `creditedAmount` e `feeAmount`. |

### Devolver quando a conta não pode receber

![Enviar e receber TED: Devolver quando a conta não pode receber](https://mintcdn.com/lerian-49cb71fc/moPIbGcvckksJUDi/images/pt/d2/id-send-and-receive-ted-4.svg?fit=max\&auto=format\&n=moPIbGcvckksJUDi\&q=85\&s=ea68814f5c11f42d52d6e1e7b372b610)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Instituição remetente | STR (BACEN) | `STR0008` | | Outra instituição envia uma TED para um cliente seu. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | O STR liquida a TED e informa o crédito à sua instituição. |
| 3 | Lerian SPB | TED Lerian | Evento | | O Lerian SPB repassa o crédito ao TED Lerian com `str.operation.received`. |
| 4 | TED Lerian | Sua instituição | Evento | Evento `incoming_transfer.received` | O TED Lerian registra a TED como `RECEIVED`. |
| 5 | TED Lerian | Midaz | Chamada interna | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-instruments) | O TED Lerian procura a conta na agência e no número da conta do recebedor. |
| 6 | Midaz | TED Lerian | Chamada interna | | O Midaz não encontra conta ali, ou devolve uma conta que não pode receber a TED. |
| 7 | TED Lerian | TED Lerian | Etapa interna | | O TED Lerian decide devolver a TED com o motivo oficial. |
| 8 | TED Lerian | Sua instituição | Evento | Evento `incoming_return.requested` | O TED Lerian registra a devolução antes de enviá-la. A TED fica em `RETURN_REQUESTED`. |
| 9 | TED Lerian | Lerian SPB | Chamada interna | [`POST /v1/str/operations/bank-transfers/{operationId}/returns`](https://docs.lerian.studio/pt/reference/rails/spb/create-bank-transfer-return-operation) | O TED Lerian pede ao Lerian SPB que devolva a TED com o motivo. |
| 10 | Lerian SPB | STR (BACEN) | `STR0010` | | O Lerian SPB envia a devolução ao STR. |
| 11 | STR (BACEN) | Lerian SPB | `STR0010R1` | | O STR liquida a devolução e responde. |
| 12 | Lerian SPB | TED Lerian | Evento | | O Lerian SPB informa a liquidação da devolução com `settlement.settled`. |
| 13 | TED Lerian | Sua instituição | Evento | Evento `incoming_return.returned` | A TED fica em `RETURNED`. O dinheiro voltou para a instituição remetente, e nenhum saldo mudou no Midaz. |

### Receber em uma conta da sua instituição

![Enviar e receber TED: Receber em uma conta da sua instituição](https://mintcdn.com/lerian-49cb71fc/moPIbGcvckksJUDi/images/pt/d2/id-send-and-receive-ted-5.svg?fit=max\&auto=format\&n=moPIbGcvckksJUDi\&q=85\&s=5a2eadcb565ecac11f23242020dd1633)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Instituição remetente | STR (BACEN) | `STR0008` | | Outra instituição envia uma TED para uma conta que a sua instituição detém. |
| 2 | STR (BACEN) | Lerian SPB | `STR0008R2` | | O STR liquida a TED e informa o crédito à sua instituição. |
| 3 | Lerian SPB | TED Lerian | Evento | | O Lerian SPB repassa o crédito ao TED Lerian com `str.operation.received`. |
| 4 | TED Lerian | Sua instituição | Evento | Evento `incoming_transfer.received` | O TED Lerian registra a TED como `RECEIVED`. |
| 5 | TED Lerian | Midaz | Chamada interna | [`GET /v2/organizations/{organization_id}/instruments`](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-instruments) | O TED Lerian procura a conta na agência e no número da conta do recebedor. |
| 6 | Midaz | TED Lerian | Chamada interna | | O Midaz devolve a conta. O documento do titular é o CNPJ da sua organização no Midaz. |
| 7 | TED Lerian | TED Lerian | Etapa interna | | O TED Lerian registra a TED e não credita nada no Midaz. |
| 8 | TED Lerian | Sua instituição | Evento | Evento `incoming_transfer.recorded` | A TED fica em `RECORDED`, com `kind` igual a `INSTITUTION`. |

## Regras

***

* Aceita não é liquidada. Um `201` com `SUBMITTED` significa que o Lerian SPB aceitou a TED para envio. O dinheiro retido só sai da conta de origem depois que o STR liquida a TED.
* Os limites de uso contam o valor mais a tarifa. Uma TED rejeitada ou cancelada libera os limites de novo.
* Quando o banco do recebedor é o seu próprio ISPB, a transferência é interna (`type` igual a `INTERNAL`). O Midaz a liquida, e nada vai para o STR.
* Do seu próprio core, defina `party` no remetente e no recebedor. Sem ele, a parte é `institution`, e o Lerian SPB envia outra mensagem do STR.
* O TED Lerian credita uma TED recebida uma vez, também quando o Lerian SPB a entrega duas vezes.
* Quando a conta não pode receber uma TED, o TED Lerian a devolve com o motivo oficial:
  * `1`: uma conta encerrada.
  * `2`: nenhuma conta nessa agência e nesse número.
  * `5`: o documento do titular não corresponde.
  * `84`: o tipo de conta na TED não é o tipo da conta.
* Uma conta é considerada encerrada quando a sua data de encerramento é hoje ou anterior, no horário de Brasília.
* Quando o TED Lerian não consegue decidir sozinho, a TED vai para `MANUAL_REVIEW`.

## Como saber que terminou

***

* **Envio.** O evento `transfer.settled`, ou [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/get-a-transfer) com `status` igual a `SETTLED`. Do seu próprio core, o evento `settlement.settled` da operação.
* **Recebimento.** O evento `incoming_transfer.credited`, `incoming_return.returned` ou `incoming_transfer.recorded`, ou [`GET /v1/incoming-transfers/{incomingTransferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/get-an-incoming-ted) com `status` igual a `CREDITED`, `RETURNED` ou `RECORDED`.

## O que pode dar errado

***

| Situação | O que você vê | O que fazer |
| - | - | - |
| Fora da grade oficial ou depois do seu cut-off | `422` com `TED-0020` | Nada é reservado. Envie a TED na próxima janela. [`GET /v1/policy/window`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/get-the-operating-window) mostra a janela. |
| Um fim de semana ou um feriado | `422` com `TED-0021` | Nada é reservado. Envie a TED no próximo dia útil. |
| O TED Lerian não consegue determinar a janela | `503` com `TED-0022` | Nada é reservado. Se o calendário de feriados daquele ano não está carregado, carregue-o. Depois envie a TED de novo. |
| Seus limites de uso não estão definidos | `503` com `TED-0080` | Defina os limites com [`PUT /v1/policy/limits`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/set-usage-limits). |
| Um limite de uso foi excedido | `422` com `TED-0030` | Nada é reservado. Reduza o valor, ou espere o próximo dia ou mês. |
| Não foi possível determinar a tarifa | `503` com `TED-0040` | Nada é reservado. Leia o `detail`: corrija a configuração dos pacotes de tarifas ou tente de novo mais tarde, conforme a causa. |
| A conta de origem não consegue pagar o valor mais a tarifa | `201` com `REJECTED` e `rejection.code` igual a `TED-0031` | Nada é reservado. Ajuste o valor. |
| O Lerian SPB ou o STR recusa a TED | `REJECTED` na resposta, ou depois com `transfer.rejected` | O TED Lerian libera a reserva. Leia `rejection`, corrija os dados e envie uma nova TED com uma nova chave. |
| O Midaz ou o Lerian SPB não responde ao TED Lerian a tempo | `201` com `AWAITING_RECONCILIATION`, ou `transfer.awaiting_reconciliation` | Não envie a TED de novo. Se a transferência ficar em `EXHAUSTED`, um operador a destrava com a evidência do STR por [`POST /v1/transfers/{transferId}/unblock`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/unblock-a-transfer). |
| A sua requisição fica sem resposta | Um timeout | Não presuma que a TED falhou. Envie a mesma requisição com a mesma chave `X-Idempotency`. A mesma chave nunca cria uma segunda transferência. Antes de usar uma nova chave, procure a transferência com [`GET /v1/transfers`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/list-transfers) filtrada por `client_reference`. |
| A instituição recebedora devolve uma TED que você enviou | `transfer.returned` | O TED Lerian credita o valor de volta na conta de origem. A transferência continua `SETTLED`. |
| Do seu próprio core, o STR não liquida a TED | `settlement.failed` | A TED não foi liquidada. Não lance o débito. |
| Uma TED recebida aguarda uma decisão | `incoming_transfer.manual_review` | Leia o `reviewReason` da TED recebida. Depois credite a TED, devolva-a ou confirme o crédito dela com [`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/resolve-an-incoming-ted-review). Decida antes de `slaDeadlineAt`. |
| O STR recusa uma devolução automática | `incoming_return.failed` | A TED vai para `MANUAL_REVIEW`. Decida com [`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/resolve-an-incoming-ted-review). |

A [lista de erros do TED Lerian](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/ted-lerian-error-list.md) descreve cada código.

## Relacionados

***

* [Cancelar ou devolver uma TED](https://docs.lerian.studio/pt/diagrams/native-rails/cancel-or-return-a-ted.md)
* [Reservar um valor e depois confirmar ou cancelar](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-reserve-then-confirm-or-cancel.md)
* [Como o TED Lerian funciona](https://docs.lerian.studio/pt/interfaces/ted-lerian/ted-lerian-how-it-works.md)
* [Eventos do TED Lerian](https://docs.lerian.studio/pt/interfaces/ted-lerian/ted-lerian-events.md)
* [Eventos e integração com o ledger do Lerian SPB](https://docs.lerian.studio/pt/rails/spb/spb-events-and-ledger-integration.md)


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