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. A equipe de DevOps define seu comportamento por meio de variáveis de ambiente no momento do deploy. Uma alteração em uma variável exige reiniciar o 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. MULTI_TENANCY_ENABLED alterna a multi-tenancy (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

Estas variáveis definem os endpoints e as credenciais para a conexão com a BTG. Elas também definem os intervalos de refresh em segundo plano do access token da BTG e das 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. Ele autentica chamadas internas entre os pods de worker e de API com uma chave de API. Ambas as chaves 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.

Outbox interno do Midaz

O rail sempre inicializa um outbox interno do PostgreSQL para operações assíncronas do 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 novas tentativas e de tempo de processamento e rejeita combinações inseguras.

Variável	Padrão / Obrigatória	Descrição
`OUTBOX_DISPATCH_INTERVAL_SEC`	`2`	Intervalo em segundos entre consultas do dispatcher.
`OUTBOX_BATCH_SIZE`	`50`	Máximo de linhas reivindicadas por consulta.
`OUTBOX_PUBLISH_MAX_ATTEMPTS`	`1`	Tentativas do handler durante o dispatch de uma linha reivindicada. Mantenha esse valor baixo porque as chamadas ao Midaz já tentam novamente internamente.
`OUTBOX_PUBLISH_BACKOFF_MS`	`200`	Espera em milissegundos entre tentativas do handler.
`OUTBOX_RETRY_WINDOW_SEC`	`180`	Espera antes de uma linha com falha ficar elegível para outro dispatch.
`OUTBOX_MAX_DISPATCH_ATTEMPTS`	`10`	Máximo de tentativas externas de dispatch antes de a linha passar para o estado inválido.
`OUTBOX_PROCESSING_TIMEOUT_SEC`	`120`	Timeout de processamento, em segundos, para uma linha reivindicada.
`OUTBOX_MAX_FAILED_PER_BATCH`	`25`	Máximo de linhas com falha processadas em um lote.
`OUTBOX_INCLUDE_TENANT_METRICS`	`false`	Inclui identificadores de tenant nas métricas do outbox.
`OUTBOX_PRIORITY_EVENT_TYPES`	—	Mantenha vazia. Qualquer valor não vazio faz a inicialização falhar.
`OUTBOX_ALLOW_EMPTY_TENANT`	`true`	Permite linhas do outbox interno sem identificador de tenant na operação single-tenant.

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`	`100`	Máximo de boletos reconciliados por ciclo, por tenant.
`RECONCILIATION_DELAY_MS`	`500`	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`	`50`	Número de eventos de webhook despachados por batch.
`WEBHOOK_DISPATCHER_INTERVAL`	`10s`	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`	`300`	Timeout em segundos para uma execução de migração de banco de dados.
`MIGRATION_LOCK_TIMEOUT_MS`	`10000`	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. Se você habilitar a multi-tenancy, 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

Outbox interno do 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

​Outbox interno do 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

Outbox interno do Midaz

Reconciliação

Dispatch de webhook e idempotência

Migrações

Saúde e prontidão