Variáveis de ambiente

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.

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.

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

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 para o formato da resposta e o comportamento de inicialização e drenagem.

Visão geral

Console

Variáveis de ambiente

Servidor e porta

Integração com o BTG

Criptografia de credenciais e chaves de API internas

Vínculo com o ledger do Midaz

Outbox interno do Midaz

Conciliação

Despacho de webhooks e idempotência

Migrações

Health e readiness

​Servidor e porta

​Integração com o BTG

​Criptografia de credenciais e chaves de API internas

​Vínculo com o ledger do Midaz

​Outbox interno do Midaz

​Conciliação

​Despacho de webhooks e idempotência

​Migrações

​Health e readiness

Servidor e porta

Integração com o BTG

Criptografia de credenciais e chaves de API internas

Vínculo com o ledger do Midaz

Outbox interno do Midaz

Conciliação

Despacho de webhooks e idempotência

Migrações

Health e readiness