> ## 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. # Visão geral da API do TED Lerian > Conceitos, integração em quatro passos, status, permissões, convenções e famílias de erro da API do TED Lerian. O TED Lerian é a interface sobre o Lerian SPB, o conector de mensageria própria da Lerian com o STR. A sua instituição usa a API dele para enviar TEDs, fazer transferências internas, acompanhar TEDs recebidas e operar devoluções, filas e política, tudo sobre o ledger Midaz da instituição. Em uma TED, o dinheiro sai da conta apenas quando o STR liquida. Cada operação com efeito é idempotente, então você pode reenviar após um timeout. ## Conceitos *** | Termo | Significado | | - | - | | TED | Uma transferência para outra instituição, liquidada em tempo real pelo STR (Banco Central do Brasil). Ela é assíncrona: a resposta do envio nunca inclui a liquidação. | | Transferência interna | O destinatário está na sua própria instituição. Mesma operação, `POST /v1/transfers`, liquidada imediatamente no ledger (`type=INTERNAL`). | | Conta de origem | A conta debitada, enviada no header `X-Account-Id` (UUID), nunca no body. Ela deve pertencer à sua organização. | | ISPB / COMPE | Identificadores do banco de destino: ISPB (8 dígitos) ou código COMPE (3 dígitos, por exemplo `001`). Envie um deles em `recipient`. `GET /v1/participants` converte um no outro. | | Código de finalidade (`purposeCode`) | Código de 5 dígitos do Dicionário de Domínios do SFN. `99999` (outros) exige `description`. | | Reserva | Valor mais tarifa bloqueados na conta de origem até a liquidação (`SETTLED`). Liberada em `REJECTED` e `CANCELLED`. | | Janela de funcionamento | O horário em que o STR aceita TEDs, reduzido pelo cut-off da instituição e pelo calendário de feriados. `GET /v1/policy/window` informa se ela está aberta. | | `nuop` | Número único de operação no SPB (23 dígitos). Ele aparece quando o STR aceita a TED e identifica a operação em comprovantes e eventos. | | TED recebida | Uma TED que outra instituição envia para um dos seus clientes. O TED Lerian credita, devolve ou abre uma revisão manual, dentro do prazo regulatório de 60 minutos. | | Devolução | Devolução integral de uma TED recebida ao remetente, com um motivo oficial (`returnCode`, CodDevTransf). | ## Integre em quatro passos *** **1. Configure a instituição** Faça isso uma vez, com o papel `editor`. Defina os limites de uso com `PUT /v1/policy/limits`; eles são obrigatórios antes da primeira TED. Para TEDs recebidas, defina os vínculos de ISPB com organização com `PUT /v1/policy/ispb-bindings`. Opcionalmente, defina um cut-off com `PUT /v1/policy/window`. **2. Envie a TED** Envie `X-Account-Id` (a conta debitada) e `X-Idempotency` (uma chave nova para cada pagamento). Para mostrar a tarifa antes de confirmar, chame `POST /v1/transfers/fee-quotes` com os mesmos campos. ```bash theme={null} curl -X POST "$TED_URL/v1/transfers" \ -H "Authorization: Bearer $TED_BEARER_TOKEN" \ -H "X-Account-Id: 0a2f4c6e-8b1d-4e3f-9a5b-7c9d1e3f5a7b" \ -H "X-Idempotency: 9b4f1a6e-3c2d-4e5f-8a7b-6c5d4e3f2a1b" \ -H "Content-Type: application/json" \ -d '{ "amount": "1500.00", "purposeCode": "00010", "description": "Supplier payment", "clientReference": "PED-2026-000123", "recipient": { "bankCode": "001", "agency": "1234", "bankAccount": "0001234567", "bankAccountType": "CACC", "name": "Maria da Silva", "document": "12345678901" } }' ``` O envio retorna `201` com o status que a TED atingiu nesta chamada, normalmente `SUBMITTED`. ```json theme={null} { "transferId": "6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b", "type": "TED", "status": "SUBMITTED", "amount": "1500.00", "feeAmount": "3.25", "totalAmount": "1503.25", "nuop": "87654321202610220000123", "createdAt": "2026-10-22T13:05:12Z" } ``` **3. Acompanhe até a liquidação** Consulte `GET /v1/transfers/{transferId}` até `status` chegar a `SETTLED`, `REJECTED` ou `CANCELLED`, ou faça a subscription dos eventos `transfer.*`. Em `REJECTED`, `rejection.source` e `rejection.code` informam quem recusou e por quê. ```bash theme={null} curl "$TED_URL/v1/transfers/6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b" \ -H "Authorization: Bearer $TED_BEARER_TOKEN" ``` **4. Trate as TEDs recebidas** Liste-as com `GET /v1/incoming-transfers`. O crédito ao cliente é automático. Apenas `status=MANUAL_REVIEW` exige uma decisão do operador (`POST /v1/incoming-transfers/{incomingTransferId}/resolve-review`), e `POST /v1/incoming-transfers/{incomingTransferId}/return` devolve uma TED que já foi creditada. ## Status *** Uma TED enviada passa por estes status. Os status finais são `SETTLED`, `REJECTED` e `CANCELLED`. | Status | Significado | O que fazer | | - | - | - | | `CREATED` → `RESERVED` | Registrada; valor mais tarifa em reserva | Aguarde (pode ser cancelada) | | `SUBMITTED` | Aceita pelo trilho e enviada ao STR | Aguarde a liquidação; não pode ser cancelada | | `PENDING_STR` | O STR mantém o lançamento pendente | Aguarde; você pode pedir o cancelamento | | `SETTLED` | Liquidada; débito confirmado | Nada. Uma devolução posterior aparece em `returned` | | `REJECTED` | Recusada; reserva liberada | Veja `rejection` | | `CANCELLED` | Cancelada antes do envio, ou cancelamento confirmado pelo STR | Nada | | `AWAITING_RECONCILIATION` | Resultado não confirmado; a conciliação automática consulta o trilho (por padrão, a partir de 15 minutos, até 8 tentativas) | Aguarde; não reenvie | | `EXHAUSTED` | A conciliação esgotou as tentativas sem evidência | Um operador resolve com `POST /v1/transfers/{transferId}/unblock` | Uma TED recebida vai de `RECEIVED` (decisão em andamento) para `CREDITED` (creditada ao cliente), `RECORDED` (conta própria da instituição, final), `RETURN_REQUESTED` (o TED Lerian não pode creditá-la) ou `MANUAL_REVIEW` (aguarda um operador; veja `reviewReason`). Ela vai de `RETURN_REQUESTED` para `RETURNED` quando é devolvida. `slaDeadlineAt` é o prazo regulatório de 60 minutos a partir da liquidação interbancária. ## Autenticação e permissões *** Cada chamada, exceto os health checks públicos, envia `Authorization: Bearer ` emitido pelo Access Manager. Os papéis padrão são `editor` (todas as operações), `operator` (todas as operações, exceto as escritas de política e de vínculos de ISPB) e `viewer` (leituras, exceto as leituras de conciliação). | Operações | Permissão | | - | - | | `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | `transfers:create` | | `GET /v1/transfers` e seus sub-recursos | `transfers:read` | | `POST /v1/transfers/{transferId}/cancel` · `POST /v1/transfers/{transferId}/unblock` | `transfers:cancel` · `transfers:unblock` | | `GET /v1/incoming-transfers` e seus sub-recursos | `incoming-transfers:read` | | `POST /v1/incoming-transfers/{incomingTransferId}/return` · `POST /v1/incoming-transfers/{incomingTransferId}/resolve-review` | `incoming-transfers:return` · `incoming-transfers:resolve-review` | | `GET /v1/reconciliation/*` · `POST /v1/reconciliation/reviews/{reviewId}/resolve`, `POST /v1/reconciliation/held-returns/{heldReturnId}/close` · `POST /v1/reconciliation/runs` | `reconciliation:read` · `reconciliation:resolve` · `reconciliation:create` | | `GET /v1/operations/*` | `dashboard:read` | | `GET` e `PUT` em `/v1/policy/window` e `/v1/policy/limits`, `PUT /v1/policy/holidays` | `policy-config:read` / `policy-config:write` | | `GET` e `PUT` em `/v1/policy/ispb-bindings` | `policy-ispb-bindings:read` / `policy-ispb-bindings:write` | | `GET /v1/participants` | `participants:read` | Sem a permissão, ou com uma licença do produto que não é válida para a organização: `403` `TED-0071`. Token ausente ou inválido: `401` `TED-0070`. ## Convenções *** * **Tenant.** Nunca do path, da query ou do body. * **Valores.** Strings decimais em BRL com duas casas decimais (`"1500.00"`), nunca números JSON. * **Datas.** RFC 3339 em UTC (`2026-10-22T13:05:12Z`); dias como `YYYY-MM-DD`. A janela de funcionamento usa o fuso horário da instituição (`America/Sao_Paulo`). * **Idempotência.** Cada operação com efeito exige `X-Idempotency` (de 1 a 128 caracteres ASCII; use um UUID). A mesma chave com o mesmo body retorna a resposta original com `X-Idempotency-Replayed: true` e nenhum efeito novo. Um body diferente retorna `422` `TED-0012`. Se a primeira requisição ainda estiver em processamento, você recebe `409` `TED-0013` (tente de novo após `Retry-After`). O replay dura `X-TTL` segundos (padrão 300). No `POST /v1/transfers`, a chave fica vinculada à transferência que criou. * **Proteção contra duplicidade.** `POST /v1/transfers` pode recusar com `409` `TED-0014` uma requisição materialmente idêntica enviada pouco depois de outra, mesmo com uma chave diferente. Consulte a transferência existente. * **Paginação.** As listas retornam `items`, `limit`, `next_cursor` e `prev_cursor`. Peça até `limit=100` (padrão 20) e siga `next_cursor` até ele ser `null`. O cursor é opaco. * **Correlação.** Envie `X-Request-Id` (UUID) ou receba um gerado. Ele volta em cada resposta e identifica a chamada para o suporte. * **Eventos.** Cada transição é publicada como um CloudEvent com `ce-type` `studio.lerian.br-ted..`: `transfer.*`, `incoming_transfer.*` e `incoming_return.*`. A entrega é pelo menos uma vez; deduplique por `ce-id`. * **Ambientes.** A URL base é por instalação (BYOC ou Lerian Cloud), e a Lerian a fornece. ## Erros *** Cada erro é `application/problem+json` (RFC 9457) com um `code` estável. Trate os erros pelo `code`. `errors` lista os campos inválidos de um `422`. Um `503` significa que a requisição não teve efeito: tente de novo mais tarde com o mesmo `X-Idempotency`. Há três exceções: * `TED-1000`: o ledger não confirmou o resultado, e a operação já pode estar no ledger. Leia o status do recurso antes de agir de novo. * `TED-0080` em um envio: a transferência já pode existir. Procure-a com `GET /v1/transfers` antes de enviá-la de novo. * `TED-1010` em um cancelamento: a resposta do conector do STR é desconhecida, e a solicitação de cancelamento continua registrada. Tente de novo com o mesmo `X-Idempotency` e o mesmo `reason`. Uma chamada limitada pelo rate limit retorna `429` com `Retry-After`: trate-a pelo status e aguarde esse tempo antes de tentar de novo. | Família | Códigos | Quando | | - | - | - | | Requisição | `TED-0001` (400), `TED-0002` a `TED-0007` (422) | JSON malformado; campo, código de finalidade, banco ou documento inválido | | Headers e idempotência | `TED-0008` (400), `TED-0009` (403), `TED-0011` (400), `TED-0012` (422), `TED-0013`/`TED-0014` (409) | `X-Account-Id` ausente ou de outra organização; `X-Idempotency` ausente, reutilizada ou ainda em processamento; requisição duplicada | | Política | `TED-0020`/`TED-0021`/`TED-0030` (422), `TED-0022`/`TED-0040` (503) | Fora da janela; dia não útil; limite; janela ou cálculo de tarifa indisponível | | Status | `TED-0060`/`TED-0061`/`TED-0062`/`TED-0067` (409), `TED-0063` a `TED-0066` (422) | Ação incompatível com o status; não pode ser cancelada; não pode ser devolvida; devolução retida ainda vinculada a uma transferência; devolução ou evidência inválida | | Acesso | `TED-0070` (401), `TED-0071` (403) | Token; permissão ou licença | | Configuração | `TED-0080` (503), `TED-0081` (422) | Instituição sem configuração obrigatória; cut-off depois do fechamento oficial | | Dependências | `TED-1000`/`TED-1010`/`TED-1012`/`TED-1020` (503), `TED-1001`/`TED-1021` (422) | Ledger, conector do STR ou cadastro indisponível ou recusando os dados | | Interno | `TED-9000` (500), `TED-9002` (503) | Falha inesperada: contate o suporte com o `X-Request-Id`; serviço indisponível, por exemplo quando a trilha de auditoria não consegue registrar uma mudança de política | Em um envio, `TED-0031`, `TED-1001`, `TED-1011` e `TED-1013` nunca chegam como resposta de erro. Eles chegam em `rejection.code` de uma transferência com status `REJECTED`, na resposta `201` ou em uma consulta posterior. A [lista de erros](https://docs.lerian.studio/pt/reference/interfaces/ted-lerian/ted-lerian-error-list.md) traz cada código com a causa e a correção. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.