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. O TED Lerian recusa um código desconhecido, ou que não está vigente na data da requisição, no Dicionário de Domínios FinlddCli do BACEN. 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 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, vincule cada ISPB com PUT /v1/policy/ispb-bindings à organização e ao ledger onde esta instalação credita as TEDs recebidas. Qualquer outra organização ou ledger recebe 422 TED-0002. Com as integrações de ledger e CRM ligadas, um vínculo também precisa da organização no Midaz, da conta @external/BRL no ledger e do titular da sua instituição (o CNPJ da organização) com uma conta no CRM. Um item ausente recebe 422 TED-0002, e a mensagem o indica. Carregue o calendário de feriados nacionais de cada ano com PUT /v1/policy/holidays, antes de o ano começar. Para cobrar tarifas, crie pacotes de tarifas do Midaz que selecionem pelos rótulos de lançamento do TED Lerian. Opcionalmente, defina um cut-off com PUT /v1/policy/window. Sem cut-off, a janela segue a grade oficial do STR.

2. Envie a TED

   Envie X-Account-Id (a conta debitada) e X-Idempotency (uma chave nova para cada pagamento). Para mostrar uma estimativa de 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": "12345678909"
       }
     }'
   

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

   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. A TED aguarda a decisão do STR, ou antes uma aprovação no Lerian SPB quando o Lerian SPB exige uma.	Aguarde a liquidação; não pode ser cancelada
PENDING_STR	O STR mantém o lançamento pendente. Se o Lerian SPB não conhece a TED no fechamento do dia, ela passa a AWAITING_RECONCILIATION e a reserva continua	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. O reviewReason aparece só enquanto o status é MANUAL_REVIEW; a timeline guarda os motivos anteriores. Um estorno de operador que falha leva a TED a MANUAL_REVIEW. LEDGER_REVERT_REFUSED significa que o ledger recusou e o crédito continua. LEDGER_REVERT_INDETERMINATE significa que o resultado é desconhecido e o crédito pode ter sido estornado. 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 mesma chave com a mesma requisição também repete a resposta depois do X-TTL: a resposta é 201 com X-Idempotency-Replayed: true e a transferência no estado atual. Uma chave nova em uma devolução ou em uma decisão de revisão já aplicada retorna 409 TED-0060.
• Proteção contra duplicidade. POST /v1/transfers pode recusar com 409 TED-0014 uma requisição materialmente idêntica com uma chave nova, enviada pouco depois de outra. Consulte a transferência existente. Para repetir uma requisição, envie a mesma chave.
• 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, e o type termina com esse código. Trate os erros pelo code. errors lista os campos inválidos de um 422. Um JSON malformado recebe 400 TED-0001, e um campo ou parâmetro fora do schema declarado recebe 422 TED-0002.

Um 503 significa que a requisição não teve efeito: tente de novo mais tarde com o mesmo X-Idempotency. Estas são as 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.
• TED-1010 em uma devolução de TED recebida: a resposta do STR é desconhecida. Qualquer crédito já foi estornado. A devolução continua solicitada até a conciliação ou a revisão manual. Leia o status da TED antes de agir de novo.
• TED-1012 em um cancelamento: o rail da sua instituição não cancela um lançamento pendente. Uma nova tentativa recebe a mesma resposta, e a TED segue o resultado do STR.
• TED-0022 para uma data cujo ano não tem calendário de feriados: carregue o ano com PUT /v1/policy/holidays. Só tentar de novo não resolve.

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 (dígitos verificadores incluídos)
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 indeterminada ou ano de feriados não carregado; estimativa 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, ou um pacote de tarifas que tira uma tarifa do valor enviado; cut-off depois do fechamento oficial
Dependências	TED-1000/TED-1010/TED-1012/TED-1020 (503), TED-1001/TED-1011/TED-1021 (422)	Ledger, conector do STR ou cadastro indisponível ou recusando os dados
Interno	TED-9000 (500)	Falha inesperada: contate o suporte com o X-Request-Id
Genérico	TED-9002 (503), TED-9003 (413), TED-9004 (outros 4xx, como 405 e 415)	Uma recusa sem código específico, identificada pelo status. Por exemplo, TED-9002 quando a trilha de auditoria não consegue registrar uma mudança de política

Em um envio, TED-0031, TED-1001, TED-1010, 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.