> ## 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 de boletos e pagamento de contas via BTG: OAuth do BTG, criptografia de credenciais com rotação de chaves, ledger do Midaz, conciliação e webhooks.
O trilho de boletos e pagamento de contas emite boletos e liquida pagamentos de contas e de tributos (DARF) pelo BTG. O DevOps define o comportamento dele por variáveis de ambiente no deploy. Uma mudança em uma variável exige reiniciar o serviço. Esta página cobre as variáveis **específicas deste trilho**. Para os controles de datastore, multi-tenancy, 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 o segredo no deploy a partir do seu cofre de segredos. Nunca faça commit dele. 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. Ele usa o formato de datastore compartilhado `POSTGRES_*`. Veja [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 versão usam essa mesma porta. `MULTI_TENANCY_ENABLED` liga e desliga o multi-tenancy (atenção à grafia `MULTI_TENANCY_`). A conexão com o Tenant Manager usa as variáveis compartilhadas `MULTI_TENANT_*`. Veja [Multi-tenancy](/pt/reference/byoc-configuration#multi-tenancy) e [Portas de rede padrão](/pt/reference/default-network-ports).
## Integração com o BTG
Essas variáveis definem os endpoints e as credenciais da conexão com o BTG. Elas também definem os intervalos de atualização em background do token de acesso do BTG e das credenciais sincronizadas.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------ | -------------------- | -------------------------------------------------------------------------- |
| `BTG_API_BASE_URL` | **Obrigatório** | URL base da API do BTG. |
| `BTG_AUTH_URL` | **Obrigatório** | Endpoint de token OAuth do BTG. |
| `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_HTTP_TIMEOUT` | `30s` | Timeout das chamadas à API do BTG. |
| `BTG_TOKEN_REFRESH_INTERVAL` | `1h` | Com que frequência o token de acesso do BTG é renovado. |
| `BTG_CREDENTIAL_SYNC_INTERVAL` | `20h` | Com que frequência as credenciais armazenadas do BTG são ressincronizadas. |
## Criptografia de credenciais e chaves de API internas
O trilho criptografa as credenciais armazenadas em repouso. Ele autentica as chamadas internas entre os pods de worker e de API com uma chave de API. As duas chaves têm um slot `_PREVIOUS` para você rotacionar o valor ativo sem downtime.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------------ | -------------------- | --------------------------------------------------------------------- |
| `CREDENTIAL_ENCRYPTION_KEY` | 🔒 **Obrigatório** | 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ório** | Chave de API que autentica as chamadas internas do worker para a API. |
| `INTERNAL_API_KEY_PREVIOUS` | 🔒 — | Chave de API interna anterior, aceita durante a rotação. |
| `INTERNAL_WORKER_URL` | **Obrigatório** | URL que a API usa para alcançar o worker interno. |
## Vínculo com o ledger do Midaz
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------- | -------------------- | ---------------------------------------------------------------------------- |
| `MIDAZ_LEDGER_URL` | **Obrigatório** | URL do serviço de ledger do Midaz. |
| `MIDAZ_DEFAULT_ORG_ID` | **Obrigatório** | UUID padrão da organização do Midaz para os lançamentos. |
| `MIDAZ_DEFAULT_LEDGER_ID` | **Obrigatório** | UUID padrão do ledger do Midaz para os lançamentos. |
| `MIDAZ_ALLOW_INSECURE_HTTP` | `false` | Permite uma URL `http://` do Midaz em texto puro. Deixe `false` em produção. |
## Outbox interno do Midaz
O trilho sempre inicializa um outbox interno em PostgreSQL para as operações assíncronas no ledger do Midaz. Essa é uma fila de trabalho interna, não um catálogo externo de CloudEvents ou do Streaming Hub. A inicialização valida em conjunto os orçamentos de nova tentativa e de tempo de processamento, e rejeita combinações inseguras.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2` | Intervalo em segundos entre as consultas do dispatcher. |
| `OUTBOX_BATCH_SIZE` | `50` | Número máximo de linhas reivindicadas por consulta. |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | `1` | Tentativas do handler dentro de um despacho de linha reivindicada. Mantenha esse valor baixo porque as chamadas ao Midaz já fazem novas tentativas internamente. |
| `OUTBOX_PUBLISH_BACKOFF_MS` | `200` | Backoff em milissegundos entre as tentativas do handler. |
| `OUTBOX_RETRY_WINDOW_SEC` | `180` | Atraso até uma linha com falha ficar elegível para outro despacho. |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | `10` | Número máximo de tentativas externas de despacho antes de a linha ficar inválida. |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | `120` | Timeout de processamento, em segundos, de uma linha reivindicada. |
| `OUTBOX_MAX_FAILED_PER_BATCH` | `25` | Número máximo de linhas com falha tratadas em um lote. |
| `OUTBOX_INCLUDE_TENANT_METRICS` | `false` | Inclui os identificadores de tenant nas métricas do outbox. |
| `OUTBOX_PRIORITY_EVENT_TYPES` | — | Mantenha vazio. Qualquer valor não vazio faz a inicialização falhar. |
| `OUTBOX_ALLOW_EMPTY_TENANT` | `true` | Permite linhas internas do outbox sem identificador de tenant na operação single-tenant. |
## Conciliação
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------------------- | -------------------- | ----------------------------------------------------------- |
| `RECONCILIATION_INTERVAL` | `5m` | Com que frequência o ciclo de conciliação roda. |
| `RECONCILIATION_LOOKBACK_HOURS` | `24` | Quanto tempo para trás cada ciclo de conciliação varre. |
| `RECONCILIATION_MAX_BOLETOS_PER_CYCLE` | `100` | Número máximo de boletos conciliados por ciclo, por tenant. |
| `RECONCILIATION_DELAY_MS` | `500` | Atraso em milissegundos entre as etapas da conciliação. |
## Despacho de webhooks e idempotência
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------- | -------------------- | --------------------------------------------------------------------- |
| `WEBHOOK_DISPATCHER_BATCH_SIZE` | `50` | Número de eventos de webhook despachados por lote. |
| `WEBHOOK_DISPATCHER_INTERVAL` | `10s` | Intervalo entre os ciclos de despacho de webhooks. |
| `WEBHOOK_SKIP_URL_VALIDATION` | `false` | Pula a validação da URL do assinante. Deixe `false` em produção. |
| `IDEMPOTENCY_RECORD_TTL_HOURS` | `48` | Por quanto tempo os registros de idempotência são mantidos, em horas. |
| `ACCOUNT_VALIDATION_DISABLED` | `false` | Desabilita a validação de conta. Deixe `false` em produção. |
## Migrações
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------- | -------------------- | ---------------------------------------------------------- |
| `MIGRATION_TIMEOUT_SEC` | `300` | Timeout em segundos de uma execução de migração do banco. |
| `MIGRATION_LOCK_TIMEOUT_MS` | `10000` | Timeout em milissegundos para adquirir o lock da migração. |
## Health e readiness
O trilho expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta principal. Se você habilita o multi-tenancy, ele adiciona uma probe por tenant protegida por autenticação em `GET /readyz/tenant/{id}`. Veja [Health e readiness](/pt/reference/health-and-readiness) para o formato da resposta e o comportamento de inicialização e drenagem.