> ## 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, lotes e parcelas de boletos 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 compartilhados de datastore, telemetria e autenticação, veja [Fundamentos de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> Este trilho **não** monta a systemplane admin API. Ele usa o formato de datastore compartilhado `POSTGRES_*`. Veja [Datastores](https://docs.lerian.studio/pt/reference/byoc-configuration.md#datastores).

## Servidor e porta

O serviço escuta no endereço em `SERVER_ADDRESS` (padrão `:8080`). A porta principal serve `GET /health` e `GET /version`. `PLUGIN_AUTH_ENABLED` tem padrão `true`, e a produção força o valor ligado. Veja [Portas de rede padrão](https://docs.lerian.studio/pt/reference/default-network-ports.md).

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `HEALTH_PORT` | — | Porta do listener de probes. Sem valor, o processo não inicia o listener de probes. |
| `REQUEST_TIMEOUT_SEC` | o maior entre `180` e quatro vezes `BTG_HTTP_TIMEOUT` | Prazo de cada requisição de negócio, em segundos. Uma dependência que não responde dentro dele faz a requisição falhar com `503`. Requisições `GET` e `HEAD` rodam com o menor entre este valor e 30 segundos. A inicialização falha com um valor abaixo de quatro vezes `BTG_HTTP_TIMEOUT`. |

## Declaração de permissões

O serviço publica as permissões do Payments no Access Manager somente quando `IDP_DECLARATION_ENABLED` é `true`. Vem desligado por padrão.

| Variável | Padrão / Obrigatória | Descrição |
| - | - | - |
| `IDP_DECLARATION_ENABLED` | `false` | Publica a declaração de permissões do Payments na inicialização. Aceita apenas `true` ou `false`. |
| `IDP_HOST` | — | Host de identidade do Access Manager. Obrigatória com a declaração ligada. |
| `IDP_M2M_CLIENT_ID` | — | Id da credencial de máquina usada para publicar. Obrigatória com a declaração ligada. |
| `IDP_M2M_CLIENT_SECRET` | — | Segredo da credencial de máquina. 🔒 Obrigatória com a declaração ligada. |

A declaração também exige `PLUGIN_AUTH_ENABLED` em `true` e um host de autenticação em `PLUGIN_AUTH_HOST` ou `PLUGIN_AUTH_ADDRESS`. Um valor ausente interrompe a inicialização.

## Licença

A licença é obrigatória em todos os ambientes. A inicialização falha quando `LICENSE_KEY` está vazia. A licença vale para o deployment inteiro, então a chave deve ser global. O [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md) 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 global que a Lerian emitiu para este trilho. |

## 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, que o serviço usa para descobrir a conta do BTG que emite. Sem ela, o connect do provedor não verifica a conta e responde `account_verified: false`. Todo boleto híbrido, e todo boleto, item de lote ou série de parcelas que leva um nosso número escolhido, é recusado com `422` `PBP-0017`. |
| `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, e para o beneficiário final de todo boleto, 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 não tem identificador do BTG: uma que reserva um nosso número, ou um boleto avulso sem ele cuja resposta do BTG se perdeu. Valores abaixo de `15m` valem `15m`, e o valor nunca fica abaixo de quatro vezes `BTG_HTTP_TIMEOUT`. |
| `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`. |

## Série de parcelas

Estas variáveis definem como a conciliação envia ao BTG os boletos de uma série de parcelas, um de cada vez.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `RECONCILIATION_INSTALLMENT_CLAIM_LEASE` | `10m` | Por quanto tempo uma réplica mantém a reivindicação exclusiva de uma parcela enquanto a envia ao BTG. Um valor inválido vale `10m`. O valor nunca fica abaixo de quatro vezes `BTG_HTTP_TIMEOUT` mais um minuto, nem abaixo de `3m`. |
| `RECONCILIATION_INSTALLMENT_DISCOUNT_CUTOFF_MARGIN` | `30m` | Quanto do dia deve restar antes da meia-noite em Brasília para que uma parcela cuja data-limite de desconto é hoje seja enviada. Valores acima de `6h` valem `6h`. Um valor zero, negativo ou inválido vale `30m`. |
| `RECONCILIATION_INSTALLMENT_RECOVERY_ALERT_AGE` | `1h` | Por quanto tempo uma parcela pode esperar seu título no BTG antes que o serviço gere um alerta. Valores abaixo de `15m` valem `15m`. O alerta não altera a parcela. |
| `RECONCILIATION_INSTALLMENT_RECOVERY_ESCALATION_AGE` | `24h` | A idade em que esse alerta sobe de severidade. Um valor que não seja maior que a idade do alerta é substituído na inicialização por `24h`, ou pelo dobro da idade do alerta quando `24h` não é maior. O serviço não o recusa. |
| `RECONCILIATION_INSTALLMENT_ACCOUNT_DISCOVERY_ALERT_AGE` | `1h` | Por quanto tempo uma parcela ainda não tentada de uma série sem conta no BTG pode esperar antes que o serviço gere um alerta. Valores abaixo de `15m` valem `15m`. |

## Lotes de boletos

Estas variáveis definem como o serviço envia ao BTG os itens de um lote de boletos.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `BTG_BULK_MAX_BODY_BYTES` | `7680` | Orçamento de bytes do corpo de um envio de lote ao BTG. A inicialização falha com um valor zero, negativo ou inválido. |
| `BOLETO_BATCH_INLINE_SUBMIT_BUDGET` | `8s` | Por quanto tempo a requisição de criação do lote espera seus envios antes de responder. Limita apenas essa espera, nunca a chamada ao BTG. Um valor zero, negativo ou inválido vale `8s`. |
| `RECONCILIATION_BATCH_SUBMISSION_CLAIM_LEASE` | `3m` | Por quanto tempo uma réplica mantém a reivindicação exclusiva de um envio de lote. Um valor inválido vale `3m`. O valor nunca fica abaixo de quatro vezes `BTG_HTTP_TIMEOUT` mais um minuto. |
| `RECONCILIATION_BATCH_SUBMISSIONS_PER_CYCLE` | `10` | Máximo de envios de lote que a conciliação envia por tenant a cada ciclo. Um valor zero ou negativo vale `10`. |
| `BOLETO_BATCH_UNKNOWN_ATTEMPTS_BEFORE_SEARCH` | `3` | Quantos resultados desconhecidos consecutivos um envio de lote aceita antes que o serviço procure seus boletos no BTG. Um valor zero ou negativo vale `3`. |
| `BOLETO_BATCH_ITEM_OVERDUE_AFTER` | `30m` | Por quanto tempo um item de lote pode ficar sem resultado, desde a primeira tentativa de envio ou, se não houve, desde a criação, antes que o lote o leia como atrasado. Um valor zero, negativo ou inválido vale `30m`. |
| `RECONCILIATION_BATCH_RECOVERY_ALERT_AGE` | `1h` | Por quanto tempo um item de lote em recuperação pode ficar sem resultado antes que o serviço gere um alerta. O alerta não altera o item. |
| `BOLETO_BATCH_CANCEL_CONCURRENCY` | `5` | Quantos itens de um lote um cancelamento cancela no BTG ao mesmo tempo. Um valor zero ou negativo vale `5`. |

## 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

`GET /readyz` (readiness) e, no modo multi-tenant, `GET /readyz/tenant/:id` respondem na porta de `HEALTH_PORT`. Veja [Health e readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o formato da resposta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.