> ## 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.
# Como o plugin funciona
> Entenda como o plugin Bank Transfer lida com a comunicação SPB, cálculo de tarifas, liquidação e webhooks em todo o ciclo de vida da transferência.
O plugin Bank Transfer é 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
* 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
Endpoint: [POST /v1/transfers/initiate](/pt/reference/midaz/plugins/ted/initiate-transfer)
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.
O plugin calcula a tarifa e retorna um `initiationId` com os valores calculados.
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](/pt/reference/midaz/plugins/ted/process-transfer)
Seu sistema chama o plugin com o `initiationId` para confirmar.
O plugin verifica os limites diários e mensais e confere o saldo disponível.
O plugin reserva fundos no Midaz (hold) e envia a mensagem assinada para a JD Consultores.
A JD encaminha a transferência para o banco de destino via rede SPB.
O plugin recebe a confirmação de liquidação da JD e finaliza os registros.
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 60 segundos (padrão) 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
***
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 modo `saas`, 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ório `X-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`.
Consulte [Configuração do TED](/pt/rails/ted/jd/ted-configuration) para a lista completa de variáveis de ambiente suportadas.
## 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](/pt/rails/ted/jd/ted-data-model) 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.
### Detecção de duplicatas
O plugin gera um fingerprint de detecção de duplicatas a partir de `senderAccountId`, 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. O `tenantId` é 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.
### Observabilidade
O plugin expõe métricas Prometheus, logs JSON estruturados e traces OpenTelemetry. Probes de liveness e readiness sem autenticação estão disponíveis para a orquestração do Kubernetes. Estes são principalmente relevantes para deployments BYOC.
Os probes de liveness e readiness não requerem autenticação por design (para compatibilidade com probes K8s). Em deployments BYOC, restrinja o acesso a esses probes 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.