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

# TED por um parceiro

> Envie, receba e devolva TED por uma interface de parceiro.

Envie, receba e devolva TED quando um parceiro conecta sua instituição ao STR.

> [!NOTE]
>
> Esta página sugere uma forma de ler os manuais do BACEN para a TED. A documentação do parceiro e os manuais prevalecem sobre esta página. Sua instituição, como participante, valida o fluxo e o implementa sobre as APIs da Lerian. Veja [como ler os diagramas](https://docs.lerian.studio/pt/diagrams/introduction.md).

## TED pela JD

***

### Participantes

* **Sua instituição.** Chama a API do TED JD e lê o resultado de cada TED.
* **TED JD.** A interface de conectividade entre o Midaz e a JD. Ele lança cada TED no Midaz e troca as mensagens da TED com a JD.
* **Midaz.** O ledger que guarda as contas dos seus clientes.
* **STR.** O Sistema de Transferência de Reservas do BACEN. Liquida cada TED.
* **JD.** O parceiro que troca as mensagens da TED com o STR.
* **Outra instituição.** A instituição na outra ponta de uma TED que sua instituição recebe ou que volta.

### Antes de começar

* O TED JD está configurado para sua instituição. Veja [Configuração](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md).
* A conta que envia, recebe ou devolve a TED existe no Midaz e tem um titular.
* Onde a entrega de webhooks está ligada no seu deploy, registre seu endpoint com [`POST /v1/webhooks`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/create-webhook). [`GET /v1/webhooks/event-types`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-webhook-event-types) lista os eventos que você pode assinar.
* Para devolver uma TED recebida, cada rota de operação do crédito da TED no Midaz tem o `operationType` `bidirectional`. Veja [Rotas Contábeis](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md).

### Enviar uma TED pela JD

![TED por um parceiro: Enviar uma TED pela JD](https://mintcdn.com/lerian-49cb71fc/TAE_w2TeOCWL7fKX/images/pt/d2/id-partner-ted-1.svg?fit=max\&auto=format\&n=TAE_w2TeOCWL7fKX\&q=85\&s=160636801282ceed5fdb53d196abc306)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | TED JD | API da Lerian | [`POST /v1/transfers/initiate`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/initiate-transfer) | Envie a conta pagadora em `senderAccountId`, o `recipient`, o `purpose` e o `amount`. Envie os cabeçalhos `X-Organization-Id` e `X-Idempotency`. |
| 2 | TED JD | Midaz | Chamada interna | | O TED JD lê a conta pagadora e o titular dela no Midaz. |
| 3 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 1 | O TED JD responde `200` com o `initiationId`, o `feeAmount`, o `totalAmount` e o `expiresAt`. Nada se moveu ainda. |
| 4 | Sua instituição | TED JD | API da Lerian | [`POST /v1/transfers/process`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/process-transfer) | Envie o `initiationId` antes do `expiresAt`. Envie os cabeçalhos `X-Organization-Id` e `X-Idempotency`. |
| 5 | TED JD | Midaz | Chamada interna | | O TED JD reserva o `totalAmount` na conta pagadora com uma transação pendente. O `amount` vai para a conta externa. |
| 6 | TED JD | JD | API da JD | | O TED JD envia a TED à JD. |
| 7 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 4 | O TED JD responde `200` com a TED em `PROCESSING`. Guarde o `transferId` dela. |
| 8 | JD | STR | Entre outras partes | | A JD envia a TED ao STR. |
| 9 | STR | JD | Entre outras partes | | O STR liquida ou rejeita a TED. |
| 10 | TED JD | JD | API da JD | | O TED JD consulta o resultado na JD. |
| 11 | TED JD | Midaz | Chamada interna | | Para uma TED liquidada, o TED JD confirma a transação pendente. Para uma TED rejeitada, ele cancela a transação pendente e libera o valor. |
| 12 | TED JD | Sua instituição | Webhook | Webhook `transfer.completed` ou `transfer.rejected` | A TED fica `COMPLETED`, ou `REJECTED` para uma TED rejeitada. |
| 13 | Sua instituição | TED JD | API da Lerian | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) | Consulte a TED com o `transferId` do passo 7. |
| 14 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 13 | O TED JD responde com a TED e o status dela. |

### Receber uma TED pela JD

![TED por um parceiro: Receber uma TED pela JD](https://mintcdn.com/lerian-49cb71fc/TAE_w2TeOCWL7fKX/images/pt/d2/id-partner-ted-2.svg?fit=max\&auto=format\&n=TAE_w2TeOCWL7fKX\&q=85\&s=b7adcd48c2b2eb89cc9adfa6a1d61f04)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Outra instituição | STR | Entre outras partes | | A instituição pagadora envia uma TED para uma das suas contas. |
| 2 | STR | JD | Entre outras partes | | O STR liquida a TED e a envia à JD. |
| 3 | TED JD | JD | API da JD | | O TED JD consulta as mensagens novas na JD. |
| 4 | JD | TED JD | Resposta | | A JD responde com a TED recebida. |
| 5 | TED JD | Midaz | Chamada interna | | O TED JD encontra a conta recebedora no Midaz pela agência, número da conta, tipo de conta e documento do recebedor. |
| 6 | TED JD | Midaz | Chamada interna | | O TED JD credita a conta recebedora em uma transação. A transação debita a conta externa. |
| 7 | TED JD | Sua instituição | Webhook | Webhook `transfer_incoming.completed` | A TED recebida fica `COMPLETED`. O evento traz o `transferId` dela. |
| 8 | Sua instituição | TED JD | API da Lerian | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) | Consulte a TED recebida. Sem o evento, encontre-a com [`GET /v1/transfers`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-transfers). |
| 9 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 8 | A TED recebida está em `COMPLETED`. |

### Uma TED enviada volta pela JD

![TED por um parceiro: Uma TED enviada volta pela JD](https://mintcdn.com/lerian-49cb71fc/TAE_w2TeOCWL7fKX/images/pt/d2/id-partner-ted-3.svg?fit=max\&auto=format\&n=TAE_w2TeOCWL7fKX\&q=85\&s=6013c4f8a101d989871419818152623e)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Outra instituição | STR | Entre outras partes | | A instituição que recebeu sua TED a devolve. |
| 2 | STR | JD | Entre outras partes | | O STR liquida a devolução e a envia à JD. |
| 3 | TED JD | JD | API da JD | | O TED JD consulta as mensagens novas na JD. |
| 4 | JD | TED JD | Resposta | | A JD responde com a devolução da sua TED. |
| 5 | TED JD | Sua instituição | Webhook | Webhook `transfer_outgoing.devolution_notified` | O evento indica a TED que você enviou, o código de devolução em `codDevTransf` e o `amount`. |
| 6 | TED JD | Midaz | Chamada interna | | O TED JD credita a conta pagadora com o valor devolvido. A transação debita a conta externa. |
| 7 | TED JD | Sua instituição | Webhook | Webhook `transfer_incoming.completed` | O crédito fica `COMPLETED`. |
| 8 | Sua instituição | TED JD | API da Lerian | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) | Consulte a TED que você enviou. |
| 9 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 8 | A TED que você enviou continua em `COMPLETED` e mostra o código de devolução em `devolutionCode`. |

### Devolver uma TED recebida pela JD

![TED por um parceiro: Devolver uma TED recebida pela JD](https://mintcdn.com/lerian-49cb71fc/TAE_w2TeOCWL7fKX/images/pt/d2/id-partner-ted-4.svg?fit=max\&auto=format\&n=TAE_w2TeOCWL7fKX\&q=85\&s=c96af39bee09d9fe1d734b61472ebe35)

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | TED JD | API da Lerian | [`POST /v1/transfers/{transferId}/return`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/return-transfer) | Envie o `transferId` da TED recebida no caminho. Envie os cabeçalhos `X-Organization-Id` e `X-Idempotency`. Quando uma aplicação chama, envie também o `externalReference` no corpo. |
| 2 | TED JD | Midaz | Chamada interna | | O TED JD lê no Midaz o crédito da TED recebida e as rotas de operação dele. Ele confere se o crédito pode ser revertido. |
| 3 | TED JD | Midaz | Chamada interna | | O TED JD reserva o valor creditado com uma transação pendente. Ela debita a conta que recebeu a TED e credita a conta externa. |
| 4 | TED JD | Sua instituição | Webhook | Webhook `transfer_incoming.return_requested` | O TED JD começou a devolução. |
| 5 | TED JD | JD | API da JD | | O TED JD envia à JD a devolução do valor total, com o código de devolução `70`. |
| 6 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 1 | O TED JD responde `201` com a devolução em `PROCESSING`. Guarde o `transferId` dela. |
| 7 | JD | STR | Entre outras partes | | A JD envia a devolução ao STR. |
| 8 | STR | JD | Entre outras partes | | O STR liquida ou rejeita a devolução. |
| 9 | TED JD | JD | API da JD | | O TED JD consulta o resultado na JD. |
| 10 | TED JD | Midaz | Chamada interna | | Para uma devolução liquidada, o TED JD cancela a transação pendente. Depois, ele reverte o crédito da TED recebida em uma transação nova. Para uma devolução rejeitada, ele só cancela a transação pendente. |
| 11 | TED JD | Sua instituição | Webhook | Webhook `transfer_incoming.returned` ou `transfer_incoming.return_rejected` | A devolução fica `COMPLETED`, ou `REJECTED` para uma devolução rejeitada. |
| 12 | Sua instituição | TED JD | API da Lerian | [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) | Consulte a devolução com o `transferId` do passo 6. |
| 13 | TED JD | Sua instituição | API da Lerian | Resposta ao passo 12 | O TED JD responde com a devolução e o status dela. |

### Regras para a JD

#### Enviar uma TED

* O TED JD envia uma TED por iniciação. Quando você confirma o mesmo `initiationId` de novo, o TED JD não envia uma segunda TED.
* A reserva no Midaz não é a liquidação.

#### Receber uma TED

* Quando a JD entrega a mesma TED de novo, o TED JD não a credita de novo.

#### Uma TED enviada volta

* O crédito é uma nova transferência recebida, com um `transferId` próprio. O `originalTransferId` dela indica a TED que você enviou.
* Onde a configuração da sua instituição a liga, uma devolução do valor total também pode devolver a tarifa da TED que você enviou.

#### Devolver uma TED recebida

* A devolução envia de volta o valor total da TED recebida.
* A devolução é uma nova transferência de `type` `TED_OUT`, com um `transferId` próprio. A TED recebida continua em `COMPLETED`.

### Como saber que terminou na JD

* **Enviar uma TED.** O webhook `transfer.completed` ou `transfer.rejected` informa o status final. Depois de uma conciliação, o webhook `transfer.reconciliation_resolved` ou `transfer.reconciliation_failed` informa o status, e a TED também pode terminar em `FAILED`. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) mostra o status.
* **Receber uma TED.** O webhook `transfer_incoming.completed` informa o crédito. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) mostra a TED recebida em `COMPLETED`.
* **Uma TED enviada volta.** O webhook `transfer_outgoing.devolution_notified` informa a devolução, e `transfer_incoming.completed` informa o crédito. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) mostra a TED que você enviou com um `devolutionCode`.
* **Devolver uma TED recebida.** O webhook `transfer_incoming.returned` ou `transfer_incoming.return_rejected` informa o status final. [`GET /v1/transfers/{transferId}`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer) com o `transferId` da devolução mostra `COMPLETED` ou `REJECTED`.

### O que pode dar errado na JD

#### Enviar uma TED

| Situação | O que você vê | O que fazer |
| - | - | - |
| A janela de operação da TED está fechada. | `422`, código `BTF-0010`. | Nada se moveu. Envie a TED quando a janela estiver aberta. |
| A iniciação expirou. | O passo 4 responde `410`, código `BTF-0202`. | Nada se moveu. Comece uma TED nova. |
| A conta pagadora não tem o saldo. | O passo 4 responde `422`, código `BTF-2003`. | Nada se moveu. Adicione fundos e comece uma TED nova. |
| A JD recusa a TED. | O passo 4 responde `422`, código `BTF-1001`, com o código da JD em `upstream.code`. | O TED JD liberou o valor reservado. A TED está em `REJECTED`. Confira os dados do recebedor e comece uma TED nova. |
| A JD não responde. | O passo 4 responde `503`, código `BTF-1000` ou `BTF-1003`, com o `transferId`. | Não envie uma TED nova. O TED JD mantém a reserva e pergunta o resultado à JD. Consulte a TED mais tarde. |
| A JD não recebeu a TED, ou informa um erro para ela. | O webhook `transfer.reconciliation_resolved` ou `transfer.reconciliation_failed`. A TED está em `FAILED`, com `reconciliationStatus` `RESOLVED`. | O TED JD liberou o valor reservado. Comece uma TED nova. |
| A resposta ao passo 4 não chega. | Nenhuma resposta, ou um timeout. | Envie o passo 4 de novo com o mesmo `initiationId` e a mesma chave `X-Idempotency`. |
| O TED JD não consegue saber o resultado pela JD. | A TED mostra `reconciliationStatus` `MANUAL_REVIEW`, e o valor continua reservado. A TED está em `PROCESSING`, ou em `FAILED` quando o TED JD esgotou as tentativas. O webhook `transfer.reconciliation_exhausted` informa o caso `FAILED` e alguns casos `PROCESSING`. | Confirme o resultado com a JD. Quando a JD responder liquidada, resolva a TED com [`POST /v1/transfers/{transferId}/reconciliation/resolve`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/resolve-transfer-reconciliation) e `SETTLE`, que conclui a TED. Quando a JD responder recusada, resolva com `REVERT`, que libera o valor reservado. Quando a JD responder pendente ou não encontrada, devolva uma TED em `PROCESSING` para a conciliação com [`POST /v1/transfers/{transferId}/reconciliation/retry`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retry-transfer-reconciliation). O TED JD consulta a JD de novo, e a reserva continua. |
| Você quer parar uma TED que o TED JD ainda não enviou. | A TED está em `CREATED` ou `PENDING`. | Cancele-a com [`POST /v1/transfers/{transferId}/cancel`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/cancel-transfer). O TED JD cancela a TED e libera qualquer valor reservado. |

#### Receber uma TED

| Situação | O que você vê | O que fazer |
| - | - | - |
| O TED JD não consegue creditar a TED recebida. | O webhook `transfer_incoming.undeliverable`. | O TED JD devolve a TED à instituição pagadora, ou a guarda para a sua análise. Encontre-a com [`GET /v1/transfers/ted-in/undeliverables`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits). |

#### Devolver uma TED recebida

| Situação | O que você vê | O que fazer |
| - | - | - |
| A TED não pode ser devolvida. | `422`, código `BTF-0118`. | Nada foi criado. Confira o `transferId`. |
| A TED recebida já tem uma devolução. | `409`, código `BTF-0119`. O `transferId` indica essa devolução. | Consulte essa devolução. |
| A janela de operação da TED está fechada. | `422`, código `BTF-0010`. | Nada foi criado. Peça de novo quando a janela estiver aberta. |
| O Midaz não pode reverter o crédito da TED recebida. | `422`, código `BTF-0120`. O `reason` diz o motivo. | Nada foi reservado nem enviado. `route_not_reversible` quer dizer que o roteamento do crédito da TED no Midaz não permite uma reversão. |
| O Midaz recusa a reserva. | `422`, código `BTF-0121`, com o `reason` `insufficient_balance` ou `prior_reservation_pending`. | Nada foi enviado. Com `insufficient_balance`, peça de novo quando a conta tiver o valor creditado. Com `prior_reservation_pending`, peça de novo mais tarde. Use uma chave `X-Idempotency` nova. |
| O TED JD não consegue concluir o pedido. | `503`, código `BTF-2000`. Quando a devolução existe, o `transferId` indica essa devolução. | Nada foi enviado. O TED JD encerra essa devolução e libera qualquer valor reservado. Depois, peça de novo com uma chave `X-Idempotency` nova. |
| A JD recusa a devolução. | `422`, código `BTF-1001`, com o código da JD em `upstream.code`. | O TED JD libera o valor reservado, e a devolução termina em `REJECTED`. |
| O TED JD não tem certeza de que a JD recebeu a devolução. | O passo 6 traz `reconciliationStatus` `AWAITING`. | O TED JD pergunta o resultado à JD. Consulte a devolução mais tarde. |
| O TED JD separa a devolução para uma decisão manual. | O webhook `transfer_incoming.return_manual_review`. | Consulte a devolução. O `reconciliationReasonCode` dela diz o motivo. Depois, resolva a devolução com [`POST /v1/transfers/{transferId}/reconciliation/resolve`](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/resolve-transfer-reconciliation). |
| A resposta ao passo 1 não chega. | Nenhuma resposta, ou um timeout. | Envie a mesma chamada de novo com a mesma chave `X-Idempotency`. |

## Relacionados

***

* [Enviar e receber TED](https://docs.lerian.studio/pt/diagrams/native-rails/send-and-receive-ted.md): as mesmas jornadas no Lerian SPB nativo.
* [Cancelar ou devolver uma TED](https://docs.lerian.studio/pt/diagrams/native-rails/cancel-or-return-a-ted.md): a devolução no Lerian SPB nativo.
* [Enviar (TED OUT)](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-out.md)
* [Receber (TED IN)](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-in.md)
* [Webhooks](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md)
* [Guia do desenvolvedor](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-developer-guide.md)


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