> ## 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
> Variáveis de ambiente definidas no deploy do plugin Bank Transfer — infraestrutura, persistência, integrações e segurança.
Estas são variáveis definidas no momento do deploy pela equipe de DevOps; alterações exigem reiniciar o serviço. As configurações de runtime e de negócio ficam em [Configuração](/pt/rails/ted/jd/ted-configuration).
Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (ex: **Obrigatória**, **Obrigatória em produção**, **Obrigatória se habilitado**) marca variáveis que devem ser definidas. `—` significa que não há padrão.
## 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ória | Descrição |
| ------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENV_NAME` | `development` | Ambiente (`development`, `staging`, `production`) |
| `DEPLOYMENT_MODE` | `byoc` | Sabor de deployment. `byoc` = Bring Your Own Cloud (single-tenant, gerenciado pelo operador). Aciona comportamentos internos SaaS vs. BYOC. |
| `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 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ória | Descrição |
| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| `SERVER_TLS_CERT_FILE` | — | Caminho para o arquivo de certificado TLS. Deve ser definido junto com `SERVER_TLS_KEY_FILE`. |
| `SERVER_TLS_KEY_FILE` | — | Caminho para o arquivo de 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
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ória | Descrição |
| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_PROXY_HEADER` | — | 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` | **Obrigatória se proxy header definido** | Lista separada por vírgula de IPs/CIDRs de proxies confiáveis. Obrigatória quando `SERVER_PROXY_HEADER` está definido para evitar spoofing de IP. |
### 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ória | Descrição |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `false` | Habilita a autorização via plugin-auth. Defina como `true` em produção. |
| `PLUGIN_AUTH_ADDRESS` | **Obrigatória se habilitado** | URL do serviço plugin-auth. Deve usar HTTPS em produção. |
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ória | Descrição |
| ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_TEST_ADMIN_ENABLED` | `false` | ⚠️ Expõe endpoints administrativos apenas de teste. Deve permanecer `false` em produção. |
| `BTF_TEST_ADMIN_TOKEN` | **Obrigatória 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). |
### Idempotência
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------------------------- |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | `300` | Janela de tempo (em segundos) durante a qual uma chave de idempotência é considerada válida. |
### Multi-tenancy
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_ENABLED` | `false` | Habilita multi-tenancy em nível de infraestrutura com bancos de dados isolados por tenant. |
| `ORGANIZATION_ID` | **Obrigatória (single-tenant + polling JD)** | UUID de organização Midaz injetado no contexto dos workers em segundo plano (poller de TED IN, reconciliação) em modo single-tenant. Obrigatória quando `MULTI_TENANT_ENABLED=false` e `JD_POLLING_ENABLED=true`. Ignorada em modo multi-tenant, onde os vínculos de organização por tenant são resolvidos pelo tenant manager. As requisições HTTP sempre carregam a organização no header `X-Organization-Id`. |
| `AWS_REGION` | **Obrigatória se backend de secretos AWS** | Região AWS para leituras de secretos por tenant no Secrets Manager. Obrigatória quando `MULTI_TENANT_ENABLED=true` e o backend de secretos é AWS. |
| `ORGANIZATION_IDS` | **Obrigatória em produção** | Lista de UUIDs de organização Midaz no escopo de licenciamento, separados por vírgula. O gateway de licença valida `LICENSE_KEY` contra estes na inicialização. Também referenciada em [Licença](#licença). |
| `MULTI_TENANT_URL` | **Obrigatória quando habilitado** | URL do serviço da plataforma de multi-tenancy. |
| `MULTI_TENANT_REDIS_HOST` | — | Host Redis para descoberta de tenants orientada a eventos via Pub/Sub. |
| `MULTI_TENANT_REDIS_PORT` | `6379` | Porta do Redis para Pub/Sub. |
| `MULTI_TENANT_REDIS_PASSWORD` | — | Senha do Redis para Pub/Sub. |
| `MULTI_TENANT_REDIS_TLS` | `false` | Habilita TLS para conexão Redis Pub/Sub. |
| `MULTI_TENANT_REDIS_CA_CERT` | — | Certificado CA para a conexão TLS do Redis Pub/Sub multi-tenant. |
| `MULTI_TENANT_TIMEOUT` | `30` | Timeout HTTP em segundos para chamadas ao serviço de multi-tenancy. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Máximo de pools de conexão de banco simultâneos por tenant. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Timeout de inatividade em segundos antes de descartar um pool de tenant. |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Número de falhas antes do circuit breaker abrir. |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Timeout de recuperação em segundos do circuit breaker. |
| `MULTI_TENANT_SERVICE_API_KEY` | **Obrigatória quando habilitado** | Chave de API para o endpoint `/settings` do serviço de multi-tenancy. |
| `MULTI_TENANT_CACHE_TTL_SEC` | `120` | TTL em segundos do cache in-memory de configuração de tenant. Recarregável a quente via systemplane API. |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo assíncrono em segundos para revalidação de configurações de pool. Somente bootstrap (não recarregável a quente). |
**BYOC single-tenant:**
```bash theme={null}
# Organização injetada nos workers em segundo plano (obrigatória quando o polling JD está habilitado)
ORGANIZATION_ID=
# Escopo de licenciamento validado contra LICENSE_KEY em produção
ORGANIZATION_IDS=
```
**SaaS multi-tenant:**
```bash theme={null}
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ória | Descrição |
| ---------------------------------- | ------------------------------------------- | ------------------------------------------------- |
| `POSTGRES_HOST` | `localhost` · **Obrigatória** | Host primário do PostgreSQL. |
| `POSTGRES_PORT` | `5432` | Porta primária do PostgreSQL. |
| `POSTGRES_USER` | `plugin-br-bank-transfer` · **Obrigatória** | Usuário do banco de dados. |
| `POSTGRES_PASSWORD` | **Obrigatória** | Senha do banco de dados. Obrigatória em produção. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Obrigatória** | Nome do banco de dados. |
| `POSTGRES_SSLMODE` | `require` | Modo SSL. `disable` é rejeitado em produção. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Máximo de conexões abertas. |
| `POSTGRES_MAX_IDLE_CONNS` | `5` | Máximo de conexões ociosas. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Tempo máximo de vida da conexão em minutos. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Tempo máximo ocioso da conexão em minutos. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `10` | Timeout de conexão em segundos. |
### 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ória | 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 da réplica. |
| `POSTGRES_REPLICA_SSLMODE` | — | 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ória | Descrição |
| ----------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MONGO_ENABLED` | `true` · **Obrigatória** | Habilita a conexão MongoDB. Deve ser `true` em todos os ambientes. |
| `MONGO_URI` | **Obrigatória** | String de conexão MongoDB (ex: `mongodb://user:pass@host:27017`). Deve incluir credenciais e TLS em produção. |
| `MONGO_DATABASE` | **Obrigatória** | 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 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ória | Descrição |
| ------------------------ | ---------------------------------- | --------------------------------------------------- |
| `REDIS_HOST` | `localhost:6379` · **Obrigatória** | Host e porta do Redis. |
| `REDIS_MASTER_NAME` | — | Nome do master Redis Sentinel (se usando Sentinel). |
| `REDIS_PASSWORD` | — | Senha do Redis (se autenticação habilitada). |
| `REDIS_DB` | `0` | Número do banco de dados Redis. |
| `REDIS_PROTOCOL` | `3` | Versão do protocolo Redis (2 ou 3). |
| `REDIS_TLS` | `false` | Habilita TLS para conexões Redis. |
| `REDIS_CA_CERT` | — | Certificado CA para TLS Redis. |
| `REDIS_POOL_SIZE` | `10` | Tamanho do pool de conexões. |
| `REDIS_MIN_IDLE_CONNS` | `2` | 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 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ória | Descrição |
| ------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obrigatória no BYOC** | URL base da API JD SPB. |
| `JD_SOAP_PATH` | `/soap` | Caminho do endpoint SOAP JD. |
| `JD_LEGACY_CODE` | **Obrigatória no BYOC** | Código legado JD (máx. 10 chars). |
| `JD_USER_CODE` | **Obrigatória no BYOC** | Código de usuário JD (máx. 10 chars). |
| `JD_PASSWORD` | **Obrigatória no BYOC** | Senha JD (criptografada em repouso). |
| `JD_PRIVATE_KEY_PEM` | **Obrigatória no BYOC** | Conteúdo PEM da chave privada RSA para assinatura XML. |
| `JD_PRIVATE_KEY_PEM_FILE` | — | Caminho para um arquivo contendo o PEM da chave privada RSA. Alternativa a inserir a chave inline em `JD_PRIVATE_KEY_PEM`; lido na inicialização. |
| `JD_PUBLIC_KEY_PEM` | — | PEM de chave pública para validar assinaturas em respostas do JD. |
| `JD_PRIVATE_KEY_KEYINFO` | — | Bloco XML `` 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_CERT_PEM` | — | Certificado X.509 codificado em PEM opcional pareado com a chave de assinatura JD. Usado apenas pelo gauge de métricas de expiração de 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_signer` delega a um serviço remoto via `JD_EXTERNAL_SIGNER_URL`. |
| `JD_EXTERNAL_SIGNER_URL` | **Obrigatória se `JD_SIGNING_MODE=external_signer`** | URL base do serviço de assinatura externo. |
| `JD_EXTERNAL_SIGNER_AUTH_TOKEN` | — | Bearer token enviado no header `Authorization` para chamadas ao assinador externo. |
| `JD_EXTERNAL_SIGNER_TIMEOUT_MS` | `5000` | Timeout (em milissegundos) para chamadas ao assinador externo. |
| `JD_SANDBOX_MODE` | `false` | Habilita modo sandbox JD. Rejeitado em produção. |
### Polling JD
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------- | -------------------- | ---------------------------------------------------------- |
| `JD_POLLING_ENABLED` | `false` | Habilita worker de polling TED IN. |
| `JD_POLL_INTERVAL_SECONDS` | `60` | Frequência (em segundos) de verificação de TEDs recebidos. |
`JD_POLLING_ENABLED` é desabilitado por padrão para deployments mais seguros. Em modo single-tenant, configure `ORGANIZATION_ID` antes de habilitá-lo — os workers em segundo plano o injetam no contexto para chamadas downstream ao CRM/Midaz. Em modo multi-tenant, o gerenciador do poller de TED IN inicia um poller por tenant ativo descoberto através do serviço da plataforma de multi-tenancy e resolve a configuração JD de cada tenant via o resolvedor de integração do tenant.
### Serviços externos (Midaz)
| Variável | Padrão / Obrigatória | Descrição |
| ----------------------- | ----------------------------- | ----------------------------------------------------- |
| `MIDAZ_BASE_URL` | **Obrigatória** | URL base do serviço Midaz. |
| `MIDAZ_TRANSACTION_URL` | **Obrigatória** | URL do serviço de transações Midaz. |
| `MIDAZ_TIMEOUT_MS` | `3000` | Timeout de requisições Midaz em milissegundos. |
| `MIDAZ_MAX_RETRIES` | `3` | Tentativas de retry em falha do Midaz. |
| `MIDAZ_AUTH_ENABLED` | `false` | Habilita autenticação M2M para Midaz. |
| `MIDAZ_AUTH_ADDRESS` | **Obrigatória se habilitado** | URL do serviço de autenticação para tokens M2M Midaz. |
| `MIDAZ_CLIENT_ID` | **Obrigatória se habilitado** | OAuth client ID para M2M Midaz. |
| `MIDAZ_CLIENT_SECRET` | **Obrigatória se habilitado** | OAuth client secret para M2M Midaz. |
### Serviços externos (CRM)
| Variável | Padrão / Obrigatória | Descrição |
| ------------------- | ----------------------------- | -------------------------------------------- |
| `CRM_BASE_URL` | **Obrigatória** | URL do serviço CRM. |
| `CRM_TIMEOUT_MS` | `2000` | Timeout de requisições CRM em milissegundos. |
| `CRM_MAX_RETRIES` | `2` | Tentativas de retry em falha do CRM. |
| `CRM_AUTH_ENABLED` | `false` | Habilita autenticação M2M para CRM. |
| `CRM_CLIENT_ID` | **Obrigatória se habilitado** | OAuth client ID para M2M CRM. |
| `CRM_CLIENT_SECRET` | **Obrigatória se habilitado** | OAuth client secret para M2M 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ória | Descrição |
| -------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_FEE_ENABLED` | `false` | 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` | **Obrigatória se habilitado** | URL do serviço Fees Engine. |
| `FEES_TIMEOUT_MS` | `2000` | Timeout de requisições de tarifas em milissegundos. |
| `FEES_MAX_RETRIES` | `2` | Tentativas de retry em falha do serviço de tarifas. |
| `FEES_AUTH_ENABLED` | `false` | Habilita autenticação M2M para Fees. |
| `FEES_CLIENT_ID` | **Obrigatória se habilitado** | OAuth client ID para M2M Fees. |
| `FEES_CLIENT_SECRET` | **Obrigatória se habilitado** | OAuth client secret para M2M Fees. |
### RabbitMQ
Eventos de ciclo de vida de transferência podem ser publicados no RabbitMQ para consumidores downstream.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `RABBITMQ_ENABLED` | `false` | Habilita publicação de eventos de ciclo de vida de transferência. |
| `RABBITMQ_URL` | **Obrigatória se habilitado** | URL de conexão AMQP. Deve usar `amqps://` fora de desenvolvimento. |
| `RABBITMQ_HEALTH_CHECK_URL` | — | URL HTTP(S) do endpoint de health do management do RabbitMQ. O hostname deve corresponder ao `RABBITMQ_URL`; deve usar `https://` em produção. |
| `RABBITMQ_EXCHANGE` | `bank_transfer.lifecycle` | Nome do exchange para eventos de ciclo de vida. |
| `RABBITMQ_EVENT_SIGNING_SECRET` | **Obrigatória se habilitado** | Segredo HMAC para assinatura de eventos publicados. Mínimo 32 caracteres. |
### Streaming outbox
O subsistema de streaming publica eventos de transferência em um broker Redpanda/Kafka via um outbox transacional. Ele deve estar habilitado para que a entrega de webhooks de saída funcione (`WEBHOOK_ENABLED=true` requer `STREAMING_ENABLED=true`).
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------- |
| `STREAMING_ENABLED` | `false` | Habilita o subsistema de streaming outbox. Obrigatório para entrega de webhooks. |
| `STREAMING_BROKERS` | **Obrigatória se habilitado** | Lista separada por vírgula de endereços de broker Kafka/Redpanda. |
| `STREAMING_CLIENT_ID` | — | Client ID apresentado ao broker. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Obrigatória se habilitado** | Atributo `source` do CloudEvents definido nos eventos publicados. |
| `STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS` | `30` | Intervalo (em segundos) entre ciclos de dispatch do outbox. Deve ser > 0. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Razão de falhas do circuit breaker que dispara o breaker (deve ser > 0 e ≤ 1). |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Mínimo de requisições em uma janela antes que o circuit breaker possa disparar. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Timeout de recuperação do circuit breaker em segundos. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Timeout de shutdown gracioso (em segundos) para o produtor de streaming. |
### Entrega de webhooks
A entrega de webhooks de saída requer que tanto o RabbitMQ quanto o streaming outbox estejam habilitados. O worker de webhook consome eventos de uma fila RabbitMQ e os entrega aos endpoints dos assinantes.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_ENABLED` | `false` | Habilita entrega de webhooks de saída. Requer `RABBITMQ_ENABLED=true` e `STREAMING_ENABLED=true`. |
| `WEBHOOK_SIGNING_SECRET` | **Obrigatória se habilitado** | Segredo HMAC para assinar payloads de webhook. Mínimo 32 caracteres. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | — | Segredo HMAC separado para verificar eventos do broker. Usa `WEBHOOK_SIGNING_SECRET` como fallback. |
| `WEBHOOK_QUEUE_NAME` | `transfer.webhook.delivery` | Nome da fila RabbitMQ para eventos de webhook. |
| `WEBHOOK_DLQ_NAME` | `transfer.webhook.dlq` | Fila de dead-letter para entregas de webhook falhas. |
| `WEBHOOK_DLX_EXCHANGE_NAME` | — | Nome do exchange de dead-letter. Quando vazio, o worker deriva `.exchange`. Sobrescreva para centralizar o DLX entre plugins. |
| `WEBHOOK_DLQ_MESSAGE_TTL_MS` | `0` | `x-message-ttl` na DLQ em milissegundos. `0` usa o padrão da biblioteca (7 dias). Mudanças de topologia exigem deletar a DLQ existente antes do redeploy. |
| `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 RabbitMQ. |
| `WEBHOOK_DELIVERY_CONCURRENCY` | `8` | Máximo de entregas de webhook concorrentes por worker. |
### Telemetria (OpenTelemetry)
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENABLE_TELEMETRY` | `false` | Habilita tracing e métricas OpenTelemetry. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | Endpoint gRPC do coletor OTel. |
| `OTEL_TRACES_SAMPLER_ARG` | — | 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` | 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` | 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ória | Descrição |
| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `LICENSE_KEY` | **Obrigatória em produção** | Chave de licença. Obrigatória em ambientes de produção. |
| `LICENSE_SERVICE_ADDRESS` | — | URL do serviço de validação de licença. |
| `ORGANIZATION_IDS` | **Obrigatória em produção** | Mesma variável de [Multi-tenancy](#multi-tenancy). Lista de UUIDs de organização Midaz no escopo de licenciamento, separados por vírgula; o gateway de licença valida `LICENSE_KEY` contra estes na inicialização. |
### 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ória | Descrição |
| ------------------------------------ | -------------------- | ----------------------------------------------------------------------- |
| `JD_INCOMING_RAW_XML_ENCRYPTION_KEY` | — | Chave AES-256 para criptografia de payloads XML JD recebidos. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | Chave AES-256 para criptografia de detalhes do destinatário em repouso. |