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
- Valida dias úteis do BACEN contra o calendário
bacen_holidays(seed estática para 2026–2028; o refresher em tempo real da ANBIMA está pendente) - 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
Seu sistema chama o plugin com os detalhes da transferência (valor, destinatário, conta do remetente).
O plugin valida a conta do remetente, verifica os horários de funcionamento e executa a detecção de duplicatas.
Etapa 2 — Processar
Como o TED IN funciona
- Um banco externo envia um TED para sua instituição via JD Consultores.
- O plugin consulta a JD a cada 60 segundos (padrão) para detectar novas transferências recebidas.
- O plugin valida o destinatário no CRM para encontrar a conta correta.
- O plugin credita a conta no Midaz e cria um registro de transferência concluída.
- 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.
- Seu sistema chama o plugin com a conta do remetente, a conta do destinatário e o valor.
- O plugin calcula a tarifa (se configurada) e a apresenta para confirmação.
- Após a confirmação, o plugin executa a transferência no Midaz.
- Ambas as contas são atualizadas imediatamente. Seu sistema recebe um webhook.
Modelos de deployment
O plugin TED suporta dois modelos de deployment, definidos por meio da variável de ambiente
DEPLOYMENT_MODE.
SaaS (gerenciado pela Lerian)
Nos deployments SaaS, a Lerian gerencia a integração com a JD Consultores, incluindo o gerenciamento de credenciais e a manutenção de certificados. Sua equipe só precisa configurar as definições em nível de negócio, como limites de transação, tarifas e webhooks, via Admin API. Nenhum gerenciamento de infraestrutura ou de conexões é necessário. Ao executar no modosaas, o plugin opera como um serviço multi-tenant. A identidade do tenant, as credenciais JD, os segredos de webhook e determinadas definições de configuração são resolvidos dinamicamente por meio do serviço da plataforma de multi-tenancy. Nesse modo, as variáveis MULTI_TENANT_* e AWS_REGION são obrigatórias e ativamente utilizadas pelo plugin.
BYOC (traga suas próprias credenciais)
Nos deployments BYOC, sua instituição é responsável por fornecer as credenciais da JD Consultores e a chave privada RSA usada para assinar as mensagens. Esses valores são configurados pela sua equipe de DevOps por meio de variáveis de ambiente, o que lhe dá controle total sobre a conexão com a JD e permite que o plugin seja executado inteiramente dentro da sua própria infraestrutura. Este é o modo de deployment padrão (byoc). Toda a configuração — incluindo credenciais JD, segredos de webhook e definições relacionadas a tarifas — é carregada de variáveis de ambiente durante o boot da aplicação.
Resolução de organização
Nos deployments single-tenant, a organização Midaz é identificada por meio do header obrigatórioX-Organization-Id nas rotas de API com escopo de organização.
Para os processos em segundo plano que não recebem headers de requisição, como o poller de TED IN e os workers de reconciliação, o plugin recorre à variável de ambiente ORGANIZATION_ID.
As variáveis relacionadas a multi-tenancy (
MULTI_TENANT_*) e AWS_REGION são ignoradas quando o plugin é executado no modo byoc.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.
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.
Detecção de duplicatas
O plugin gera um fingerprint de detecção de duplicatas a partir desenderAccountId, dos dados do destinatário (ISPB, agência, conta, documento do titular), do valor e da finalidade, e o armazena no Redis com um TTL configurável (padrão: 300 segundos via DUPLICATE_GUARD_TTL_SEC). A organização não faz parte do fingerprint; o isolamento de tenant vem do prefixo da chave Redis. Requisições duplicadas dentro da janela são rejeitadas com 409 Conflict e código de erro BTF-0012.
Isolamento de dados multi-tenant
O isolamento de tenant vem da resolução de banco de dados da plataforma de multi-tenancy. OtenantId é extraído do claim JWT ou do contexto autenticado e nunca é fornecido através de X-Organization-Id. O cache Redis usa prefixos de chave por tenant (tenant:{tenantId}:{key}), e as tabelas de negócio usam os campos de organização Midaz apenas para a autorização de escopo de negócio dentro do tenant resolvido.