Variáveis de ambiente

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.

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.

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 e Portas de rede padrão.

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 para o formato da resposta e o comportamento de startup/drain.

Visão geral

Console

Variáveis de ambiente

Servidor e porta

Integração com a BTG

Criptografia de credenciais e chaves de API internas

Vínculo com o ledger Midaz

Reconciliação

Dispatch de webhook e idempotência

Migrações

Saúde e prontidão

​Servidor e porta

​Integração com a BTG

​Criptografia de credenciais e chaves de API internas

​Vínculo com o ledger Midaz

​Reconciliação

​Dispatch de webhook e idempotência

​Migrações

​Saúde e prontidão

Servidor e porta

Integração com a BTG

Criptografia de credenciais e chaves de API internas

Vínculo com o ledger Midaz

Reconciliação

Dispatch de webhook e idempotência

Migrações

Saúde e prontidão