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 compartilhados de datastore, telemetria e autenticação, 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. PLUGIN_AUTH_ENABLED tem padrão true, e a produção força o valor ligado. Veja Portas de rede padrão.

Licença

A licença é obrigatória em todos os ambientes. A inicialização falha quando uma das variáveis está vazia. O License Manager descreve como o produto verifica a licença.

Variável	Padrão / Obrigatório	Descrição
`LICENSE_KEY`	🔒 Obrigatório	A chave de licença que a Lerian emitiu para este trilho.
`ORGANIZATION_IDS`	Obrigatório	Escopo da licença: `global` ou uma lista de UUIDs de organizações em minúsculas, separados por vírgula.

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_COMMON_BASE_URL`	—	URL base da API Common Methods do BTG. Sem ela, o connect do provedor não verifica a conta e responde `account_verified: false`.
`PROVIDER_CLIENT_ID`	Obrigatório	Client ID OAuth da API do BTG.
`PROVIDER_CLIENT_SECRET`	🔒 Obrigatório	Client secret OAuth da API do BTG.
`BTG_WEBHOOK_HMAC_SECRET`	🔒 Obrigatório em produção	Segredo que autentica os webhooks de entrada do BTG. No mínimo 32 caracteres.
`BTG_HTTP_TIMEOUT`	`30s`	Timeout das chamadas à API do BTG.
`BTG_TOKEN_REFRESH_INTERVAL`	`2m`	Com que frequência o token de acesso do BTG é renovado. Valores acima de `4m` ficam limitados a `4m`.
`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 que a API apresenta nas chamadas ao worker. No mínimo 32 caracteres. Os pods de worker sempre precisam dela; os pods de API precisam dela em produção.
`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. Para consultar o pagador de pagamentos de contas e DARF, esse serviço deve oferecer os endpoints de instrumentos e titulares do CRM em `/v2`.
`MIDAZ_AUTH_ENABLED`	`false`	Autentica as chamadas ao Midaz pelo Access Manager. A produção exige `true`.
`MIDAZ_ALLOW_INSECURE_HTTP`	`false`	Permite uma URL `http://` em texto puro do Midaz ou do Access Manager. 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.

Conciliação

Variável	Padrão / Obrigatório	Descrição
`RECONCILIATION_INTERVAL`	`90s`	Com que frequência o ciclo de conciliação roda.
`RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`	`100`	Número máximo de itens de pagamento e de liquidação conciliados por ciclo.
`RECONCILIATION_MAX_BOLETOS_PER_CYCLE`	`40`	Número máximo de boletos conciliados por ciclo.
`RECONCILIATION_DELAY_MS`	`500`	Atraso em milissegundos entre as etapas da conciliação.
`RECONCILIATION_PAYMENT_GRACE_PERIOD`	`5m`	Idade que um pagamento precisa atingir antes que a conciliação consulte o BTG sobre ele. Valores abaixo de `2m` valem `2m`.
`PAYMENT_UNCONFIRMED_DISPATCH_GRACE`	`5m`	Idade mínima antes que a conciliação faça falhar um pagamento `UNCONFIRMED` que nunca foi enviado ao BTG. Nada foi pago, e qualquer reserva é cancelada. A inicialização falha abaixo de `5m`.
`PAYMENT_UNCONFIRMED_ABSENCE_WINDOW`	`30m`	Por quanto tempo o BTG precisa ficar sem registro de um pagamento de conta ou de concessionária enviado antes que a conciliação o faça falhar com `PBP-0211` e libere os fundos. A inicialização falha abaixo de `10m`.
`PAYMENT_UNCONFIRMED_BATCH_SIZE`	`50`	Máximo de pagamentos `UNCONFIRMED` lidos por ciclo. Valores acima de `100` valem `100`.
`RECONCILIATION_BOLETO_GRACE_PERIOD`	`5m`	Idade que um boleto precisa atingir antes que a conciliação consulte o BTG sobre ele. Valores abaixo de `2m` valem `2m`.
`RECONCILIATION_BOLETO_PROCESSING_CEILING`	`24h`	Idade, pelo horário de criação no BTG, a partir da qual um boleto que o BTG ainda responde como `PROCESSING` ou `ERROR` deixa de contar como um registro em andamento. Precisa ser maior que `RECONCILIATION_BOLETO_GRACE_PERIOD`, ou a conciliação não inicia. Valores abaixo de `15m` valem `15m`.
`RECONCILIATION_BOLETO_RESERVATION_GRACE_PERIOD`	`30m`	Idade mínima antes que a conciliação consulte o BTG sobre uma emissão de boleto que reserva um nosso número e não tem identificador do BTG.
`RECONCILIATION_WEBHOOK_SILENCE_WINDOW`	`30m`	Por quanto tempo o trilho pode ficar sem receber webhook do BTG antes que a conciliação reporte o silêncio como erro. Ela só o reporta quando um boleto que o BTG aceitou antes do início da janela ainda aguarda o webhook de registro. Valores abaixo de `10m` valem `10m`.
`RECONCILIATION_WEBHOOK_CLAIM_LEASE`	`2h`	Por quanto tempo uma réplica mantém a reivindicação exclusiva de um lote de webhooks do BTG que ela processa. Aumente-o quando aumentar `RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`. Valores abaixo de `1h` valem `1h`.

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_DISPATCHER_CLAIM_LEASE`	`15m`	Por quanto tempo uma réplica mantém a reivindicação exclusiva de um lote de entregas de webhook que ela envia. Aumente-o quando aumentar `WEBHOOK_DISPATCHER_BATCH_SIZE`. Valores abaixo de `5m` valem `5m`.
`WEBHOOK_CONSUMER_INTERVAL`	`5s`	Intervalo entre os ciclos que processam os webhooks que o BTG envia ao trilho. Valores abaixo de `1s` valem `1s`.
`WEBHOOK_CONNECTION_GRACE_WINDOW_SEC`	`1800`	Por quanto tempo, em segundos, a URL de webhook e a chave de assinatura anteriores continuam autenticando entregas depois que um connect do provedor as rotaciona. A inicialização falha com um valor abaixo de `1200` ou com um valor que não seja um inteiro positivo. Deixe sem definir para manter o padrão.
`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.

Consulta de conta

Essas variáveis configuram POST /v1/payments/consult. O rate limit conta as consultas por chamador, e cada réplica faz a própria contagem.

Variável	Padrão / Obrigatório	Descrição
`CONSULT_RATE_LIMIT_MAX`	`100`	Máximo de consultas por chamador em uma janela. `0` ou um valor negativo vale `100`.
`CONSULT_RATE_LIMIT_WINDOW_SEC`	`60`	Duração da janela, em segundos. `0` ou um valor negativo vale `60`.
`CONSULT_AUDIT_HMAC_KEY`	🔒 Obrigatório	A chave que o serviço usa para gerar a impressão digital da linha de pagamento em cada registro de auditoria da consulta. Use pelo menos 32 caracteres, sem espaços no início ou no fim. Um pod que serve a API de pagamentos não inicia sem ela. Em produção, o serviço recusa o valor de exemplo do template de configuraçã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. Veja Health e readiness para o formato da resposta.

Introdução

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Variáveis de ambiente

Servidor e porta

Licença

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

Consulta de conta

Migrações

Health e readiness

​Servidor e porta

​Licença

​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

​Consulta de conta

​Migrações

​Health e readiness

Servidor e porta

Licença

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

Consulta de conta

Migrações

Health e readiness