> ## 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 trata a comunicação com o SPB, o cálculo de tarifas, a liquidação e as notificações por webhook em todo o ciclo de vida da transferência.
O plugin Bank Transfer opera o trilho TED do Brasil pela JD Consultores. A JD fornece a conectividade regulada com o SPB. O plugin conduz cada transferência do cálculo da tarifa até a confirmação da liquidação, então o seu time não chama a JD diretamente.
## O que o plugin resolve para você
***
* Envia TEDs de saída para qualquer banco brasileiro (TED OUT)
* Recebe e credita os TEDs de entrada (TED IN)
* Processa transferências internas instantâneas entre contas (P2P)
* Calcula e aplica as tarifas antes de o cliente confirmar
* Detecta e bloqueia transferências duplicadas dentro de uma janela configurável
* Valida os dias úteis do BACEN contra o calendário `bacen_holidays` (carga estática para 2026–2028, atualizador ANBIMA ao vivo pendente)
* Assina as mensagens com o certificado digital da sua instituição, como o BACEN exige
* Repete automaticamente as operações que falham
* Avisa o seu sistema por webhooks quando uma transferência muda de status
## Como funciona o TED OUT
***
O TED OUT é um fluxo de confirmação prévia. O cliente revisa a tarifa antes de o plugin enviar a transferência.
### Etapa 1: Iniciar
Endpoint: [POST /v1/transfers/initiate](/pt/reference/interfaces/ted-jd/initiate-transfer)
O seu sistema chama o plugin com os dados da transferência: valor, destinatário e conta do remetente.
O plugin valida a conta do remetente, verifica o horário de funcionamento e roda a detecção de duplicidade.
O plugin calcula a tarifa e retorna um `initiationId` com os valores calculados.
O seu sistema mostra a tarifa ao cliente para confirmação.
A iniciação vale por 24 horas. Se o cliente não confirmar dentro dessa janela, ela expira.
### Etapa 2: Preparar a assinatura (opcional)
Endpoint: [POST /v1/transfers/signing/prepare](/pt/reference/interfaces/ted-jd/prepare-transfer-signing)
Use esta etapa apenas quando o seu tenant assina fora do plugin (modo de assinatura externa). O plugin congela o payload canônico do STR0008 e retorna os bytes exatos e o hash a assinar. O seu sistema assina o payload e passa a assinatura para a etapa de processamento. Quando o plugin assina com a sua chave local (o padrão), pule esta etapa.
### Etapa 3: Processar
Endpoint: [POST /v1/transfers/process](/pt/reference/interfaces/ted-jd/process-transfer)
O seu sistema chama o plugin com o `initiationId` para confirmar.
O plugin verifica os limites diário e mensal e o saldo disponível.
O plugin reserva os fundos no Midaz (uma retenção) e envia a mensagem assinada para a JD Consultores.
A JD roteia a transferência até o banco de destino pela rede do SPB.
O plugin recebe a confirmação de liquidação da JD e finaliza os registros.
O seu sistema recebe um webhook com o status final.
## Como funciona o TED IN
***
1. Um banco externo envia um TED para a sua instituição pela JD Consultores.
2. O plugin consulta a JD a cada 60 segundos (padrão) para detectar novas transferências de entrada.
3. O plugin valida o destinatário no CRM para achar a conta correta.
4. O plugin credita a conta no Midaz e cria um registro de transferência concluída.
5. O seu sistema recebe um webhook que confirma o crédito.
O polling do TED IN vem desligado por padrão. Para ligá-lo, defina `JD_POLLING_ENABLED` depois de configurar as credenciais da JD e o worker de polling.
## Como funciona o P2P
***
As transferências P2P movem fundos entre duas contas da mesma organização. Elas não usam a rede do SPB, e a liquidação é instantânea.
1. O 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 houver configuração, e a mostra para confirmação.
3. Depois da confirmação, o plugin roda a transferência no Midaz.
4. As duas contas são atualizadas na hora, e o seu sistema recebe um webhook.
## Modelos de deploy
***
O plugin TED aceita dois modelos de deploy. A variável de ambiente `DEPLOYMENT_MODE` seleciona o modelo.
### SaaS (gerenciado pela Lerian)
Em deploys SaaS, a Lerian gerencia a integração com a JD Consultores, incluindo a manutenção de credenciais e certificados. O seu time configura apenas as definições de negócio pela Admin API, como limites de transação, tarifas e webhooks. Você não gerencia infraestrutura nem conexões.
No modo `saas`, o plugin roda como um serviço multi-tenant. O serviço de plataforma de multi-tenancy resolve a identidade do tenant, as credenciais da JD, os segredos de webhook e as definições selecionadas em tempo de execução. Esse modo exige as variáveis `MULTI_TENANT_*` e `AWS_REGION`, e o plugin as usa ativamente.
### BYOC (traga suas próprias credenciais)
Em deploys BYOC, a sua instituição fornece as credenciais da JD Consultores e a chave privada RSA que assina as mensagens. O seu time de DevOps define esses valores por variáveis de ambiente. Você mantém o controle total da conexão com a JD, e o plugin roda inteiramente na sua própria infraestrutura.
O BYOC é o modelo de deploy padrão (`byoc`). O plugin carrega toda a configuração a partir de variáveis de ambiente na inicialização, incluindo as credenciais da JD, os segredos de webhook e as definições de tarifa.
### Resolução da organização
O plugin identifica a organização no Midaz pelo header obrigatório `X-Organization-Id` nas rotas de API com escopo de organização.
Alguns processos em segundo plano não recebem headers de requisição, como o poller do TED IN e os workers de conciliação. Para eles, o plugin recorre à variável de ambiente `ORGANIZATION_ID`.
No modo `byoc`, o plugin ignora as variáveis de multi-tenancy (`MULTI_TENANT_*`) e `AWS_REGION`.
Veja [Configuração do TED](/pt/interfaces/ted-jd/ted-configuration) para a lista completa de variáveis de ambiente aceitas.
## Integração com o Midaz
***
Todas as movimentações financeiras passam pelo ledger do Midaz. O plugin cria uma transação no Midaz para cada transferência:
* **TED OUT**: o plugin retém os fundos na etapa de processamento (por `pending: true`) e depois os debita quando a JD confirma a liquidação.
* **TED IN**: o plugin credita os fundos depois que a JD valida e confirma a transferência.
* **P2P**: uma única transação no Midaz debita o remetente e credita o destinatário de forma atômica.
Cada transferência corresponde a um registro de transação no seu ledger do Midaz. Veja [Dados e relatórios do TED](/pt/interfaces/ted-jd/ted-data-model) para os campos disponíveis para conciliação.
## Para desenvolvedores
***
### Arquitetura
O plugin usa uma arquitetura Hexagonal (Ports and Adapters) com CQRS. Esse desenho mantém a lógica de negócio separada da infraestrutura. Você pode adicionar um novo adaptador, como um provedor de SPB diferente, sem mudar o comportamento central.
### Detecção de duplicidade
O plugin monta um fingerprint de detecção de duplicidade para cada transferência. O fingerprint cobre `senderAccountId`, os dados do destinatário (ISPB, agência, conta, documento do titular), o valor e a finalidade. O plugin guarda o fingerprint no Redis com um TTL configurável (padrão de 300 segundos, definido por `DUPLICATE_GUARD_TTL_SEC`).
A organização não faz parte do fingerprint. O isolamento entre tenants vem do prefixo da chave no Redis. O plugin rejeita uma requisição duplicada dentro da janela com `409 Conflict` e o código de erro `BTF-0012`.
### Isolamento de dados multi-tenant
O isolamento entre tenants vem da resolução de banco de dados por tenant na plataforma de multi-tenancy. O plugin lê o `tenantId` da claim do JWT ou do contexto autenticado, nunca do `X-Organization-Id`. O cache do Redis usa prefixos de chave por tenant (`tenant:{tenantId}:{key}`). As tabelas de negócio usam os campos de organização do Midaz apenas para 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. Ele também expõe probes de liveness e de readiness sem autenticação para a orquestração no Kubernetes. Esses probes importam principalmente em deploys BYOC.
Os probes de liveness e de readiness ficam sem autenticação por desenho, para compatibilidade com os probes do K8s. Em deploys BYOC, restrinja o acesso a esses probes no nível de rede, por exemplo com regras de ingress ou security groups. Isso mantém o status das dependências internas fora da internet pública.