> ## 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.

Quando outro motor de core bancário da sua instituição usa o mesmo canal JD e o mesmo ISPB, o [JD Courier](https://docs.lerian.studio/pt/interfaces/jd-courier/what-is-jd-courier.md) compartilha o canal entre os motores.

## 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)
* Envia TEDs para o outro core da sua instituição, e recebe os TEDs dele, pelo JD Courier ([TED entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md))
* Detecta e bloqueia transferências duplicadas dentro de uma janela configurável
* Valida os dias úteis do BACEN contra o próprio calendário de feriados embutido, de 2026 a 2028
* Assina as mensagens com o certificado digital da sua instituição, como o BACEN exige
* Concilia com a JD as transferências cujo resultado é desconhecido
* 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

> [!TIP]
>
> Endpoint: [POST /v1/transfers/initiate](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/initiate-transfer.md)

**Step 1**

O seu sistema chama o plugin com os dados da transferência: valor, destinatário e conta do remetente.

**Step 2**

O plugin valida a conta do remetente, verifica o horário de funcionamento e roda a detecção de duplicidade.

**Step 3**

O plugin calcula a tarifa e retorna um `initiationId` com os valores calculados.

**Step 4**

O seu sistema mostra a tarifa ao cliente para confirmação.

Uma iniciação de TED OUT vale até o fechamento da janela de operação daquele dia. Se o cliente não a confirmar a tempo, ela expira.

### Etapa 2: Preparar a assinatura (opcional)

> [!TIP]
>
> Endpoint: [POST /v1/transfers/signing/prepare](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/prepare-transfer-signing.md)

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

> [!TIP]
>
> Endpoint: [POST /v1/transfers/process](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/process-transfer.md)

**Step 1**

O seu sistema chama o plugin com o `initiationId` para confirmar.

**Step 2**

O plugin verifica os limites diário e mensal e o saldo disponível.

**Step 3**

O plugin reserva os fundos no Midaz (uma retenção) e envia a mensagem assinada para a JD Consultores.

**Step 4**

A JD roteia a transferência até o banco de destino pela rede do SPB.

**Step 5**

O plugin recebe a confirmação de liquidação da JD e finaliza os registros.

**Step 6**

O seu sistema lê o status final com [Get Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer.md). Veja [Webhooks](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-webhooks.md) para os eventos do TED OUT.

## 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.

> [!NOTE]
>
> 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 e do mesmo ledger do Midaz. Elas não usam a rede do SPB, e a liquidação é instantânea. O [P2P entre dois ledgers](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-p2p.md#transfers-between-ledgers) vem desligado por padrão.

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 roda em dois modelos de deploy. A variável de ambiente `DEPLOYMENT_MODE` (`byoc` por padrão, ou `saas`) indica o modelo. No modo `saas`, o plugin se recusa a iniciar a menos que PostgreSQL, Redis, MongoDB, RabbitMQ e o broker de streaming usem TLS.

### 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.

### BYOC (traga sua própria nuvem)

Em deploys BYOC, o plugin roda na sua própria infraestrutura. A sua instituição fornece as credenciais da JD Consultores e a chave privada RSA que assina as mensagens, e o seu time de DevOps as define por variáveis de ambiente. Você mantém o controle total da conexão com a JD.

### 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. Esses processos usam a variável de ambiente `ORGANIZATION_ID`.

Veja [Configuração do TED](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md) 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 quando o TED de entrada chega da JD.
* **P2P**: o plugin debita o remetente e credita o destinatário de forma atômica no Midaz.

Cada transferência registra a transação dela no Midaz em `midazTransactionId`. Um chargeback de TED IN adiciona uma transação compensatória que carrega o mesmo ID de transferência. Veja [Dados e relatórios do TED](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-data-model.md) 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.

![Padrão arquitetural do TED](https://mintcdn.com/lerian-49cb71fc/acz_224gNiM7aYvL/images/pt/d2/ted-architectural-pattern.svg?fit=max\&auto=format\&n=acz_224gNiM7aYvL\&q=85\&s=2f911534c0af748790b4f3eb2990a085)

### 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 por 300 segundos por padrão (chave do systemplane `idempotency.duplicate_guard_ttl_seconds`).

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 por tenant

A Lerian isola os dados de cada tenant. 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. 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.

### Observabilidade

O plugin escreve logs JSON estruturados, pode exportar traces e métricas OpenTelemetry e pode servir métricas Prometheus. 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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.