> ## 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 rail Pix Indireto, via BTG — integração com a BTG e mTLS, a convenção de datastore `DB_*`, vínculos Midaz/CRM/Fee, webhooks internos e componentes de worker.
O Pix Indireto, via BTG alcança o arranjo Pix através da BTG como participante direto. Ele é entregue como vários componentes — uma API mais workers de reconciliação, agenda e webhooks de entrada/saída — cada um configurado através de variáveis de ambiente definidas no momento do deploy pela equipe de DevOps; alterar uma exige a reinicialização daquele componente. Esta página cobre as variáveis **distintivas deste rail** — para os parâmetros de multi-tenancy, streaming, telemetria e autenticação compartilhados entre todos os serviços Go da Lerian, consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (por exemplo **Obrigatória**) marca variáveis que você deve definir. `—` significa que não há padrão. `🔒` marca um **segredo** — injete-o no momento do deploy a partir do seu secret store, nunca faça commit dele. Esta página lista apenas nomes de variáveis e comportamento; ela não imprime nenhum valor de segredo.
Este rail **não** monta a API de administração do systemplane. Suas variáveis de datastore usam um prefixo `DB_*` em vez do formato compartilhado `POSTGRES_*` — consulte [Datastores](#datastores) abaixo.
## Componentes e portas
O componente de API escuta em `SERVER_PORT` (padrão `4014`; `SERVER_ADDRESS` deriva dele). Os workers de reconciliação, agenda e webhook cada um se vincula a um `WORKER_PORT` para suas probes de saúde e carrega seus próprios parâmetros de tuning extensivos (tamanhos de batch, intervalos de polling, concorrência e circuit breakers) em seus respectivos arquivos `.env.example`. Consulte [Portas de rede padrão](/pt/reference/default-network-ports).
## Integração com a BTG e mTLS
Credenciais e as configurações de TLS mútuo para a conexão com a BTG.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------- | -------------------- | --------------------------------------------------------------------------------- |
| `BTG_BASE_URL` | **Obrigatória** | URL base da API da BTG. |
| `BTG_CERTIFICATE_URL` | **Obrigatória** | Endpoint a partir do qual o certificado de cliente é obtido para mTLS. |
| `BTG_CLIENT_ID` | **Obrigatória** | OAuth client ID para a API da BTG. |
| `BTG_CLIENT_SECRET` | 🔒 **Obrigatória** | OAuth client secret para a API da BTG. |
| `BTG_WEBHOOK_SECRET` | 🔒 **Obrigatória** | Segredo usado para validar assinaturas de webhook de entrada da BTG. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica assinaturas de webhook da BTG. Mantenha `true` em produção. |
| `MTLS_ENABLED` | `false` | Habilita TLS mútuo na conexão com a BTG. Habilite em produção. |
| `MTLS_CERTIFICATE_TTL` | `24h` | Por quanto tempo um certificado de cliente obtido fica cacheado antes do refresh. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout para a chamada HTTP de obtenção do certificado. |
## Datastores
Este rail usa um prefixo `DB_*` (não o formato compartilhado `POSTGRES_*`) para sua conexão PostgreSQL primária e uma réplica de leitura separada, além de MongoDB e Redis.
| Variável | Padrão / Obrigatória | Descrição |
| ----------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_HOST` · `DB_PORT` | **Obrigatória** | Host e porta do PostgreSQL primário. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Obrigatória** | Credenciais do PostgreSQL primário. |
| `DB_NAME` | **Obrigatória** | Nome do banco de dados primário. |
| `DB_SSL_MODE` | `disable` | Modo TLS do libpq. Use `require` ou mais forte em produção. |
| `DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD` | 🔒 — | Conexão de réplica de leitura opcional (mesmo formato do primário). |
| `REPLICATION_USER` · `REPLICATION_PASSWORD` | 🔒 — | Credenciais para a role de replicação por streaming. |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Obrigatória** | Conexão MongoDB. `MONGO_URI` define o esquema de conexão (`mongodb` ou `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD` e `MONGO_NAME` fornecem o host, as credenciais e o banco de dados. Todas se combinam em uma única string de conexão — não são alternativas de URI versus partes discretas. A senha é um segredo. |
| `MONGO_TLS` | `false` | Habilita TLS para o MongoDB. |
| `REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD` | 🔒 — | Endpoint do Redis/Valkey e senha de auth. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Habilita TLS para o Redis e fornece um CA PEM codificado em base64. |
## Midaz, CRM e Fees
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Obrigatória** | URLs dos serviços de onboarding e de transações do Midaz. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Obrigatória** | UUIDs de organização e de ledger do Midaz para contabilizações Pix. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 — | Credenciais OAuth para M2M do Midaz. |
| `PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 — | URL do serviço CRM e credenciais OAuth. |
| `FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET` | 🔒 — | URL do serviço Fees Engine e credenciais OAuth. |
| `FEE_SERVICE_TIMEOUT` | — | Timeout de requisição de tarifa. |
| `CASHIN_FEE_CALCULATION_TYPE` | — | Como as tarifas de cash-in são calculadas. |
## Webhooks internos e agendamento
A API e os workers trocam eventos por um canal de webhook interno e rodam fluxos Pix recorrentes e agendados.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Obrigatória** | Segredo HMAC compartilhado entre a API e os workers para a assinatura de webhooks internos. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica assinaturas de webhook interno. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | — | Desvio de relógio permitido ao validar timestamps de webhook interno. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | — | Limite de payload de webhook de entrada e teto de retries. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | — | Parâmetros de agendamento e de tratamento de reply do Pix recorrente. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | — | Janela de execução de pagamento agendado e seus limites. |
| `RECONCILIATION_INTERNAL_CIDR` | — | Faixa de CIDR confiável para chamadas internas de reconciliação. |
## Escopo Pix e de ledger
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX_ISPB` | **Obrigatória** | O ISPB (código de participante) sob o qual este deployment opera. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Janela diária durante a qual escritas de entradas no ledger são bloqueadas. |
| `ORGANIZATION_IDS` | **Obrigatória em produção** | UUIDs de organização Midaz no escopo de licenciamento, separados por vírgula. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Caminho para um arquivo de credenciais de service account do Google, ao rodar contra dependências gerenciadas pelo GCP. |
## Saúde e prontidão
Cada componente expõe `GET /health` (liveness) e `GET /readyz` (readiness) em sua porta; a API também responde `/ready`. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de startup/drain.