Visão geral 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

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.

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.

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.

{
  "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"
}

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

curl "$TED_URL/v1/transfers/6f1c2b3a-4d5e-4f60-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $TED_BEARER_TOKEN"

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 <token> 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.<resource>.<event>: 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 traz cada código com a causa e a correção.

Visão geral

API de Transferências

API de TEDs recebidas

API de Conciliação

API de Operações

API de Políticas

API de Participantes

Tratamento de erros

Visão geral da API do TED Lerian

Conceitos

Integre em quatro passos

Status

Autenticação e permissões

Convenções

Erros

​Conceitos

​Integre em quatro passos

​Status

​Autenticação e permissões

​Convenções

​Erros

Conceitos

Integre em quatro passos

Status

Autenticação e permissões

Convenções

Erros