> ## 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](/pt/interfaces/ted-jd/ted-configuration).
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 |
| ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENV_NAME` | `development` | Ambiente (`development`, `staging`, `production`) |
| `DEPLOYMENT_MODE` | `byoc` | Variante de deploy. `byoc` = Bring Your Own Cloud (single-tenant, gerenciado pelo operador). Alterna comportamentos internos entre SaaS e 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 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. Os endpoints de metadados da nuvem continuam bloqueados independentemente deste flag. |
### 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 `plugin-auth`. Configure a conexão com as variáveis abaixo.
| Variável | Padrão / Obrigatório | Descrição |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `false` | Habilita a autorização via plugin-auth. Defina como `true` em produção. |
| `PLUGIN_AUTH_ADDRESS` | **Obrigatório se habilitado** | URL do serviço plugin-auth. Deve usar HTTPS em produção. |
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.
### Admin de teste (apenas fora de produção)
O `BTF_TEST_ADMIN_ENABLED` deve continuar `false` em produção. Ele expõe endpoints administrativos exclusivos de teste (por exemplo `POST /admin/test/circuit-breakers/reset`) que não carregam tenant e contornam a autenticação de produção. Apenas a mock-lane do docker-compose o habilita, para testes E2E. Qualquer deploy com este flag em `true` fora de uma rede de teste isolada é um erro de configuração.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_TEST_ADMIN_ENABLED` | `false` | ⚠️ Expõe endpoints administrativos exclusivos de teste. Deve continuar `false` em produção. |
| `BTF_TEST_ADMIN_TOKEN` | **Obrigatório se o admin estiver habilitado** | Token obrigatório quando `BTF_TEST_ADMIN_ENABLED=true`. Enviado no header `X-Test-Admin-Token`. Separado de propósito da autenticação de produção (superfície exclusiva de teste, sem tenant). |
### Idempotência
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------------- |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | `300` | Janela de tempo (em segundos) durante a qual uma chave de idempotência é válida. |
Multi-tenancy
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MULTI_TENANT_ENABLED` | `false` | Habilita multi-tenancy no nível de infraestrutura com bancos de dados isolados por tenant. |
| `ORGANIZATION_ID` | **Obrigatório (single-tenant + polling da JD)** | UUID da organização Midaz injetado no contexto dos workers em segundo plano (poller de TED IN, conciliação) no modo single-tenant. Obrigatório quando `MULTI_TENANT_ENABLED=false` e `JD_POLLING_ENABLED=true`. Ignorado no modo multi-tenant, em que 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` em vez disso. |
| `AWS_REGION` | **Obrigatório se o backend de segredos for AWS** | Região AWS para as leituras de segredos por tenant no Secrets Manager. Obrigatória quando `MULTI_TENANT_ENABLED=true` e o backend de segredos é a AWS. |
| `ORGANIZATION_IDS` | **Obrigatório em produção** | Lista separada por vírgulas de UUIDs de organizações Midaz no escopo de licenciamento. O gateway de licença valida o `LICENSE_KEY` contra elas na inicialização. Também citada em [Licença](#license). |
| `MULTI_TENANT_URL` | **Obrigatório quando habilitado** | URL do serviço da plataforma de multi-tenancy. |
| `MULTI_TENANT_REDIS_HOST` | — | Host do Redis para a 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 a conexão Pub/Sub do Redis. |
| `MULTI_TENANT_REDIS_CA_CERT` | — | Certificado CA para a conexão TLS Pub/Sub do Redis multi-tenant. |
| `MULTI_TENANT_TIMEOUT` | `30` | Timeout HTTP em segundos para as chamadas ao serviço de multi-tenancy. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Número máximo de pools simultâneos de conexão a bancos de tenants. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Timeout de inatividade em segundos antes de descartar o pool de um tenant. |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Número de falhas antes de o 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ório 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 em memória da configuração de tenant. Recarregável a quente pela API do systemplane. |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Intervalo assíncrono em segundos para revalidar as configurações do pool. Apenas no bootstrap (não recarregável a quente). |
**BYOC single-tenant:**
```bash theme={null}
# Organization injected into background workers (required when JD polling is enabled)
ORGANIZATION_ID=
# Licensing scope validated against LICENSE_KEY in production
ORGANIZATION_IDS=
```
**SaaS multi-tenant:**
```bash theme={null}
MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=http://tenant-manager:4003
MULTI_TENANT_SERVICE_API_KEY=your-api-key
MULTI_TENANT_REDIS_HOST=redis.example.com
```
### 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** | Senha do banco de dados. Obrigatória em produção. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Obrigatório** | Nome do banco de dados. |
| `POSTGRES_SSLMODE` | `require` | Modo SSL. `disable` é rejeitado em produção. |
| `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. |
### MongoDB
O serviço exige 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` · **Obrigatório** | Habilita a conexão com o MongoDB. Deve ser `true` em todos os ambientes. |
| `MONGO_URI` | **Obrigatório** | String de conexão do MongoDB (por exemplo `mongodb://user:pass@host:27017`). Deve incluir credenciais e TLS em produção. |
| `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. |
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
Você deve definir estas variáveis em deploys BYOC. No modo SaaS, a Lerian gerencia a conexão com a JD.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obrigatório para BYOC** | URL base da API do JD SPB. |
| `JD_SOAP_PATH` | `/soap` | Caminho do endpoint SOAP da JD. |
| `JD_LEGACY_CODE` | **Obrigatório para BYOC** | Código do sistema legado da JD (máximo 10 caracteres). |
| `JD_USER_CODE` | **Obrigatório para BYOC** | Código de usuário da JD (máximo 10 caracteres). |
| `JD_PASSWORD` | **Obrigatório para BYOC** | Senha da JD (criptografada em repouso). |
| `JD_PRIVATE_KEY_PEM` | **Obrigatório para BYOC** | Conteúdo PEM da chave privada RSA para a assinatura XML. |
| `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` | — | PEM da chave pública para validar as assinaturas nas respostas da JD. |
| `JD_PRIVATE_KEY_KEYINFO` | — | Bloco XML `` embutido na assinatura SOAP (por exemplo, certificado X509 codificado em base64). Obrigatório para o envelope WS-Security quando a JD exige identificação por certificado. |
| `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_signer` delega a um serviço remoto via `JD_EXTERNAL_SIGNER_URL`. |
| `JD_EXTERNAL_SIGNER_URL` | **Obrigatório se `JD_SIGNING_MODE=external_signer`** | URL base do serviço externo de 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_SANDBOX_MODE` | `false` | Habilita o modo sandbox da JD. Rejeitado em produção. |
### 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. |
O padrão de `JD_POLLING_ENABLED` é `false`, para deploys mais seguros. No modo single-tenant, 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. No modo multi-tenant, o gerenciador de pollers de TED IN encontra cada tenant ativo pelo serviço da plataforma de multi-tenancy. Ele então sobe um poller por tenant e resolve a configuração JD de cada tenant.
### 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` | **Obrigatório se habilitado** | 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. |
### Serviços externos (CRM)
| Variável | Padrão / Obrigatório | Descrição |
| ------------------- | ----------------------------- | ------------------------------------------------ |
| `CRM_BASE_URL` | **Obrigatório** | URL do serviço de CRM. |
| `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. |
| `CRM_CLIENT_SECRET` | **Obrigatório se habilitado** | Client secret OAuth para o M2M do CRM. |
### Serviços externos (Fees)
O `BTF_FEE_ENABLED` é a chave mestra. Quando `false` (padrão), o plugin não monta nenhum adaptador do Fees e cada transferência segue com fee=0 e sem chamada HTTP. As outras variáveis `FEES_*` entram em vigor apenas quando `BTF_FEE_ENABLED=true`.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTF_FEE_ENABLED` | `false` | Chave mestra da integração com o plugin-fees. Quando `false`, nenhum adaptador do Fees é montado e todas as transferências rodam com fee=0 sem chamadas HTTP. Os operadores que rodam o plugin-fees devem defini-la como `true` explicitamente. |
| `FEES_BASE_URL` | **Obrigatório se habilitado** | URL do serviço do Fees Engine. |
| `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. |
### 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. Deve usar `amqps://` fora de desenvolvimento. |
| `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` | **Obrigatório se habilitado** | Segredo HMAC para assinar os eventos publicados. Mínimo de 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`).
| 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. |
### 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` | **Obrigatório se habilitado** | Segredo HMAC para assinar os payloads de webhook. Mínimo de 32 caracteres. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | — | Segredo HMAC separado 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 `.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 (0.0–1.0). Sem definir, usa o sampler padrão resolvido na inicialização da telemetria: `0.1` em produção, `1.0` nos demais ambientes. Valores fora de (0,1] são limitados a 1.0, para que um erro de configuração não desabilite silenciosamente o tracing em produção. |
| `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 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ório em produção** | A mesma variável de [Multi-tenancy](#multi-tenancy). Lista separada por vírgulas de UUIDs de organizações Midaz no escopo de licenciamento; o gateway de licença valida o `LICENSE_KEY` contra elas na inicialização. |
### 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). Deixe uma chave vazia para desabilitar 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. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | Chave AES-256 para criptografar os dados do destinatário em repouso. |