Pular para o conteúdo principal
O plugin TED é um serviço autocontido que gerencia toda a comunicação com a rede SPB do Brasil (via JD Consultores). Ele administra o ciclo de vida completo da transferência — do cálculo de tarifas à confirmação de liquidação — para que seu time não precise interagir diretamente com a JD.

​
O que o plugin gerencia para você

  • Envia TEDs de saída para qualquer banco brasileiro (TED OUT)
  • Recebe e credita TEDs recebidos automaticamente (TED IN)
  • Processa transferências internas instantâneas entre contas (P2P)
  • Calcula e aplica tarifas automaticamente antes do cliente confirmar
  • Detecta e previne transferências duplicadas dentro de uma janela configurável
  • Assina mensagens com o certificado digital da sua instituição, conforme exigência do BACEN
  • Refaz operações com falha automaticamente
  • Notifica seu sistema via webhooks em tempo real a cada mudança de status

​
Como o TED OUT funciona

O TED OUT usa um fluxo de duas etapas para que o cliente possa revisar a tarifa antes de confirmar.

​
Etapa 1 — Iniciar

Endpoint: POST /v1/transfers/initiate
1
Seu sistema chama o plugin com os detalhes da transferência (valor, destinatário, conta do remetente).
2
O plugin valida a conta do remetente, verifica os horários de funcionamento e executa a detecção de duplicatas.
3
O plugin calcula a tarifa e retorna um initiationId com os valores calculados.
4
Seu sistema exibe a tarifa ao cliente para confirmação.
A iniciação é válida por 24 horas. Se o cliente não confirmar dentro dessa janela, ela expira automaticamente.

​
Etapa 2 — Processar

Endpoint: POST /v1/transfers/process
1
Seu sistema chama o plugin com o initiationId para confirmar.
2
O plugin verifica os limites diários e mensais e confere o saldo disponível.
3
O plugin reserva fundos no Midaz (hold) e envia a mensagem assinada para a JD Consultores.
4
A JD encaminha a transferência para o banco de destino via rede SPB.
5
O plugin recebe a confirmação de liquidação da JD e finaliza os registros.
6
Seu sistema recebe um webhook com o status final.

​
Como o TED IN funciona

  1. Um banco externo envia um TED para sua instituição via JD Consultores.
  2. O plugin consulta a JD a cada 30 segundos para detectar novas transferências recebidas.
  3. O plugin valida o destinatário no CRM para encontrar a conta correta.
  4. O plugin credita a conta no Midaz e cria um registro de transferência concluída.
  5. Seu sistema recebe um webhook confirmando o crédito.
O recebimento de TED IN está desabilitado por padrão. Habilite-o por organização via Admin API assim que suas credenciais JD e o worker de polling estiverem configurados.

​
Como o P2P funciona

Transferências P2P movem fundos entre duas contas dentro da mesma organização, sem passar pela rede SPB. A liquidação é instantânea.
  1. Seu sistema chama o plugin com a conta do remetente, a conta do destinatário e o valor.
  2. O plugin calcula a tarifa (se configurada) e a apresenta para confirmação.
  3. Após a confirmação, o plugin executa a transferência no Midaz.
  4. Ambas as contas são atualizadas imediatamente. Seu sistema recebe um webhook.

​
Modelos de deployment

SaaS (gerenciado pela Lerian) A Lerian mantém a conexão com a JD Consultores e o certificado. Você configura as definições da sua organização — limites, tarifas, webhooks — via Admin API. Nenhum trabalho de infraestrutura é necessário. BYOC (traga suas próprias credenciais) Sua instituição fornece as credenciais da JD Consultores e a chave privada RSA para assinatura de mensagens. O DevOps configura isso via variáveis de ambiente. Você tem controle total sobre a conexão com a JD e pode executar o plugin na sua própria infraestrutura. Consulte Configuração do TED para a lista completa de variáveis de ambiente.

​
Integração com o Midaz

Todas as movimentações financeiras passam pelo ledger do Midaz. O plugin cria transações no Midaz para cada transferência:
  • TED OUT — os fundos são retidos quando a transferência é confirmada (etapa de processo, via pending: true), depois debitados na confirmação de liquidação.
  • TED IN — os fundos são creditados após a transferência ser validada e confirmada pela JD.
  • P2P — uma única transação Midaz debita o remetente e credita o destinatário atomicamente.
Isso significa que cada transferência é totalmente refletida no seu ledger Midaz com um registro de transação correspondente. Consulte Dados e relatórios do TED para os campos disponíveis para reconciliação.

​
Para desenvolvedores

​
Arquitetura

O plugin usa a arquitetura Hexagonal (Portas e Adaptadores) combinada com CQRS. A lógica de negócio é isolada da infraestrutura, tornando simples adicionar novos adaptadores (ex: um provedor SPB diferente) sem alterar o comportamento central.
Ted Architectural Pattern

​
Detecção de duplicatas

O plugin gera uma chave de idempotência a partir de SHA256(organizationId + senderAccountId + recipient + amount) e a armazena no Redis com um TTL configurável (padrão: 60 segundos). Requisições duplicadas dentro da janela são rejeitadas com 409 Conflict e código de erro BTF-0012.

​
Isolamento de dados multi-tenant

Todas as consultas ao banco de dados são filtradas por organization_id. O cache Redis usa prefixos de chave por tenant (tenant:{tenantId}:{key}) para evitar vazamento de dados entre organizações. O tenantId é extraído do claim JWT e validado contra o cabeçalho HTTP X-Tenant-Id em cada requisição.

​
Observabilidade

O plugin expõe métricas Prometheus, logs JSON estruturados e traces OpenTelemetry. Endpoints de saúde (GET /health/live, GET /health/ready) estão disponíveis sem autenticação para probes de liveness e readiness do Kubernetes. Estes são principalmente relevantes para deployments BYOC.
Os endpoints de saúde não requerem autenticação por design (para compatibilidade com probes K8s). Em deployments BYOC, restrinja o acesso a estes endpoints no nível de rede (por exemplo, via regras de ingress ou security groups) para evitar expor o status de dependências internas à internet pública.