> ## 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 trilho Pix Indireto via BTG: mTLS com o BTG, datastores DB_*, vínculos com Midaz e CRM, endpoints de webhook e componentes worker no deploy.
O Pix Indireto via BTG alcança o arranjo Pix pelo BTG como participante direto. Ele é entregue em vários componentes: uma API, mais os workers de conciliação, de agendamento e de webhooks de entrada e de saída. O DevOps define as variáveis de ambiente de cada componente no deploy. Para mudar uma variável, você reinicia aquele componente. Esta página cobre as variáveis **específicas deste trilho**. Para os controles de multi-tenancy, streaming, telemetria e autenticação compartilhados por todos os serviços Go da Lerian, veja [Fundamentos de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo **Obrigatório**) marca as variáveis que você deve definir. `—` significa que não há padrão. `🔒` marca um **segredo**. Injete cada segredo no deploy a partir do seu cofre de segredos. Nunca faça commit de um segredo. Esta página lista apenas nomes de variáveis e comportamento. Ela não imprime valores de segredos.
Este trilho **não** monta a systemplane admin API. As variáveis de datastore dele usam o prefixo `DB_*` em vez do formato compartilhado `POSTGRES_*`. Veja [Datastores](#datastores) abaixo.
## Componentes e portas
O componente de API escuta em `SERVER_PORT` (padrão `4014`). `SERVER_ADDRESS` deriva dele. Os workers de conciliação, de agendamento e de webhooks usam cada um um `WORKER_PORT` para as próprias health probes. Cada worker traz os próprios controles de ajuste (tamanhos de lote, intervalos de consulta, concorrência e circuit breakers) no arquivo `.env.example` dele. Veja [Portas de rede padrão](/pt/reference/default-network-ports).
## Integração com o BTG e mTLS
Essas variáveis guardam as credenciais e as configurações de TLS mútuo da conexão com o BTG.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `BTG_BASE_URL` | **Obrigatório** | URL base da API do BTG. |
| `BTG_CERTIFICATE_URL` | **Obrigatório** | Endpoint de onde o certificado de cliente é buscado para o mTLS. |
| `BTG_CLIENT_ID` | **Obrigatório** | Client ID OAuth da API do BTG. |
| `BTG_CLIENT_SECRET` | 🔒 **Obrigatório** | Client secret OAuth da API do BTG. |
| `BTG_WEBHOOK_SECRET` | 🔒 **Obrigatório** | Segredo usado para validar as assinaturas dos webhooks recebidos do BTG. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica as assinaturas dos webhooks do BTG. Deixe `true` em produção. |
| `MTLS_ENABLED` | `false` | Habilita o TLS mútuo na conexão com o BTG. Habilite em produção. |
| `MTLS_CERTIFICATE_TTL` | `24h` | Por quanto tempo um certificado de cliente buscado fica em cache antes da renovação. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout da chamada HTTP que busca o certificado. |
## Datastores
Este trilho usa o prefixo `DB_*` para datastores, não o formato compartilhado `POSTGRES_*`. Ele conecta a um PostgreSQL primário, a uma réplica de leitura separada, ao MongoDB e ao Redis.
| Variável | Padrão / Obrigatório | Descrição |
| ----------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_HOST` · `DB_PORT` | **Obrigatório** | Host e porta do PostgreSQL primário. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Obrigatório** | Credenciais do PostgreSQL primário. |
| `DB_NAME` | **Obrigatório** | Nome do banco 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 opcional com a réplica de leitura (mesmo formato do primário). |
| `REPLICATION_USER` · `REPLICATION_PASSWORD` | 🔒 — | Credenciais do papel de replicação por streaming. |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Obrigatório** | Conexão com o MongoDB. `MONGO_URI` define o esquema da 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. Todas se combinam em uma única string de conexão — elas não são alternativas entre URI e campos separados. A senha é um segredo. |
| `MONGO_TLS` | `false` | Habilita o TLS para o MongoDB. |
| `REDIS_HOST` · `REDIS_PORT` · `REDIS_PASSWORD` | 🔒 — | Endpoint do Redis/Valkey e senha de autenticação. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Habilita o TLS para o Redis e fornece um CA PEM codificado em base64. |
## Midaz, CRM e Fees
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------- |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Obrigatório** | URLs dos serviços de onboarding e de transação do Midaz. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Obrigatório** | UUIDs da organização e do ledger do Midaz para os lançamentos de Pix. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 — | Credenciais OAuth para o M2M do Midaz. |
| `PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 — | URL do serviço de 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 da 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 interno de webhooks. Eles também executam fluxos de Pix recorrentes e agendados.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Obrigatório** | Segredo HMAC compartilhado entre a API e os workers para assinar os webhooks internos. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica as assinaturas dos webhooks internos. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | — | Desvio de relógio permitido ao validar os timestamps dos webhooks internos. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | `10485760` (10 MB) · `3` | Limite do payload dos webhooks recebidos e teto de novas tentativas. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | `1` · `720h` · `150ms` · `3` | Controles de agendamento do Pix recorrente e de tratamento das respostas. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | `6` · `2` · `180` · `60` | Janela e limites de execução dos pagamentos agendados. |
| `RECONCILIATION_INTERNAL_CIDR` | — | Faixa CIDR confiável para as chamadas internas de conciliação. |
## Escopo do Pix e do ledger
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `PIX_ISPB` | **Obrigatório** | O ISPB (código do participante) sob o qual este deploy opera. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Janela diária durante a qual as escritas de lançamentos no ledger ficam bloqueadas. |
| `ORGANIZATION_IDS` | **Obrigatório em produção** | UUIDs de organizações do Midaz no escopo do licenciamento, separados por vírgula. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Caminho para um arquivo de credenciais de conta de serviço do Google, ao rodar com dependências gerenciadas na GCP. |
## Health e readiness
Cada componente expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta dele. Veja [Health e readiness](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de inicialização e drenagem.