> ## 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, tenant e conta — limites, políticas de taxas e horários operacionais ajustáveis em tempo de execução.

A configuração do plugin Bank Transfer acontece em três níveis. A maioria das decisões de negócio pode ser alterada em tempo de execução sem reiniciar o serviço.

É importante distinguir entre **identidade do tenant** e **escopo da organização Midaz**, pois eles cumprem propósitos diferentes.

O tenant é resolvido a partir do contexto da requisição autenticada, através da claim JWT `tenantId`. Ele é responsável pelo isolamento em nível de infraestrutura, incluindo a resolução de banco de dados da plataforma de multi-tenancy e o acesso a secretos com escopo de tenant.

O header `X-Organization-Id` define o escopo da organização Midaz dentro desse tenant. Ele é obrigatório em todas as rotas de transferência com escopo de organização, independentemente do modo de deployment. Requisições que omitem esse header ou fornecem um valor que não seja um UUID válido retornam uma resposta `400`.

Processos em segundo plano, como o poller de TED IN e os workers de reconciliação, não recebem headers de requisição. Em deployments single-tenant, esses processos usam a variável de ambiente `ORGANIZATION_ID` como contexto de organização.

## Níveis de configuração

***

A configuração do plugin Bank Transfer é dividida em três níveis:

* **Configuração de infraestrutura** (gerenciada pelo DevOps) controla URLs, credenciais, configurações de autenticação e timeouts. As alterações requerem reinicialização do serviço.
* **Configurações do tenant** (gerenciadas pelo time de produto via Admin API) controlam limites de transferência, políticas de tarifas e sobrescritas de horário de funcionamento. As alterações entram em vigor sem reiniciar o serviço.
* **Configurações de conta** (gerenciadas pelo time de produto via Admin API) controlam limites e restrições para contas individuais. As alterações entram em vigor sem reiniciar o serviço.

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

***

Estas são as configurações que GPMs e times de produto se importam. Todas são gerenciadas via Admin API em tempo de execução — sem necessidade de deploy.

### Limites de transferência

Defina tetos de volume diário e mensal em dois níveis:

* **Por organização** — aplica-se às transferências de uma organização Midaz dentro do tenant resolvido
* **Por conta** — aplica-se a uma conta específica do usuário final (sobrescreve os padrões da organização)

Os limites cobrem tanto o valor total quanto o número de transações. Defina-os para gerenciar riscos e atender aos requisitos do BACEN.

### Política de tarifas

Controle se o plugin cobra tarifa em transferências TED OUT, TED IN e P2P. As regras de tarifa são definidas no Fees Engine e aplicadas por organização. Consulte [Fees Engine](/pt/midaz/fees/fees-engine-overview) para detalhes de configuração.

### Fail-open vs. fail-closed

Se o serviço de cálculo de tarifas estiver indisponível no momento de uma transferência, você tem duas opções:

* **Fail-open** — permite que a transferência prossiga sem cobrar tarifa
* **Fail-closed** — bloqueia a transferência até que o serviço de tarifas esteja disponível novamente

A política padrão do serviço de tarifas é **fail-open** (`FEES_FAIL_CLOSED_DEFAULT=false`). Altere isso por organização via Admin API quando precisar que indisponibilidades do serviço de tarifas bloqueiem as transferências. O TED IN tem seu próprio interruptor de segurança, `BTF_FEES_TED_IN_FAIL_OPEN`, que é `true` por padrão para que os fundos recebidos sejam creditados com tarifa=0 se o plugin-fees estiver indisponível.

### Recebimento de TED IN

Transferências recebidas estão **desabilitadas por padrão**. Habilite o TED IN por organização assim que suas credenciais JD SPB estiverem configuradas e o worker de polling estiver ativo.

### Sobrescritas de horários de funcionamento

O plugin aplica a janela de funcionamento do TED do BACEN por padrão. Você pode configurar janelas personalizadas por política de tenant — por exemplo, restringindo transferências apenas ao horário comercial — dentro dos limites do BACEN.

## Configuração de infraestrutura

***

As variáveis de ambiente definidas no deploy (URLs, credenciais, TLS, persistência, integrações, chaves de segurança) são definidas pelo DevOps e requerem reinicialização do serviço. Consulte a referência completa em [Variáveis de ambiente](/pt/rails/ted/jd/ted-environment-variables).

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

***

As configurações de nível de tenant e de conta são gerenciadas via Admin API — sem necessidade de reinicialização. As alterações entram em vigor imediatamente (sujeito ao TTL do cache para configurações de tenant).

As configurações disponíveis incluem:

* Limites de transferência (diário e mensal, por organização e por conta)
* Comportamento de tarifas (fail-open ou fail-closed quando o serviço de tarifas está indisponível)
* Recebimento de TED IN (habilitado ou desabilitado por organização)
* Sobrescritas de horários de funcionamento (janelas personalizadas dentro dos limites do BACEN)

Consulte a referência da Admin API para a lista completa de campos configuráveis e o formato das requisições.

### Configurações gerenciadas pelo systemplane

As configurações abaixo são gerenciadas em tempo de execução através do systemplane (Admin API), não no momento do deploy. Cada uma tem um nome de variável de ambiente correspondente que ainda existe na base de código, mas o carregador de configuração **ignora** essas variáveis de ambiente e emite um WARN de depreciação se elas forem definidas — atribuí-las via ambiente não tem efeito. Use o systemplane para alterá-las.

| Área                            | Configurações                                                                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 wildcard `*` 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`, `BTF_FEES_TED_IN_FAIL_OPEN`                                                                               |
| Limites de uso                  | `USAGE_LIMITS_ENABLED`, `USAGE_LIMIT_DAILY_CENTS`, `USAGE_LIMIT_MONTHLY_CENTS`                                                                                                                 |
| Horários de funcionamento       | `TRANSFER_OPERATING_OPEN`, `TRANSFER_OPERATING_CLOSE`, `TRANSFER_OPERATING_TIMEZONE`                                                                                                           |
| Idempotência / duplicate guard  | `IDEMPOTENCY_REQUIRE_REDIS`, `DUPLICATE_GUARD_TTL_SEC`                                                                                                                                         |
| Roteamento                      | `ROUTING_*` (todas as configurações de regra de roteamento)                                                                                                                                    |
| Tuning de timeout & retry do JD | `JD_TIMEOUT_MS`, `JD_MAX_RETRIES`, `JD_VALIDATE_EXTERNAL_SIGNATURE`                                                                                                                            |
| Tuning de polling do JD         | `JD_POLL_MAX_MESSAGES_PER_CYCLE`, `JD_POLL_RECOVERY_BATCH_SIZE`, `JD_POLL_DISABLE_OPERATING_HOURS_WINDOW`                                                                                      |
| Tuning de reconciliação         | `BTF_RECONCILIATION_BATCH_SIZE`, `BTF_RECONCILIATION_MAX_ATTEMPTS`, `BTF_RECONCILIATION_STALE_AFTER_SEC`, `BTF_RECONCILIATION_TICK_DEADLINE_SECONDS`, `RECONCILIATION_PENDING_ALERT_THRESHOLD` |
| Tuning de publicação RabbitMQ   | `RABBITMQ_MAX_RETRIES`, `RABBITMQ_PUBLISH_TIMEOUT_MS`, `RABBITMQ_RETRY_BACKOFF_MS`, `RABBITMQ_ROUTING_KEY_PREFIX`                                                                              |
| Tuning de entrega de webhooks   | `WEBHOOK_TIMEOUT_MS`, `WEBHOOK_MAX_RETRIES`, `WEBHOOK_RETRY_BACKOFF_MS`, `WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS`, `WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC`                                    |

<Note>
  Definir qualquer um dos nomes acima via ambiente não tem efeito e é registrado em WARN como depreciado. Eles existem apenas como gêmeos de ambiente depreciados de configurações gerenciadas em runtime/systemplane.
</Note>

<Warning>
  Quando o CORS não está configurado, a origem permitida padrão é o wildcard `*` — qualquer origem pode chamar a API — e isso não é validado na inicialização. Em produção, defina origens explícitas pela chave de systemplane `cors.allowed_origins` em vez de deixar o wildcard.
</Warning>