Configuração do Bank Transfer

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.

Níveis de configuração

Nível	Quem gerencia	O que controla	Requer reinicialização?
Infraestrutura (variáveis de env)	DevOps	URLs, credenciais, autenticação, timeouts	Sim
Configurações do tenant (Admin API)	Time de produto	Limites, política de tarifas, sobrescritas de horário	Não
Configurações de conta (Admin API)	Time de produto	Limites e restrições por conta	Nã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 tenant — aplica-se a todas as transferências da organização
Por conta — aplica-se a uma conta específica do usuário final (sobrescreve os padrões do tenant)

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

O padrão é fail-closed. Altere isso por organização via Admin API.

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 tenant — por exemplo, restringindo transferências apenas ao horário comercial — dentro dos limites do BACEN.

Configuração de infraestrutura

Esta seção é para times de DevOps. Essas variáveis são definidas no momento do deployment e requerem reinicialização do serviço para entrar em vigor.

Aplicação

Variável	Padrão	Obrigatório	Descrição
`ENV_NAME`	`development`	Não	Ambiente (`development`, `staging`, `production`)
`LOG_LEVEL`	`info`	Não	Verbosidade do log (`debug`, `info`, `warn`, `error`)
`DEPLOYMENT_MODE`	`byoc`	Não	Sabor de deployment. `byoc` = Bring Your Own Cloud (single-tenant, gerenciado pelo operador). Aciona comportamentos internos SaaS vs. BYOC.
`SERVER_ADDRESS`	`:8080`	Não	Endereço e porta do servidor HTTP
`HTTP_BODY_LIMIT_BYTES`	`1048576`	Não	Tamanho máximo do corpo da requisição HTTP em bytes
`INFRA_CONNECT_TIMEOUT_SEC`	`30`	Não	Timeout de conexão para serviços de infraestrutura em segundos
`ALLOW_PRIVATE_UPSTREAMS`	`false`	Não	⚠️ Permite que adaptadores de saída (CRM, Fees, JD, Midaz) resolvam para IPs RFC1918/loopback. O padrão `false` é fail-closed: produção bloqueia pivot DNS para o espaço privado. Habilite em dev ou em BYOC in-cluster, onde upstreams legitimamente vivem em IPs privadas. Endpoints de metadados em cloud permanecem bloqueados independentemente desse flag.

TLS

Variável	Padrão	Obrigatório	Descrição
`SERVER_TLS_CERT_FILE`	-	Não	Caminho para o arquivo de certificado TLS. Deve ser definido junto com `SERVER_TLS_KEY_FILE`.
`SERVER_TLS_KEY_FILE`	-	Não	Caminho para o arquivo de chave privada TLS. Deve ser definido junto com `SERVER_TLS_CERT_FILE`.
`TLS_TERMINATED_UPSTREAM`	`false`	Não	Defina como `true` quando o TLS é terminado por um load balancer ou proxy reverso.

Headers de proxy

Usados quando o serviço roda atrás de um load balancer ou proxy reverso. Necessários para extrair o IP real do cliente para rate limiting e logs de auditoria.

Variável	Padrão	Obrigatório	Descrição
`SERVER_PROXY_HEADER`	-	Não	Header HTTP que carrega o IP real do cliente (ex: `X-Forwarded-For`, `X-Real-IP`). Vazio desabilita o parsing do header de proxy.
`SERVER_TRUSTED_PROXIES`	-	Se proxy header definido	Lista separada por vírgula de IPs/CIDRs de proxies confiáveis. Obrigatório quando `SERVER_PROXY_HEADER` está definido para evitar spoofing de IP.

CORS

Variável	Padrão	Obrigatório	Descrição
`CORS_ALLOWED_ORIGINS`	`http://localhost:3000`	Não	Lista de origens permitidas separadas por vírgula. Wildcards (`*`) e origens localhost são rejeitados em produção.
`CORS_ALLOWED_METHODS`	`GET,POST,PUT,PATCH,DELETE,OPTIONS`	Não	Métodos HTTP permitidos.
`CORS_ALLOWED_HEADERS`	`Origin,Content-Type,Accept,Authorization,X-Request-ID,X-Organization-Id,X-Idempotency`	Não	Headers de requisição permitidos.

Autenticação

Este plugin delega a autorização ao plugin-auth. Configure a conexão com as variáveis abaixo.

Variável	Padrão	Obrigatório	Descrição
`PLUGIN_AUTH_ENABLED`	`false`	Não	Habilita a autorização via plugin-auth. Defina como `true` em produção.
`PLUGIN_AUTH_ADDRESS`	-	Se habilitado	URL do serviço plugin-auth. Deve usar HTTPS em produção.
`PLUGIN_AUTH_CLIENT_ID`	`plugin-br-bank-transfer`	Se habilitado	OAuth client ID usado por este plugin.
`PLUGIN_AUTH_CLIENT_SECRET`	-	Se habilitado	OAuth client secret usado por este plugin.
`AUTH_CACHE_TTL_SEC`	`60`	Não	Duração (em segundos) para armazenar em cache as decisões de autorização. Decisões negadas ficam em cache por TTL/4.

Quando PLUGIN_AUTH_ENABLED=true, PLUGIN_AUTH_ADDRESS deve usar HTTPS em ambientes de produção. Endereços HTTP são rejeitados na inicialização.

Test admin (apenas não-produção)

BTF_TEST_ADMIN_ENABLED deve permanecer false em produção. Expõe endpoints administrativos apenas de teste (ex: POST /admin/test/circuit-breakers/reset) que não têm tenant e burlam a autenticação de produção. Habilitado apenas pelo mock-lane do docker-compose para testes E2E; qualquer deployment com esse flag em true fora de uma rede de testes isolada é uma má configuração.

Variável	Padrão	Obrigatório	Descrição
`BTF_TEST_ADMIN_ENABLED`	`false`	Não	⚠️ Expõe endpoints administrativos apenas de teste. Deve permanecer `false` em produção.
`BTF_TEST_ADMIN_TOKEN`	-	Se admin habilitado	Token requerido quando `BTF_TEST_ADMIN_ENABLED=true`. Enviado no header `X-Test-Admin-Token`. Intencionalmente separado da auth de produção (superfície apenas de teste, sem tenant).

Rate limiting

Variável	Padrão	Obrigatório	Descrição
`RATE_LIMIT_ENABLED`	`true`	Não	Habilita rate limiting por cliente. Forçado para `true` em produção.
`RATE_LIMIT_MAX`	`100`	Não	Máximo de requisições por janela por cliente.
`RATE_LIMIT_EXPIRY_SEC`	`60`	Não	Duração da janela deslizante em segundos.

Idempotência

Variável	Padrão	Obrigatório	Descrição
`IDEMPOTENCY_RETRY_WINDOW_SEC`	`300`	Não	Janela de tempo (em segundos) durante a qual uma chave de idempotência é válida.
`IDEMPOTENCY_REQUIRE_REDIS`	`false`	Não	Quando `true`, rejeita requisições se o Redis estiver indisponível em vez de usar fallback.
`DUPLICATE_GUARD_TTL_SEC`	`300`	Não	TTL (em segundos) para a janela de duplicate-guard no Redis. Complementa `IDEMPOTENCY_RETRY_WINDOW_SEC`; este TTL controla o tempo de vida da entrada do duplicate-guard.

Multi-tenancy

Variável	Padrão	Obrigatório	Descrição
`MULTI_TENANT_ENABLED`	`false`	Não	Habilita multi-tenancy em nível de infraestrutura com bancos de dados isolados por tenant.
`DEFAULT_TENANT_ID`	`11111111-1111-1111-1111-111111111111`	Não	UUID de tenant de fallback quando auth está desabilitado. Deve ser um UUID válido.
`DEFAULT_TENANT_SLUG`	`default`	Não	Identificador slug do tenant padrão.
`DEFAULT_ORGANIZATION_ID`	-	Não	ID de organização usado em modo single-tenant (quando `MULTI_TENANT_ENABLED=false`). Complementa `DEFAULT_TENANT_ID`.
`AWS_REGION`	-	Se backend de secretos AWS	Região AWS para leituras de secretos por tenant no Secrets Manager. Obrigatório quando `MULTI_TENANT_ENABLED=true` e o backend de secretos é AWS.
`MULTI_TENANT_INTEGRATION_SECRET_NAME_TEMPLATE`	`tenants/{env}/{tenantId}/{applicationName}/integration/configuration`	Não	Template do nome do secret no AWS Secrets Manager. Placeholders: `{env}`, `{tenantId}`, `{applicationName}`.
`TENANT_IDS`	-	Não	Lista de UUIDs de tenant permitidos, separados por vírgula. Esta variável tem dupla função: (1) allowlisting de requisições — requisições de tenants fora desta lista são rejeitadas, e (2) escopo de licenciamento — somente estes tenants são considerados licenciados. Deixe sem definir para permitir todos os tenants configurados. Também referenciada em Licença.
`MULTI_TENANT_URL`	-	Sim (quando habilitado)	URL da API HTTP do Tenant Manager.
`MULTI_TENANT_REDIS_HOST`	-	Não	Host Redis para descoberta de tenants via Pub/Sub.
`MULTI_TENANT_REDIS_PORT`	`6379`	Não	Porta do Redis para Pub/Sub.
`MULTI_TENANT_REDIS_PASSWORD`	-	Não	Senha do Redis para Pub/Sub.
`MULTI_TENANT_REDIS_TLS`	`false`	Não	Habilita TLS para conexão Redis Pub/Sub.
`MULTI_TENANT_TIMEOUT`	`30`	Não	Timeout HTTP em segundos para chamadas à API do Tenant Manager.
`MULTI_TENANT_MAX_TENANT_POOLS`	`100`	Não	Máximo de pools de conexão simultâneos por tenant.
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	`300`	Não	Timeout de inatividade em segundos antes de descartar um pool de tenant.
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	`5`	Não	Número de falhas antes do circuit breaker abrir.
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	`30`	Não	Timeout de recuperação em segundos do circuit breaker.
`MULTI_TENANT_SERVICE_API_KEY`	-	Sim (quando habilitado)	Chave de API para o endpoint `/settings` do Tenant Manager.
`MULTI_TENANT_CACHE_TTL_SEC`	`120`	Não	TTL em segundos do cache in-memory de configuração de tenant. Recarregável via systemplane API.
`MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`	`30`	Não	Intervalo em segundos para revalidação assíncrona de configurações de pool. Somente bootstrap (não recarregável).

BYOC single-tenant:

DEFAULT_TENANT_ID=<seu-tenant-uuid>
# Opcional: restringir a UUIDs de tenant específicos
TENANT_IDS=<uuid1>,<uuid2>

SaaS multi-tenant:

MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=http://tenant-manager:4003
MULTI_TENANT_SERVICE_API_KEY=sua-api-key
MULTI_TENANT_REDIS_HOST=redis.example.com

PostgreSQL

Variável	Padrão	Obrigatório	Descrição
`POSTGRES_HOST`	`localhost`	Sim	Host primário do PostgreSQL.
`POSTGRES_PORT`	`5432`	Não	Porta primária do PostgreSQL.
`POSTGRES_USER`	`plugin-br-bank-transfer`	Sim	Usuário do banco de dados.
`POSTGRES_PASSWORD`	-	Sim	Senha do banco de dados. Obrigatório em produção.
`POSTGRES_DB`	`plugin-br-bank-transfer`	Sim	Nome do banco de dados.
`POSTGRES_SSLMODE`	`require`	Não	Modo SSL. `disable` é rejeitado em produção.
`POSTGRES_MAX_OPEN_CONNS`	`25`	Não	Máximo de conexões abertas.
`POSTGRES_MAX_IDLE_CONNS`	`5`	Não	Máximo de conexões ociosas.
`POSTGRES_CONN_MAX_LIFETIME_MINS`	`30`	Não	Tempo máximo de vida da conexão em minutos.
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	`5`	Não	Tempo máximo ocioso da conexão em minutos.
`POSTGRES_CONNECT_TIMEOUT_SEC`	`10`	Não	Timeout de conexão em segundos.
`MIGRATIONS_PATH`	`migrations`	Não	Caminho para arquivos de migração.

Réplica PostgreSQL

Configure uma réplica de leitura para descarregamento de consultas. Todos os campos usam valores primários como fallback quando não definidos.

Variável	Padrão	Obrigatório	Descrição
`POSTGRES_REPLICA_HOST`	-	Não	Host da réplica. Não definido = sem réplica.
`POSTGRES_REPLICA_PORT`	-	Não	Porta da réplica.
`POSTGRES_REPLICA_USER`	-	Não	Usuário da réplica.
`POSTGRES_REPLICA_PASSWORD`	-	Não	Senha da réplica.
`POSTGRES_REPLICA_DB`	-	Não	Nome do banco da réplica.
`POSTGRES_REPLICA_SSLMODE`	-	Não	Modo SSL da réplica.

MongoDB

O MongoDB é necessário para a persistência de eventos de auditoria de transferências. O serviço não iniciará sem uma conexão MongoDB válida.

Variável	Padrão	Obrigatório	Descrição
`MONGO_ENABLED`	`true`	Sim	Habilita a conexão MongoDB. Deve ser `true` em todos os ambientes.
`MONGO_URI`	-	Sim	String de conexão MongoDB (ex: `mongodb://user:pass@host:27017`). Deve incluir credenciais e TLS em produção.
`MONGO_DATABASE`	-	Sim	Nome do banco de dados MongoDB.
`MONGO_MAX_POOL_SIZE`	`25`	Não	Tamanho máximo do pool de conexões.
`MONGO_SERVER_SELECTION_TIMEOUT_MS`	`3000`	Não	Timeout de seleção de servidor em milissegundos.
`MONGO_HEARTBEAT_INTERVAL_MS`	`10000`	Não	Intervalo de heartbeat em milissegundos.
`MONGO_TLS_CA_CERT`	-	Não	Certificado CA codificado em base64 para TLS do MongoDB. Use quando o MongoDB exigir TLS com CA personalizado (ex: Atlas, instâncias privadas com certs autoassinados).

Redis

Variável	Padrão	Obrigatório	Descrição
`REDIS_HOST`	`localhost:6379`	Sim	Host e porta do Redis.
`REDIS_MASTER_NAME`	-	Não	Nome do master Redis Sentinel (se usando Sentinel).
`REDIS_PASSWORD`	-	Não	Senha do Redis (se autenticação habilitada).
`REDIS_DB`	`0`	Não	Número do banco de dados Redis.
`REDIS_PROTOCOL`	`3`	Não	Versão do protocolo Redis (2 ou 3).
`REDIS_TLS`	`false`	Não	Habilita TLS para conexões Redis.
`REDIS_CA_CERT`	-	Não	Certificado CA para TLS Redis.
`REDIS_POOL_SIZE`	`10`	Não	Tamanho do pool de conexões.
`REDIS_MIN_IDLE_CONNS`	`2`	Não	Mínimo de conexões ociosas.
`REDIS_READ_TIMEOUT_MS`	`3000`	Não	Timeout de leitura em milissegundos.
`REDIS_WRITE_TIMEOUT_MS`	`3000`	Não	Timeout de escrita em milissegundos.
`REDIS_DIAL_TIMEOUT_MS`	`5000`	Não	Timeout de conexão em milissegundos.

Redis é uma dependência obrigatória. Se o Redis estiver indisponível na inicialização ou se tornar inacessível em tempo de execução, o serviço reportará como DOWN para o probe de readiness da orquestração e parará de aceitar requisições. O Redis é necessário para o cache de chaves de idempotência e detecção de duplicatas.

Conexão JD SPB

Essas variáveis são obrigatórias para deployments BYOC. No modo SaaS, a Lerian gerencia a conexão com o JD.

Variável	Padrão	Obrigatório	Descrição
`JD_BASE_URL`	-	Se BYOC	URL base da API JD SPB.
`JD_SOAP_PATH`	`/soap`	Não	Caminho do endpoint SOAP JD.
`JD_ORIGIN_ISPB`	-	Se BYOC	Código ISPB de origem.
`JD_LEGACY_CODE`	-	Se BYOC	Código legado JD (máx. 10 chars).
`JD_USER_CODE`	-	Se BYOC	Código de usuário JD (máx. 10 chars).
`JD_PASSWORD`	-	Se BYOC	Senha JD (criptografada em repouso).
`JD_PRIVATE_KEY_PEM`	-	Se BYOC	Conteúdo PEM da chave privada RSA para assinatura XML.
`JD_PUBLIC_KEY_PEM`	-	Não	PEM de chave pública para validar assinaturas em respostas do JD. Obrigatório quando `JD_VALIDATE_EXTERNAL_SIGNATURE=true`.
`JD_PRIVATE_KEY_KEYINFO`	-	Não	Bloco XML `<KeyInfo>` embutido na assinatura SOAP (ex: cert X509 codificado em base64). Obrigatório para o envelope WS-Security quando o JD demanda identificação por certificado.
`JD_SIGNING_MODE`	`local_pem`	Não	Modo de assinatura SOAP. `local_pem` assina localmente com `JD_PRIVATE_KEY_PEM`; `external_signer` delega a um serviço remoto via `JD_EXTERNAL_SIGNER_URL`.
`JD_VALIDATE_EXTERNAL_SIGNATURE`	`true`	Não	Valida assinaturas em respostas do JD (ou do assinador externo). O padrão `true` mantém a validação ativa. Defina como `false` apenas para debug/sandbox sem PKI configurado.
`JD_EXTERNAL_SIGNER_URL`	-	Se `JD_SIGNING_MODE=external_signer`	URL base do serviço de assinatura externo.
`JD_EXTERNAL_SIGNER_AUTH_TOKEN`	-	Não	Bearer token enviado no header `Authorization` para chamadas ao assinador externo.
`JD_EXTERNAL_SIGNER_TIMEOUT_MS`	`5000`	Não	Timeout (em milissegundos) para chamadas ao assinador externo.
`JD_BACEN_ROUTING_ISPB`	`00038166`	Não	ISPB de roteamento do BACEN (o ISPB do JD/JDSPB). O padrão `00038166` é o ISPB do banco JD. Altere apenas se o operador rotear por um PSP diferente.
`JD_TIMEOUT_MS`	`8000`	Não	Timeout de requisições SOAP em milissegundos.
`JD_MAX_RETRIES`	`3`	Não	Máximo de tentativas de retry para requisições JD.
`JD_SANDBOX_MODE`	`false`	Não	Habilita modo sandbox JD. Rejeitado em produção.

Polling JD

Variável	Padrão	Obrigatório	Descrição
`JD_POLLING_ENABLED`	`false`	Não	Habilita worker de polling TED IN.
`JD_POLL_INTERVAL_SECONDS`	`30`	Não	Frequência (em segundos) de verificação de TEDs recebidos.
`JD_POLL_MAX_MESSAGES_PER_CYCLE`	`50`	Não	Máximo de mensagens processadas por ciclo de polling.
`JD_POLL_MAX_RETRIES`	`3`	Não	Máximo de tentativas de retry por ciclo de polling.
`JD_POLL_RECOVERY_BATCH_SIZE`	`200`	Não	Tamanho do lote para polling de recuperação.
`JD_POLL_DISABLE_OPERATING_HOURS_WINDOW`	`true`	Não	Quando `true`, o poller RecebeMensagem ignora a janela de horário de funcionamento (`TRANSFER_OPERATING_OPEN`/`CLOSE`) e roda continuamente. O padrão é `true` porque o JD pode entregar mensagens fora da janela de transferência do operador.
`BTF_TED_IN_RETORNO_FILTER`	-	Não	Filtro `TpRetorno` separado por vírgula aplicado server-side pelo RecebeMensagem. Vazio = sem filtro (busca P/R/E/C). Nota: a spec do JD codifica `TpRetorno` como um único elemento, então apenas o primeiro valor é honrado hoje.

JD_POLLING_ENABLED é desabilitado por padrão para deployments mais seguros. Antes de habilitá-lo, certifique-se de que DEFAULT_TENANT_ID (ou Pool Manager) esteja configurado com um UUID válido. O polling JD não é suportado quando MULTI_TENANT_ENABLED=true.

Serviços externos (Midaz)

Variável	Padrão	Obrigatório	Descrição
`MIDAZ_BASE_URL`	-	Sim	URL base do serviço Midaz.
`MIDAZ_TRANSACTION_URL`	-	Sim	URL do serviço de transações Midaz.
`MIDAZ_TIMEOUT_MS`	`3000`	Não	Timeout de requisições Midaz em milissegundos.
`MIDAZ_MAX_RETRIES`	`3`	Não	Tentativas de retry em falha do Midaz.
`MIDAZ_OTEL_ENABLED`	`true`	Não	Habilita tracing OpenTelemetry para chamadas Midaz.
`MIDAZ_DEBUG`	`false`	Não	Habilita logging de debug para chamadas Midaz. Rejeitado em produção.
`MIDAZ_AUTH_ENABLED`	`false`	Não	Habilita autenticação M2M para Midaz.
`MIDAZ_AUTH_ADDRESS`	-	Se auth	URL do serviço de autenticação para tokens M2M Midaz.
`MIDAZ_CLIENT_ID`	-	Se auth	OAuth client ID para M2M Midaz.
`MIDAZ_CLIENT_SECRET`	-	Se auth	OAuth client secret para M2M Midaz.
`MIDAZ_BREAKER_FAILURES`	`3`	Não	Threshold de falhas do circuit breaker.
`MIDAZ_BREAKER_TIMEOUT_SECONDS`	`30`	Não	Timeout de recuperação do circuit breaker em segundos.
`BTF_MIDAZ_CB_ENABLED`	`true`	Não	Kill switch para o circuit breaker do client Midaz. Quando `false`, chamadas ao Midaz pulam o breaker (timeouts e retries permanecem ativos). Útil quando flakes intermitentes estão amplificando para 500s sustentados.

Serviços externos (CRM)

Variável	Padrão	Obrigatório	Descrição
`CRM_BASE_URL`	-	Sim	URL do serviço CRM.
`CRM_TIMEOUT_MS`	`2000`	Não	Timeout de requisições CRM em milissegundos.
`CRM_MAX_RETRIES`	`2`	Não	Tentativas de retry em falha do CRM.
`CRM_AUTH_ENABLED`	`false`	Não	Habilita autenticação M2M para CRM.
`CRM_CLIENT_ID`	-	Se auth	OAuth client ID para M2M CRM.
`CRM_CLIENT_SECRET`	-	Se auth	OAuth client secret para M2M CRM.
`CRM_SENDER_LOOKUP_PATH_TEMPLATE`	-	Não	Template de path para lookup do remetente no CRM (ex: `/api/v1/accounts/{accountId}`). Os placeholders são definidos pelo CRM do operador.
`CRM_RECIPIENT_LOOKUP_PATH_TEMPLATE`	-	Não	Template de path para lookup do destinatário no CRM.
`CRM_HOLDER_LOOKUP_PATH_TEMPLATE`	-	Não	Template de path para lookup do titular da conta no CRM.

Serviços externos (Fees)

BTF_FEE_ENABLED é a chave mestra. Quando false (padrão), nenhum adaptador de Fees é construído e cada transferência segue com tarifa=0 sem chamada HTTP. As demais variáveis FEES_* só têm efeito quando BTF_FEE_ENABLED=true.

Variável	Padrão	Obrigatório	Descrição
`BTF_FEE_ENABLED`	`false`	Não	Chave mestra para a integração com plugin-fees. Quando `false`, nenhum adaptador de Fees é construído e todas as transferências rodam com tarifa=0 sem chamadas HTTP. Operadores que rodam plugin-fees devem setar como `true` explicitamente.
`FEES_BASE_URL`	-	Se habilitado	URL do serviço Fees Engine.
`FEES_TIMEOUT_MS`	`2000`	Não	Timeout de requisições de tarifas em milissegundos.
`FEES_MAX_RETRIES`	`2`	Não	Tentativas de retry em falha do serviço de tarifas.
`FEES_FAIL_CLOSED_DEFAULT`	`false`	Não	Modo de falha padrão. `true` = bloqueia transferência quando tarifas indisponível.
`FEES_MAX_FEE_AMOUNT_CENTS`	`99999999`	Não	Valor máximo de tarifa em centavos. Respostas que excedem esse valor são rejeitadas.
`FEES_REFUND_ON_DEVOLUCAO`	`false`	Não	Quando `true`, tarifas cobradas são reembolsadas em devoluções/reversões de TED. O padrão `false` mantém a tarifa retida mesmo na devolução.
`FEES_AUTH_ENABLED`	`false`	Não	Habilita autenticação M2M para Fees.
`FEES_CLIENT_ID`	-	Se auth	OAuth client ID para M2M Fees.
`FEES_CLIENT_SECRET`	-	Se auth	OAuth client secret para M2M Fees.

Resiliência de Fees

BTF_FEES_TED_IN_FAIL_OPEN é true por padrão. Quando o plugin-fees está indisponível, TEDs recebidos são creditados com tarifa=0 (fail-open) para que os fundos cheguem ao cliente. Operadores com SLA que exige cobrança em todo crédito de entrada devem setar como false (fail-closed). TED OUT é incondicionalmente fail-closed independentemente desse flag — o débito do remetente é autoritativo.

Variável	Padrão	Obrigatório	Descrição
`BTF_FEES_TED_IN_FAIL_OPEN`	`true`	Não	⚠️ Quando `true`, TED IN segue com tarifa=0 se o plugin-fees estiver inalcançável. Quando `false`, TED IN é bloqueado até que tarifas se recupere. TED OUT é sempre fail-closed.

Reconciliação

O worker de reconciliação coleta transferências pendentes que nunca receberam retorno do JD e as reconcilia contra o ledger.

Variável	Padrão	Obrigatório	Descrição
`BTF_RECONCILIATION_ENABLED`	`true`	Não	Habilita o motor de reconciliação interno. Quando `false`, transferências sem retorno do JD nunca são reconciliadas automaticamente.
`BTF_RECONCILIATION_INTERVAL_SEC`	`30`	Não	Intervalo (em segundos) entre ciclos de reconciliação.
`BTF_RECONCILIATION_BATCH_SIZE`	`20`	Não	Número máximo de transferências processadas por ciclo de reconciliação.
`BTF_RECONCILIATION_MAX_ATTEMPTS`	`10`	Não	Máximo de tentativas de reconciliação antes de marcar uma transferência como permanentemente falha.
`BTF_RECONCILIATION_STALE_AFTER_SEC`	`60`	Não	Tempo (em segundos) após o qual uma transferência pendente é considerada obsoleta e elegível para reconciliação.
`BTF_DLQ_ENABLED`	`true`	Não	Persiste mensagens JD não-parseáveis na tabela dead-letter `jd_incoming_parse_failures`. O padrão `true` é assim porque descartar mensagens silenciosamente nunca é seguro sob entrega at-most-once.

Calendário de feriados (BACEN/ANBIMA)

Alimenta o calendário de feriados bancários do BACEN usado pelo gate de horário de funcionamento e pelo clamp do TTL de iniciação. O banco de dados é a fonte da verdade; estas variáveis governam apenas o refresher agendado.

Variável	Padrão	Obrigatório	Descrição
`ANBIMA_HOLIDAY_SOURCE_URL`	`https://www.anbima.com.br/feriados/arqs/feriados_nacionais.xls`	Não	URL upstream para feriados BACEN/ANBIMA. O fetcher em tempo real ainda não está cabeado (uma seed estática para 2026–2028 é usada); operadores podem repontar para um mirror interno.
`ANBIMA_FETCHER_ENABLED`	`true`	Não	Liga o refresher de feriados agendado. Quando `false`, o plugin se apoia em uma tabela `bacen_holidays` pré-populada.
`ANBIMA_FETCHER_SCHEDULE`	`03:00`	Não	Horário diário de disparo (HH:MM) do refresher. `03:00` fica fora do horário do BACEN e antes da janela das 06:30 abrir, evitando snapshots no meio de um refresh.
`HOLIDAY_CACHE_TTL`	`1h`	Não	TTL do cache in-process do calendário de feriados (formato `time.ParseDuration`: `1h`, `30m`, etc.). Reduza esse valor quando UPSERTs manuais precisarem se propagar mais rápido.

RabbitMQ

Eventos de ciclo de vida de transferência podem ser publicados no RabbitMQ para consumidores downstream.

Variável	Padrão	Obrigatório	Descrição
`RABBITMQ_ENABLED`	`false`	Não	Habilita publicação de eventos de ciclo de vida de transferência.
`RABBITMQ_URL`	-	Se habilitado	URL de conexão AMQP. Deve usar `amqps://` fora de desenvolvimento.
`RABBITMQ_EXCHANGE`	`bank_transfer.lifecycle`	Não	Nome do exchange para eventos de ciclo de vida.
`RABBITMQ_ROUTING_KEY_PREFIX`	`transfer`	Não	Prefixo da routing key para eventos publicados.
`RABBITMQ_EVENT_SIGNING_SECRET`	-	Se habilitado	Segredo HMAC para assinatura de eventos publicados. Mínimo 32 caracteres.
`RABBITMQ_PUBLISH_TIMEOUT_MS`	`5000`	Não	Timeout de publicação em milissegundos.
`RABBITMQ_MAX_RETRIES`	`3`	Não	Máximo de tentativas de republicação.
`RABBITMQ_RETRY_BACKOFF_MS`	`200`	Não	Backoff entre republicações em milissegundos.

Entrega de webhooks

A entrega de webhooks requer que o RabbitMQ esteja habilitado. O worker de webhook consome eventos de uma fila RabbitMQ e os entrega ao endpoint configurado.

Variável	Padrão	Obrigatório	Descrição
`WEBHOOK_ENABLED`	`false`	Não	Habilita entrega de webhooks. Requer `RABBITMQ_ENABLED=true`.
`WEBHOOK_ENDPOINT_URL`	-	Se habilitado	URL de destino. Deve usar HTTPS; IPs loopback/privados são rejeitados.
`WEBHOOK_SIGNING_SECRET`	-	Se habilitado	Segredo HMAC para assinar payloads de webhook. Mínimo 32 caracteres.
`WEBHOOK_BROKER_EVENT_SIGNING_SECRET`	-	Não	Segredo HMAC separado para verificar eventos do broker. Usa `WEBHOOK_SIGNING_SECRET` como fallback.
`WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS`	`false`	Não	Aceita temporariamente eventos não assinados do broker durante migração.
`WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC`	`0`	Não	Período de graça (em segundos) para eventos não assinados. Deve ser > 0 quando eventos não assinados são permitidos.
`WEBHOOK_QUEUE_NAME`	`transfer.webhook.delivery`	Não	Nome da fila RabbitMQ para eventos de webhook.
`WEBHOOK_DLQ_NAME`	`transfer.webhook.dlq`	Não	Fila de dead-letter para entregas de webhook falhas.
`WEBHOOK_CONSUMER_TAG`	`plugin-br-bank-transfer-webhook`	Não	Tag de consumidor RabbitMQ.
`WEBHOOK_PREFETCH_COUNT`	`20`	Não	Contagem de prefetch RabbitMQ.
`WEBHOOK_DELIVERY_CONCURRENCY`	`8`	Não	Máximo de entregas de webhook concorrentes por worker.
`WEBHOOK_TIMEOUT_MS`	`5000`	Não	Timeout de entrega HTTP em milissegundos.
`WEBHOOK_MAX_RETRIES`	`3`	Não	Máximo de tentativas de reentrega.
`WEBHOOK_RETRY_BACKOFF_MS`	`500`	Não	Backoff entre reentregas em milissegundos.

Limites de uso

Variável	Padrão	Obrigatório	Descrição
`USAGE_LIMITS_ENABLED`	`false`	Não	Habilita imposição de limites de uso por conta.
`USAGE_LIMIT_DAILY_CENTS`	`0`	Não	Limite diário padrão de transferência em centavos. Ao menos um limite deve ser > 0 quando habilitado.
`USAGE_LIMIT_MONTHLY_CENTS`	`0`	Não	Limite mensal padrão de transferência em centavos.

Horários de funcionamento

Variável	Padrão	Obrigatório	Descrição
`TRANSFER_OPERATING_OPEN`	`06:30`	Não	Horário de abertura da janela de aceitação de transferências (HH:MM).
`TRANSFER_OPERATING_CLOSE`	`17:00`	Não	Horário de fechamento da janela de aceitação de transferências (HH:MM).
`TRANSFER_OPERATING_TIMEZONE`	`America/Sao_Paulo`	Não	Fuso horário para avaliação dos horários de funcionamento.

Telemetria (OpenTelemetry)

Variável	Padrão	Obrigatório	Descrição
`ENABLE_TELEMETRY`	`false`	Não	Habilita tracing e métricas OpenTelemetry.
`OTEL_RESOURCE_SERVICE_NAME`	`plugin-br-bank-transfer`	Não	Nome do serviço OTel.
`OTEL_LIBRARY_NAME`	`github.com/LerianStudio/plugin-br-bank-transfer`	Não	Nome da biblioteca de instrumentação OTel.
`OTEL_RESOURCE_SERVICE_VERSION`	`1.0.0`	Não	Versão do serviço OTel.
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	`development`	Não	Ambiente de deployment OTel.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`localhost:4317`	Não	Endpoint gRPC do coletor OTel.
`DB_METRICS_INTERVAL_SEC`	`15`	Não	Intervalo de coleta de métricas do banco em segundos.
`RECONCILIATION_PENDING_ALERT_THRESHOLD`	`5`	Não	Threshold de alerta para itens de reconciliação pendentes.
`OTEL_TRACES_SAMPLER_ARG`	-	Não	Razão de amostragem de traces (0.0–1.0). Sem definir usa o sampler padrão resolvido na inicialização da telemetria: `0.1` em produção, `1.0` em outros ambientes. Valores fora de (0,1] são clampeados para 1.0 para que uma má configuração não desabilite silenciosamente o tracing em produção.
`BTF_METRICS_PROMETHEUS_ENABLED`	`false`	Não	Expõe um endpoint dedicado de scrape do Prometheus para as métricas `btf.*`. Quando `true`, o listener em `BTF_METRICS_PROMETHEUS_ADDRESS` é iniciado.
`BTF_METRICS_PROMETHEUS_ADDRESS`	`127.0.0.1:9090`	Não	Endereço de escuta do endpoint Prometheus `/metrics`. O padrão se vincula ao loopback para que um pod mal configurado não exponha métricas não autenticadas para a rede do cluster. Sobrescreva (ex: `0.0.0.0:9090`) apenas atrás de uma NetworkPolicy ou sidecar.

Licença

Variável	Padrão	Obrigatório	Descrição
`LICENSE_KEY`	-	Em produção	Chave de licença. Obrigatório em ambientes de produção.
`LICENSE_SERVICE_ADDRESS`	-	Não	URL do serviço de validação de licença.
`TENANT_IDS`	-	Não	Mesma variável de Multi-tenancy. Lista de UUIDs de tenant separados por vírgula, usada tanto para allowlisting de requisições quanto para escopo de licenciamento.

Criptografia

Criptografia em nível de campo para dados sensíveis em repouso. Cada chave deve ser uma chave AES-256 de 32 bytes codificada em base64. Deixe em branco para desabilitar a criptografia do campo.

Variável	Padrão	Obrigatório	Descrição
`JD_INCOMING_RAW_XML_ENCRYPTION_KEY`	-	Não	Chave AES-256 para criptografia de payloads XML JD recebidos.
`RECIPIENT_DETAILS_ENCRYPTION_KEY`	-	Não	Chave AES-256 para criptografia de detalhes do destinatário em repouso.

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

Documentation Index

​Níveis de configuração

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

​Limites de transferência

​Política de tarifas

​Fail-open vs. fail-closed

​Recebimento de TED IN

​Sobrescritas de horários de funcionamento

​Configuração de infraestrutura

​Aplicação

​TLS

​Headers de proxy

​CORS

​Autenticação

​Test admin (apenas não-produção)

​Rate limiting

​Idempotência

​Multi-tenancy

​PostgreSQL

​Réplica PostgreSQL

​MongoDB

​Redis

​Conexão JD SPB

​Polling JD

​Serviços externos (Midaz)

​Serviços externos (CRM)

​Serviços externos (Fees)

​Resiliência de Fees

​Reconciliação

​Calendário de feriados (BACEN/ANBIMA)

​RabbitMQ

​Entrega de webhooks

​Limites de uso

​Horários de funcionamento

​Telemetria (OpenTelemetry)

​Licença

​Criptografia

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

Níveis de configuração

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

Limites de transferência

Política de tarifas

Fail-open vs. fail-closed

Recebimento de TED IN

Sobrescritas de horários de funcionamento

Configuração de infraestrutura

Aplicação

TLS

Headers de proxy

CORS

Autenticação

Test admin (apenas não-produção)

Rate limiting

Idempotência

Multi-tenancy

PostgreSQL

Réplica PostgreSQL

MongoDB

Redis

Conexão JD SPB

Polling JD

Serviços externos (Midaz)

Serviços externos (CRM)

Serviços externos (Fees)

Resiliência de Fees

Reconciliação

Calendário de feriados (BACEN/ANBIMA)

RabbitMQ

Entrega de webhooks

Limites de uso

Horários de funcionamento

Telemetria (OpenTelemetry)

Licença

Criptografia

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