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

# Configuração

> Configure o Bank Transfer nos níveis de infraestrutura e tenant, com limites, políticas de tarifas, horário de funcionamento e roteamento do ledger ajustáveis em tempo de execução.

O plugin Bank Transfer divide a configuração em dois níveis. Você pode mudar a maioria das configurações de negócio em tempo de execução, sem reiniciar o serviço.

A identidade do tenant e o escopo da organização Midaz servem a propósitos diferentes. Mantenha os dois distintos.

Na Lerian Cloud, a claim JWT `tenantId` no contexto da requisição autenticada identifica o seu tenant, e a Lerian isola os seus dados.

O header `X-Organization-Id` define o escopo da organização Midaz dentro desse tenant. Cada rota de transferência com escopo de organização exige este header, em todos os modos de deploy. Uma requisição retorna `400` se omitir o header ou enviar um valor que não seja um UUID válido.

## Níveis de configuração

***

O plugin Bank Transfer tem dois níveis de configuração:

* **Configuração de infraestrutura** (o DevOps gerencia) controla URLs, credenciais, configurações de autenticação e timeouts. As mudanças precisam de reinício do serviço.
* **Configurações em tempo de execução** (gerenciadas pela Admin API) controlam limites de transferência, políticas de tarifas, horário de funcionamento e roteamento do ledger. As configurações do namespace `tenant_policy` se aplicam a um tenant. As configurações do namespace `runtime_config` se aplicam ao deploy inteiro. As mudanças entram em vigor sem reinício do serviço.

## Decisões de negócio que você pode configurar

***

GPMs e times de produto se importam com estas configurações. Você as gerencia pela Admin API em tempo de execução, sem deploy, exceto as variáveis de deploy como `MIDAZ_FEE_MODE`, que mudam apenas com um reinício.

### Limites de transferência

Defina tetos diários e mensais de valor por tenant com `usage_limits.enabled`, `usage_limits.daily_limit_cents` e `usage_limits.monthly_limit_cents`. O plugin aplica os tetos a cada conta do remetente, sobre o valor debitado do remetente (`totalAmount`), quando processa uma transferência TED OUT, P2P ou TED entre cores. O dia e o mês reiniciam às 00:00 UTC. Uma transferência acima de um teto é recusada com `422 BTF-0011`.

### Política de tarifas

A variável de deploy `MIDAZ_FEE_MODE` decide quem calcula e cobra a tarifa de cada transferência TED OUT, TED IN, P2P e TED entre cores:

* **`legacy`**: o plugin-fees calcula a tarifa a partir dos próprios pacotes. O `BTF_FEE_ENABLED` liga o plugin-fees. Com `false`, o padrão, o plugin não chama o plugin-fees, e cada transferência roda com tarifa 0.
* **`native`**: o [Fees Engine](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-overview.md) do Midaz 4.1.0 ou posterior calcula e cobra a tarifa a partir dos pacotes de tarifas do ledger. O `BTF_FEE_ENABLED` não liga nem desliga essa tarifa. Para parar uma tarifa, desabilite o pacote dela no Midaz com `enable: false`, ou exclua o pacote.
* **`auto`** (padrão): `native` no Midaz 4.1.0 ou posterior, e `legacy` em uma versão anterior ou quando a primeira leitura da versão falha.

> [!WARNING]
>
> Com `auto`, uma atualização do Midaz para a 4.1.0 ou posterior passa o Bank Transfer para `native` sozinho. Se seus pacotes de tarifas ainda estão no plugin-fees, o Midaz não encontra nenhum pacote, e as transferências novas ficam sem tarifa. Defina `MIDAZ_FEE_MODE=legacy` antes de atualizar o Midaz e depois siga [Migrar as tarifas do Bank Transfer para o Midaz](https://docs.lerian.studio/pt/products/midaz/fees/fees-migration-guide.md).

No modo `native`, uma iniciação pode levar um rótulo de tarifa opcional em `feeContext`: uma letra minúscula, seguida de até 49 letras minúsculas, dígitos ou sublinhados. Um pacote de tarifas no ledger do pagador seleciona por ele. O plugin verifica o rótulo uma vez, na iniciação. Ele recusa a iniciação com `422 BTF-0008` quando nenhum pacote de tarifas no ledger do pagador seleciona pelo rótulo, habilitado ou não, ou quando o ledger não calcula tarifas de forma nativa. Os lançamentos da transferência no ledger levam o rótulo, e [Get Transfer](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/retrieve-transfer.md) o retorna.

### Fail-open vs. fail-closed

No modo `legacy`, a política de tenant `fees.fail_closed_default` (padrão `false`) decide o que uma falha do plugin-fees faz:

* **TED OUT e P2P**: quando o plugin-fees está indisponível, a transferência segue sem tarifa (fail-open). Com `true`, o plugin recusa a transferência (fail-closed). Uma tarifa que o plugin-fees recusa sempre recusa a transferência.
* **TED IN**: qualquer falha de tarifa credita os fundos com tarifa 0. Com `true`, o plugin não credita e devolve a transferência ao banco de origem.

### Recebimento de TED IN

O polling de TED IN fica desligado por padrão. O DevOps o liga para o deploy com `JD_POLLING_ENABLED=true`, depois que as credenciais JD SPB estiverem configuradas.

Quando o plugin não encontra o destinatário de um TED IN, a política de tenant `jd_polling.auto_return_authorized` (padrão `false`) decide se ele devolve os fundos ao banco de origem ou retém a mensagem para um operador. Veja [Receber (TED IN)](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-in.md#what-happens-when-a-recipient-isnt-found).

### Horário de funcionamento

Cada tenant tem uma janela de TED OUT: `operating_hours.window` (`HH:MM-HH:MM`, padrão `06:30-17:00`) no fuso de `operating_hours.timezone` (padrão `America/Sao_Paulo`). O plugin recusa um TED OUT fora da janela, nos fins de semana e nos feriados do BACEN com `422 BTF-0010`. A mesma janela vale para a [devolução de um TED IN](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-in.md#return-a-received-transfer), que também fecha no máximo às 13:00 em 24 de dezembro e no último dia útil do ano. O P2P ignora a janela.

### Roteamento do ledger

A política de tenant `routing.ledger_bindings` é um único documento JSON que vincula cada organização Midaz, ledger e tipo de transferência às suas rotas contábeis. Um vínculo ou nomeia as rotas de transação e de operação do Midaz a usar, ou define `mode: omit` para lançar sem rotas. Não existe fallback de um vínculo para outro. Sem um vínculo:

* TED OUT e P2P são recusados com `503 BTF-9015`. O erro nomeia a configuração ausente em `systemplaneKey` e a causa em `reason`.
* Um TED IN fica retido com o motivo `LEDGER_ROUTE_UNRESOLVED`. O plugin o credita assim que o vínculo existir.

Cada tipo de [crédito ao cliente](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-in.md#customer-credits) (`TED_IN_STR0005` a `TED_IN_STR0051`) precisa do próprio vínculo, separado de `TED_IN`. A devolução de um TED IN é lançada no vínculo de `TED_OUT` do ledger do TED IN.

Um [TED entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md) é lançado no vínculo de `CROSS_CORE_OUT`. Um crédito entre cores recebido do outro core é lançado em `CROSS_CORE_IN`, e a devolução de um TED entre cores que você enviou é lançada em `CROSS_CORE_RETURN_IN`.

Antes de mover tráfego, chame [Check Ledger Routing Readiness](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/check-ledger-routing-readiness.md). A resposta traz `ready: true` apenas quando cada organização, ledger e tipo de transferência em uso tem um vínculo, e cada rota nomeada existe no Midaz.

## Configuração de infraestrutura

***

O DevOps define as variáveis de ambiente do momento do deploy (URLs, credenciais, TLS, persistência, integrações, chaves de segurança). Essas variáveis exigem reinício do serviço. Veja a referência completa em [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-environment-variables.md).

## Configuração em tempo de execução (Admin API)

***

Você gerencia as configurações em tempo de execução pela Admin API em `/system/:namespace/:key`, sem reinício. As chaves de política de tenant ficam no namespace `tenant_policy`. As chaves do deploy inteiro ficam em `runtime_config`.

As configurações ajustáveis incluem:

* Limites de transferência (diários e mensais, por tenant)
* Comportamento de tarifa (`fees.fail_closed_default`, `fees.max_fee_amount_cents`, `fees.refund_on_devolucao`)
* Devoluções de TED IN quando o destinatário não é encontrado (`jd_polling.auto_return_authorized`)
* Horário de funcionamento (`operating_hours.window`, `operating_hours.timezone`)
* Roteamento do ledger (`routing.ledger_bindings`)
* P2P entre dois ledgers de uma organização (`p2p.cross_ledger_enabled`). Veja [Transferências entre ledgers](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-p2p.md#transfers-between-ledgers)
* Um ISPB que você compartilha com outro core da sua instituição (`onus.shared_ispb_gate_enabled`). Veja [Transferências entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md)

### Configurações gerenciadas pelo systemplane

O systemplane (Admin API) gerencia as configurações abaixo em tempo de execução, não no momento do deploy. O plugin ignora essas variáveis de ambiente: se você definir uma delas, ele registra o WARN `systemplane-managed environment variable is set and ignored`. Use o systemplane para mudá-las.

| Área | Configurações |
| - | - |
| Logs | `LOG_LEVEL` |
| Rate limiting | `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_EXPIRY_SEC` |
| CORS | `CORS_ALLOWED_ORIGINS`, `CORS_ALLOWED_METHODS`, `CORS_ALLOWED_HEADERS` (a origem padrão é o coringa `*` quando não configurada; não é validada na inicialização) |
| Política de tarifas | `FEES_FAIL_CLOSED_DEFAULT`, `FEES_MAX_FEE_AMOUNT_CENTS`, `FEES_REFUND_ON_DEVOLUCAO` |
| Limites de uso | `USAGE_LIMITS_ENABLED`, `USAGE_LIMIT_DAILY_CENTS`, `USAGE_LIMIT_MONTHLY_CENTS` |
| Horário de funcionamento | `TRANSFER_OPERATING_OPEN`, `TRANSFER_OPERATING_CLOSE`, `TRANSFER_OPERATING_TIMEZONE` (substituídas por `operating_hours.window` e `operating_hours.timezone`) |
| Idempotência / proteção contra duplicatas | `IDEMPOTENCY_REQUIRE_REDIS`, `DUPLICATE_GUARD_TTL_SEC` |
| Roteamento | `ROUTING_*` (os IDs de rota são substituídos por `routing.ledger_bindings`) |
| Ajuste de timeout e nova tentativa da JD | `JD_TIMEOUT_MS`, `JD_MAX_RETRIES`, `JD_VALIDATE_EXTERNAL_SIGNATURE` |
| Ajuste do polling da JD | `JD_POLL_MAX_MESSAGES_PER_CYCLE`, `JD_POLL_RECOVERY_BATCH_SIZE`, `JD_POLL_DISABLE_OPERATING_HOURS_WINDOW` |
| Ajuste da conciliação | `BTF_RECONCILIATION_BATCH_SIZE`, `BTF_RECONCILIATION_MAX_ATTEMPTS`, `BTF_RECONCILIATION_STALE_AFTER_SEC`, `BTF_RECONCILIATION_TICK_DEADLINE_SECONDS`, `RECONCILIATION_PENDING_ALERT_THRESHOLD` |
| Ajuste de publicação no RabbitMQ | `RABBITMQ_MAX_RETRIES`, `RABBITMQ_PUBLISH_TIMEOUT_MS`, `RABBITMQ_RETRY_BACKOFF_MS`, `RABBITMQ_ROUTING_KEY_PREFIX` |
| Ajuste de entrega de webhook | `WEBHOOK_TIMEOUT_MS`, `WEBHOOK_MAX_RETRIES`, `WEBHOOK_RETRY_BACKOFF_MS`, `WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS`, `WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC` |

> [!WARNING]
>
> Quando o CORS não está configurado, a origem permitida padrão é o coringa `*`. Qualquer origem pode então chamar a API, e o plugin não a valida na inicialização. Para produção, defina origens explícitas pela chave `cors.allowed_origins` do systemplane, em vez do coringa.


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