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

# Variáveis de ambiente

> Configure o plugin Bank Transfer via JD no momento do deploy: aplicação, TLS e headers de proxy, persistência, integração JD SPB e variáveis de segurança.

O DevOps define estas variáveis no momento do deploy. Uma mudança exige reinício do serviço. As configurações de tempo de execução e de negócio ficam em [Configuração](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-configuration.md).

Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo **Obrigatório**, **Obrigatório em produção**, **Obrigatório se habilitado**) marca uma variável que você deve definir. `—` significa sem padrão.

## Configuração de infraestrutura

***

Esta seção é para times de DevOps. O DevOps define estas variáveis no momento do deploy. Uma mudança entra em vigor apenas depois de um reinício do serviço.

### Aplicação

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ENVIRONMENT_NAME` | `development` | Ambiente: `production`, `staging`, `uat`, `development`, `local` ou `test`. O serviço não sobe com outro valor, nem quando `ENV_NAME`, o nome obsoleto desta variável, indica um ambiente diferente. |
| `DEPLOYMENT_MODE` | `byoc` | `byoc` (Bring Your Own Cloud), `saas` ou `local`, que funciona como `byoc`. O serviço não sobe com outro valor. Com `saas`, o plugin se recusa a subir a menos que PostgreSQL, Redis, MongoDB, RabbitMQ e o broker de streaming usem TLS. |
| `SERVER_ADDRESS` | `:8080` | Endereço e porta do servidor HTTP |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | Tamanho máximo do corpo da requisição HTTP em bytes |
| `ALLOW_PRIVATE_UPSTREAMS` | `false` | ⚠️ Permite que os adaptadores de saída (CRM, Fees, JD, Midaz) resolvam para IPs RFC1918/loopback. O padrão `false` é fail-closed: em produção, bloqueia o pivô de DNS para o espaço privado. Habilite em dev ou em BYOC dentro do cluster, onde os upstreams ficam legitimamente em IPs privados. Recusado em produção. Os endpoints de metadados da nuvem continuam bloqueados independentemente deste flag. |
| `REQUIRE_UPSTREAM_HTTPS` | `false` | Recusa URLs base do CRM e do Fees Engine em `http://` puro. A produção já as recusa; use esta variável em deploys de staging, homologação e BYOC que carregam dados reais de clientes. |

### TLS

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

### Headers de proxy

Defina estes quando o serviço roda atrás de um load balancer ou proxy reverso. Eles permitem ao serviço ler o IP real do cliente para rate limiting e logs de auditoria.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SERVER_PROXY_HEADER` | — | Header HTTP que carrega o IP real do cliente (por exemplo `X-Forwarded-For`, `X-Real-IP`). Vazio desabilita a leitura do header de proxy. |
| `SERVER_TRUSTED_PROXIES` | **Obrigatório se o header de proxy estiver definido** | Lista separada por vírgulas de IPs/CIDRs de proxies confiáveis. Obrigatório quando `SERVER_PROXY_HEADER` está definido, para evitar spoofing de IP. |

### Autenticação

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

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` · **`true` obrigatório em produção** | Habilita a autorização via Access Manager. O serviço se recusa a subir em produção com `false`. |
| `PLUGIN_AUTH_ADDRESS` | **Obrigatório se habilitado** | URL do serviço de autenticação do Access Manager. Deve usar HTTPS em produção. Os tokens M2M do CRM e do Fees Engine também vêm deste endereço. |

> [!WARNING]
>
> Quando `PLUGIN_AUTH_ENABLED=true`, o `PLUGIN_AUTH_ADDRESS` deve usar HTTPS em ambientes de produção. O serviço rejeita um endereço HTTP na inicialização.

### Declaração de permissões

Na inicialização, o serviço pode publicar a sua declaração de permissões no Access Manager.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `IDP_DECLARATION_ENABLED` | `false` | Defina `true` para publicar a declaração de permissões na inicialização. |
| `IDP_HOST` | — | URL do serviço Identity do Access Manager. |
| `IDP_M2M_CLIENT_ID` | — | O client ID com que o serviço publica. |
| `IDP_M2M_CLIENT_SECRET` | — | O client secret com que o serviço publica. |

Com `IDP_DECLARATION_ENABLED=true`, o serviço não sobe quando uma das outras três variáveis está vazia, ou quando `PLUGIN_AUTH_ENABLED` não é `true`. Quando o Access Manager recusa a publicação ou não responde, o serviço sobe mesmo assim.

### Escopo da organização

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ORGANIZATION_ID` | **Obrigatório com polling da JD** | UUID da organização Midaz injetado no contexto dos workers em segundo plano (poller de TED IN, conciliação). Ignorado quando `MULTI_TENANT_ENABLED=true`. As requisições HTTP sempre carregam a organização no header `X-Organization-Id` em vez disso. |
| `ORGANIZATION_IDS` | **Obrigatório** | Defina como `global`. Veja [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). Também citada em [Licença](#license). |

```bash theme={null}
# Organization injected into background workers (required when JD polling is enabled)
ORGANIZATION_ID=<your-midaz-organization-uuid>
# Licensing scope validated against LICENSE_KEY
ORGANIZATION_IDS=global
```

### PostgreSQL

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `POSTGRES_HOST` | `localhost` · **Obrigatório** | Host primário do PostgreSQL. |
| `POSTGRES_PORT` | `5432` | Porta primária do PostgreSQL. |
| `POSTGRES_USER` | `plugin-br-bank-transfer` · **Obrigatório** | Usuário do banco de dados. |
| `POSTGRES_PASSWORD` | **Obrigatório em produção** | Senha do banco de dados. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Obrigatório** | Nome do banco de dados. |
| `POSTGRES_SSLMODE` | `require` | Modo SSL. Em produção, deve ser `require`, `verify-ca` ou `verify-full`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Número máximo de conexões abertas. |
| `POSTGRES_MAX_IDLE_CONNS` | `5` | Número máximo de conexões ociosas. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Tempo de vida máximo da conexão em minutos. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tempo máximo de inatividade da conexão em minutos. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `10` | Timeout de conexão em segundos. |

### Réplica do PostgreSQL

Configure uma réplica de leitura para aliviar as consultas. Todos os campos usam os valores do primário quando não definidos.

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

### MongoDB

O serviço usa o MongoDB para persistir os eventos de auditoria das transferências. Ele não sobe sem uma conexão MongoDB válida.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MONGO_ENABLED` | `true` | Habilita a conexão com o MongoDB. Deve ser `true`. |
| `MONGO_URI` | **Obrigatório** | String de conexão do MongoDB (por exemplo `mongodb://user:pass@host:27017`). Em produção, deve incluir credenciais e TLS (`tls=true` ou `mongodb+srv`). |
| `MONGO_DATABASE` | **Obrigatório** | Nome do banco de dados MongoDB. |
| `MONGO_MAX_POOL_SIZE` | `25` | Tamanho máximo do pool de conexões. |
| `MONGO_SERVER_SELECTION_TIMEOUT_MS` | `3000` | Timeout de seleção de servidor em milissegundos. |
| `MONGO_HEARTBEAT_INTERVAL_MS` | `10000` | Intervalo de heartbeat em milissegundos. |
| `MONGO_TLS_CA_CERT` | — | Certificado CA codificado em Base64 para o TLS do MongoDB. Use quando o MongoDB exige TLS com uma CA personalizada (por exemplo Atlas, instâncias privadas com certificados autoassinados). |

### Redis

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

> [!WARNING]
>
> O Redis é uma dependência obrigatória. Ele guarda em cache as chaves de idempotência e detecta duplicatas. Se o Redis estiver indisponível na inicialização ou ficar inacessível em tempo de execução, o serviço se reporta como DOWN à sonda de readiness. Ele então para de aceitar requisições.

### Conexão JD SPB

O plugin valida as variáveis da JD apenas quando `JD_BASE_URL` está definida.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `JD_BASE_URL` | — | URL base da API do JD SPB. |
| `JD_SOAP_PATH` | `/soap` | Caminho do endpoint SOAP da JD. |
| `JD_LEGACY_CODE` | **Obrigatório** | Código do sistema legado da JD (máximo 10 caracteres). |
| `JD_USER_CODE` | **Obrigatório** | Código de usuário da JD (máximo 10 caracteres). |
| `JD_PASSWORD` | **Obrigatório** | Senha da JD. |
| `JD_PRIVATE_KEY_PEM` | **Obrigatório para `local_pem`** | Conteúdo PEM da chave privada RSA (pelo menos 3072 bits) para a assinatura XML, que usa PKCS#1 v1.5 com SHA-256. |
| `JD_PRIVATE_KEY_PEM_FILE` | — | Caminho de um arquivo com o PEM da chave privada RSA. Alternativa a colocar a chave direto em `JD_PRIVATE_KEY_PEM`; lido na inicialização. |
| `JD_PUBLIC_KEY_PEM` | **Obrigatório para `external_provided`** | PEM da chave pública que verifica as assinaturas que o seu sistema fornece. Obrigatório no modo `external_provided` enquanto `jdspb.validate_external_signature` estiver ativo (padrão). |
| `JD_PRIVATE_KEY_KEYINFO` | **Obrigatório ao assinar** | Identificador da chave de assinatura, em hexadecimal: uma impressão digital de certificado de 40 caracteres ou um identificador de chave de 64 caracteres. |
| `JD_CERT_PEM` | — | Certificado X.509 opcional, codificado em PEM, pareado com a chave de assinatura da JD. Usado apenas pelo medidor de métricas de expiração do certificado, não pelo caminho de assinatura; um PEM malformado é um erro de inicialização. |
| `JD_SIGNING_MODE` | `local_pem` | Modo de assinatura SOAP. `local_pem` assina localmente com `JD_PRIVATE_KEY_PEM`. `external_provided` recebe a assinatura que o seu sistema envia para a etapa de processamento. O plugin recusa `disabled` na inicialização enquanto `JD_BASE_URL` estiver definida. |
| `JD_EXTERNAL_SIGNER_URL` | — | No modo `external_provided`, o serviço de assinatura que o plugin chama quando uma requisição de processamento não traz assinatura. |
| `JD_EXTERNAL_SIGNER_AUTH_TOKEN` | — | Token Bearer enviado no header `Authorization` nas chamadas ao assinador externo. |
| `JD_EXTERNAL_SIGNER_TIMEOUT_MS` | `5000` | Timeout (em milissegundos) das chamadas ao assinador externo. |
| `JD_ALLOW_PRIVATE_NETWORK` | `false` | Permite que o adaptador da JD alcance um endereço de rede privada. Os endpoints de metadados da nuvem continuam bloqueados. |
| `JD_SANDBOX_MODE` | `false` | Habilita o modo sandbox da JD. Permitido apenas quando `ENVIRONMENT_NAME` é `local`, `development` ou `test`. |

### Polling da JD

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `JD_POLLING_ENABLED` | `false` | Habilita o worker de polling de TED IN. |
| `JD_POLL_INTERVAL_SECONDS` | `60` | Com que frequência (em segundos) o plugin consulta as TEDs de entrada. |
| `JD_POLL_CYCLE_TIMEOUT_SECONDS` | `0` | Prazo de um ciclo de polling, de 30 a 3600 segundos. `0` deriva o prazo do intervalo. |
| `RECONCILIATION_CYCLE_TIMEOUT_SECONDS` | `0` | Prazo de uma rodada de conciliação, de 30 a 3600 segundos. `0` deriva o prazo do intervalo do worker. |
| `DEVOLUTION_SCAN_CYCLE_TIMEOUT_SECONDS` | `0` | Prazo de uma varredura de devoluções, de 30 a 3600 segundos. `0` deriva o prazo do intervalo da varredura. |

> [!NOTE]
>
> O padrão de `JD_POLLING_ENABLED` é `false`, para deploys mais seguros. Defina `ORGANIZATION_ID` antes de habilitá-lo. Os workers em segundo plano injetam esse valor no contexto das chamadas downstream ao CRM e ao Midaz.

### Serviços externos (Midaz)

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MIDAZ_BASE_URL` | **Obrigatório** | URL do serviço base do Midaz. |
| `MIDAZ_TRANSACTION_URL` | **Obrigatório** | URL do serviço de transações do Midaz. |
| `MIDAZ_TIMEOUT_MS` | `3000` | Timeout das requisições ao Midaz em milissegundos. |
| `MIDAZ_MAX_RETRIES` | `3` | Novas tentativas em caso de falha do Midaz. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita a autenticação M2M para o Midaz. |
| `MIDAZ_AUTH_ADDRESS` | `PLUGIN_AUTH_ADDRESS` | URL do serviço de autenticação para os tokens M2M do Midaz. |
| `MIDAZ_CLIENT_ID` | **Obrigatório se habilitado** | Client ID OAuth para o M2M do Midaz. |
| `MIDAZ_CLIENT_SECRET` | **Obrigatório se habilitado** | Client secret OAuth para o M2M do Midaz. |
| `MIDAZ_FEE_MODE` | `auto` | Quem cobra a tarifa de cada transferência. `legacy`: o plugin-fees, configurado pelas variáveis `FEES_*` abaixo, com lançamentos na API `/v1` do Midaz. `native`: o Fees Engine do Midaz, a partir dos pacotes de tarifas do ledger, com lançamentos na `/v2`. `auto` lê a versão do Midaz e usa `native` no Midaz 4.1.0 ou posterior, e `legacy` em uma versão anterior ou quando a primeira leitura falha. O Bank Transfer não inicia com nenhum outro valor. |
| `MIDAZ_FEE_MODE_REFRESH` | `5m` | A frequência com que `auto` lê de novo a versão do Midaz, como duração Go. A nova leitura acontece na primeira transferência depois desse intervalo, e uma leitura que falha mantém o modo atual. O Bank Transfer não inicia com um valor igual a zero ou menor. |

O Bank Transfer pede ao Midaz que crie um índice de metadata de transação para as suas leituras de correlação. Essa chamada precisa da permissão `settings` `post` do Midaz, nos dois modos de tarifa.

> [!WARNING]
>
> Com o `auto` padrão, o Bank Transfer passa para `native` sozinho assim que lê o Midaz 4.1.0 ou posterior. 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).

### Serviços externos (CRM)

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `CRM_BASE_URL` | **Obrigatório** | URL do ledger do Midaz, que incorpora o CRM. Esta URL deve responder a `GET /version`, ou toda leitura do CRM falha. Deve usar HTTPS em produção. |
| `CRM_TIMEOUT_MS` | `2000` | Timeout das requisições ao CRM em milissegundos. |
| `CRM_MAX_RETRIES` | `2` | Novas tentativas em caso de falha do CRM. |
| `CRM_AUTH_ENABLED` | `false` | Habilita a autenticação M2M para o CRM. |
| `CRM_CLIENT_ID` | **Obrigatório se habilitado** | Client ID OAuth para o M2M do CRM. Esta credencial precisa de acesso de leitura a Titulares e Instrumentos no ledger. |
| `CRM_CLIENT_SECRET` | **Obrigatório se habilitado** | Client secret OAuth para o M2M do CRM. |

### Serviços externos (Fees)

> [!NOTE]
>
> Estas variáveis configuram o plugin-fees e valem apenas quando o modo de tarifa é `legacy`. O `BTF_FEE_ENABLED` liga o plugin-fees. Quando `false` (padrão), o plugin não monta nenhum adaptador do plugin-fees, e cada transferência `legacy` segue com tarifa 0 e sem chamada HTTP. As outras variáveis `FEES_*` entram em vigor apenas quando `BTF_FEE_ENABLED=true`. No modo `native`, o `BTF_FEE_ENABLED` não liga nem desliga tarifas: quem faz isso é o pacote de tarifas do Midaz no ledger.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `BTF_FEE_ENABLED` | `false` | Liga a integração com o plugin-fees, apenas no modo `legacy`. Quando `false`, nenhum adaptador do plugin-fees é montado e cada transferência `legacy` roda com tarifa 0 sem chamadas HTTP. Defina como `true` para cobrar tarifas pelo plugin-fees. No modo `native`, habilite ou desabilite o pacote de tarifas do Midaz em vez disso. |
| `FEES_BASE_URL` | **Obrigatório se habilitado** | URL do serviço do plugin-fees. Deve usar HTTPS em produção. |
| `FEES_TIMEOUT_MS` | `2000` | Timeout das requisições de tarifa em milissegundos. |
| `FEES_MAX_RETRIES` | `2` | Novas tentativas em caso de falha do serviço de tarifas. |
| `FEES_AUTH_ENABLED` | `false` | Habilita a autenticação M2M para o Fees. |
| `FEES_CLIENT_ID` | **Obrigatório se habilitado** | Client ID OAuth para o M2M do Fees. |
| `FEES_CLIENT_SECRET` | **Obrigatório se habilitado** | Client secret OAuth para o M2M do Fees. |

### JD Courier

Estas variáveis conectam o plugin ao JD Courier, que faz o relay das [transferências entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md) para o outro core da sua instituição. No modo multi-tenant, o plugin não usa `COURIER_BASE_URL`, `COURIER_CLIENT_ID` nem `COURIER_CLIENT_SECRET`.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `COURIER_BASE_URL` | — | URL do JD Courier. Deve usar HTTPS em produção. |
| `COURIER_CLIENT_ID`, `COURIER_CLIENT_SECRET` | **Obrigatórios em produção quando `COURIER_BASE_URL` está definida** | Credenciais de cliente OAuth para o JD Courier. Defina as duas ou nenhuma. Elas precisam de `PLUGIN_AUTH_ADDRESS`. |
| `COURIER_ACCOUNT_CLAIMS_ENABLED` | `false` | Reivindica as contas deste motor no mapa de titularidade do JD Courier. Precisa de `CRM_BASE_URL` e `PLUGIN_AUTH_ADDRESS`. No modo single-tenant, também precisa de `COURIER_BASE_URL`, `COURIER_CLIENT_ID`, `COURIER_CLIENT_SECRET` e `ORGANIZATION_ID`. |

### RabbitMQ

Quando o streaming está habilitado, o plugin pode fazer fan-out dos eventos de ciclo de vida das transferências para o RabbitMQ, para os consumidores downstream.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `RABBITMQ_ENABLED` | `false` | Adiciona o RabbitMQ como destino de fan-out do ciclo de vida das transferências. A publicação exige `STREAMING_ENABLED=true`. |
| `RABBITMQ_URL` | **Obrigatório se habilitado** | URL de conexão AMQP. `amqp://` é permitido apenas quando `ENVIRONMENT_NAME` é `development`, `test` ou `local`, ou para um host de loopback. |
| `RABBITMQ_HEALTH_CHECK_URL` | — | URL HTTP(S) do endpoint de health da administração do RabbitMQ. O hostname deve corresponder ao de `RABBITMQ_URL`; deve usar `https://` em produção. |
| `RABBITMQ_EXCHANGE` | `bank_transfer.lifecycle` | Nome do exchange dos eventos de ciclo de vida. |
| `RABBITMQ_EVENT_SIGNING_SECRET` | — | Segredo HMAC para assinar os eventos publicados. Recorre ao `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` e depois ao `WEBHOOK_SIGNING_SECRET`. O segredo em vigor deve ter pelo menos 32 caracteres. |

### Outbox de streaming

O subsistema de streaming publica os eventos de transferência no tópico único da aplicação `lerian.streaming.plugin-br-bank-transfer` em um broker Redpanda/Kafka, por meio de um outbox transacional. Você deve habilitá-lo para a entrega de webhooks de saída (`WEBHOOK_ENABLED=true` exige `STREAMING_ENABLED=true`). Enquanto o streaming está desligado, o plugin descarta os eventos: ligá-lo depois publica apenas os eventos novos.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Habilita o subsistema de outbox de streaming. Obrigatório para a entrega de webhooks. |
| `STREAMING_BROKERS` | **Obrigatório se habilitado** | Lista separada por vírgulas de endereços de brokers Kafka/Redpanda. |
| `STREAMING_CLIENT_ID` | — | Client ID apresentado ao broker. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `plugin-br-bank-transfer` | Sobreposição opcional do `source` do CloudEvents. Deixe sem definir para usar `plugin-br-bank-transfer`; se definida, deve corresponder exatamente a esse valor, mesmo com o streaming desabilitado. |
| `STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS` | `30` | Intervalo (em segundos) entre os ciclos de despacho do outbox. Deve ser > 0. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Proporção de falhas que dispara o circuit breaker (deve ser > 0 e ≤ 1). |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Número mínimo de requisições em uma janela antes de o circuit breaker poder disparar. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Timeout de recuperação do circuit breaker em segundos. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Timeout de desligamento gracioso (em segundos) do produtor de streaming. |
| `STREAMING_TLS_ENABLED` | `false` | Usa TLS na conexão com o broker. Deve ser `true` quando `DEPLOYMENT_MODE=saas`. |
| `STREAMING_TLS_CA_CERT` | — | Certificado CA para a conexão TLS com o broker. |
| `STREAMING_SASL_MECHANISM`, `STREAMING_SASL_USERNAME`, `STREAMING_SASL_PASSWORD` | — | Autenticação SASL no broker. |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Permite SASL sem TLS. |

### Entrega de webhooks

A entrega de webhooks de saída exige o RabbitMQ e o outbox de streaming. O worker de webhook consome os eventos de uma fila do RabbitMQ e os entrega aos endpoints dos assinantes.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `WEBHOOK_ENABLED` | `false` | Habilita a entrega de webhooks de saída. Exige `RABBITMQ_ENABLED=true` e `STREAMING_ENABLED=true`. |
| `WEBHOOK_SIGNING_SECRET` | — | Último recurso para o segredo dos eventos do broker. Não assina as entregas: cada registro de webhook assina com o próprio `signingSecret`. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | **Obrigatório em produção se habilitado** | Segredo HMAC para verificar os eventos do broker. Recorre ao `WEBHOOK_SIGNING_SECRET`. |
| `WEBHOOK_QUEUE_NAME` | `transfer.webhook.delivery` | Nome da fila do RabbitMQ para os eventos de webhook. |
| `WEBHOOK_DLQ_NAME` | `transfer.webhook.dlq` | Fila dead-letter para as entregas de webhook que falharam. |
| `WEBHOOK_DLX_EXCHANGE_NAME` | — | Nome do exchange dead-letter. Quando vazio, o worker deriva `<WEBHOOK_DLQ_NAME>.exchange`. Sobreponha para centralizar o DLX entre plugins. |
| `WEBHOOK_DLQ_MESSAGE_TTL_MS` | `0` | `x-message-ttl` da DLQ em milissegundos. `0` usa o padrão da biblioteca (7 dias). Mudanças de topologia exigem apagar a DLQ existente antes do novo deploy. |
| `WEBHOOK_DLQ_MAX_LENGTH` | `0` | Contagem máxima de mensagens na DLQ. `0` usa o padrão da biblioteca (10000). |
| `WEBHOOK_PREFETCH_COUNT` | `20` | Contagem de prefetch do RabbitMQ. |
| `WEBHOOK_DELIVERY_CONCURRENCY` | `8` | Número máximo de entregas simultâneas de webhook por worker. |

### Telemetria (OpenTelemetry)

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | Habilita o tracing e as métricas do OpenTelemetry. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | Endpoint gRPC do coletor OTel. |
| `OTEL_TRACES_SAMPLER_ARG` | — | Proporção de amostragem de traces. Um valor em (0,1] é aplicado como definido. Sem definir, ou com um valor de 0 ou menos, usa `0.1` em produção e `1.0` nos demais ambientes. Um valor acima de 1 conta como `1.0`. |
| `BTF_METRICS_PROMETHEUS_ENABLED` | `false` | Expõe um endpoint de scrape do Prometheus dedicado às métricas `btf.*`. Quando `true`, o listener em `BTF_METRICS_PROMETHEUS_ADDRESS` sobe. |
| `BTF_METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9090` | Endereço de escuta do endpoint `/metrics` do Prometheus. O padrão liga no loopback, para que um pod mal configurado não exponha métricas sem autenticação à rede do cluster. Sobreponha (por exemplo `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` | **Obrigatório** | Chave de licença. O serviço não sobe sem ela, em nenhum ambiente. |
| `IS_DEVELOPMENT` | — | Deixe sem valor ou `false` e use um `LICENSE_KEY` de produção emitido pela Lerian. O Bank Transfer v3.4.0 lê essa variável: `true` seleciona o serviço de licenças de desenvolvimento. Veja [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). |
| `ORGANIZATION_IDS` | **Obrigatório** | A mesma variável de [Escopo da organização](#organization-scope). Defina como `global`. |

### Criptografia

Criptografia no nível de campo para os dados sensíveis em repouso. Cada chave deve ser uma chave AES-256 de 32 bytes codificada em hexadecimal (64 caracteres hexadecimais). As duas chaves são obrigatórias em produção. Fora de produção, uma chave vazia desabilita a criptografia daquele campo.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `JD_INCOMING_RAW_XML_ENCRYPTION_KEY` | — | Chave AES-256 para criptografar os payloads XML de entrada da JD. Use uma chave de 32 bytes em hexadecimal. Mantenha-a estável entre upgrades: uma chave alterada torna ilegíveis os registros que a chave anterior criptografou. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | Chave AES-256 para criptografar os dados do destinatário em repouso. Use uma chave de 32 bytes em hexadecimal. Mantenha-a estável entre upgrades: uma chave alterada torna ilegíveis os registros que a chave anterior criptografou. |


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