> ## 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 de Boleto e pagamento de contas, via BTG — integração com a BTG, criptografia de credenciais e rotação de chaves, vínculo com o ledger Midaz, reconciliação e dispatch de webhooks.
O rail de Boleto e pagamento de contas emite boletos e liquida pagamentos de contas e tributos (DARF) através da BTG. Seu comportamento é configurado através de variáveis de ambiente definidas no momento do deploy pela equipe de DevOps; alterar uma exige uma reinicialização do serviço. Esta página cobre as variáveis **distintivas deste rail** — para os parâmetros de datastore, multi-tenancy, 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. Ele usa o formato de datastore compartilhado `POSTGRES_*` — consulte [Datastores](/pt/reference/byoc-configuration#datastores).
## Servidor e porta
O serviço escuta no endereço em `SERVER_ADDRESS` (padrão `:8080`). As probes de liveness, readiness e version se vinculam a essa mesma porta. A multi-tenancy é alternada com `MULTI_TENANCY_ENABLED` (note a grafia `MULTI_TENANCY_`; a conexão do Tenant Manager usa as variáveis compartilhadas `MULTI_TENANT_*`). Consulte [Multi-tenancy](/pt/reference/byoc-configuration#multi-tenancy) e [Portas de rede padrão](/pt/reference/default-network-ports).
## Integração com a BTG
Endpoints e credenciais para a conexão com a BTG, além dos intervalos de refresh em segundo plano para o access token da BTG e as credenciais sincronizadas.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------- |
| `BTG_API_BASE_URL` | **Obrigatória** | URL base da API da BTG. |
| `BTG_AUTH_URL` | **Obrigatória** | Endpoint de token OAuth da BTG. |
| `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_HTTP_TIMEOUT` | `30s` | Timeout para chamadas à API da BTG. |
| `BTG_TOKEN_REFRESH_INTERVAL` | `1h` | Com que frequência o access token da BTG é atualizado. |
| `BTG_CREDENTIAL_SYNC_INTERVAL` | `20h` | Com que frequência as credenciais armazenadas da BTG são re-sincronizadas. |
## Criptografia de credenciais e chaves de API internas
O rail criptografa as credenciais armazenadas em repouso e autentica chamadas internas (worker-to-API) com uma chave de API. Ambas suportam um slot `_PREVIOUS` para que você rotacione o valor ativo sem downtime.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------------ | -------------------- | -------------------------------------------------------------------- |
| `CREDENTIAL_ENCRYPTION_KEY` | 🔒 **Obrigatória** | Chave usada para criptografar as credenciais armazenadas em repouso. |
| `CREDENTIAL_ENCRYPTION_KEY_PREVIOUS` | 🔒 — | Chave de criptografia anterior, mantida legível durante a rotação. |
| `INTERNAL_API_KEY` | 🔒 **Obrigatória** | Chave de API que autentica chamadas internas worker-to-API. |
| `INTERNAL_API_KEY_PREVIOUS` | 🔒 — | Chave de API interna anterior, aceita durante a rotação. |
| `INTERNAL_WORKER_URL` | **Obrigatória** | URL que a API usa para alcançar o worker interno. |
## Vínculo com o ledger Midaz
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `MIDAZ_LEDGER_URL` | **Obrigatória** | URL do serviço de ledger do Midaz. |
| `MIDAZ_DEFAULT_ORG_ID` | **Obrigatória** | UUID de organização Midaz padrão para contabilizações. |
| `MIDAZ_DEFAULT_LEDGER_ID` | **Obrigatória** | UUID de ledger Midaz padrão para contabilizações. |
| `MIDAZ_ALLOW_INSECURE_HTTP` | `false` | Permite uma URL `http://` em texto claro para o Midaz. Mantenha `false` em produção. |
## Reconciliação
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------------- | -------------------- | -------------------------------------------------------- |
| `RECONCILIATION_INTERVAL` | `5m` | Com que frequência o ciclo de reconciliação roda. |
| `RECONCILIATION_LOOKBACK_HOURS` | `24` | Quão longe no passado cada ciclo de reconciliação varre. |
| `RECONCILIATION_MAX_BOLETOS_PER_CYCLE` | — | Máximo de boletos reconciliados por ciclo. |
| `RECONCILIATION_DELAY_MS` | — | Atraso em milissegundos entre etapas de reconciliação. |
## Dispatch de webhook e idempotência
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------- | -------------------- | -------------------------------------------------------------------- |
| `WEBHOOK_DISPATCHER_BATCH_SIZE` | — | Número de eventos de webhook despachados por batch. |
| `WEBHOOK_DISPATCHER_INTERVAL` | — | Intervalo entre ciclos de dispatch de webhook. |
| `WEBHOOK_SKIP_URL_VALIDATION` | `false` | Pula a validação da URL do assinante. Mantenha `false` em produção. |
| `IDEMPOTENCY_RECORD_TTL_HOURS` | `48` | Por quanto tempo os registros de idempotência são retidos, em horas. |
| `ACCOUNT_VALIDATION_DISABLED` | `false` | Desabilita a validação de conta. Mantenha `false` em produção. |
## Migrações
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------- | -------------------- | -------------------------------------------------------------------- |
| `MIGRATION_TIMEOUT_SEC` | — | Timeout em segundos para uma execução de migração de banco de dados. |
| `MIGRATION_LOCK_TIMEOUT_MS` | — | Timeout em milissegundos para adquirir o lock de migração. |
## Saúde e prontidão
O rail expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta principal. Quando a multi-tenancy está habilitada, ele adiciona uma probe por tenant protegida por auth em `GET /readyz/tenant/{id}`. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de startup/drain.