> ## 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 Pix Indireto via BTG: mTLS com o BTG, datastores DB_*, vínculos com Midaz e CRM, endpoints de webhook e componentes worker no deploy.

O Pix Indireto via BTG alcança o arranjo Pix pelo BTG como participante direto. Ele é entregue em vários componentes: uma API, mais os workers de conciliação, de agendamento e de webhooks de entrada e de saída. O DevOps define as variáveis de ambiente de cada componente no deploy. Para mudar uma variável, você reinicia aquele componente. Esta página cobre as variáveis específicas deste trilho. Para os controles de streaming, telemetria e autenticação compartilhados por todos os serviços Go da Lerian, 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 cada segredo no deploy a partir do seu cofre de segredos. Nunca faça commit de um segredo. 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. As variáveis de datastore dele usam o prefixo `DB_*` em vez do formato compartilhado `POSTGRES_*`. Veja [Datastores](#datastores) abaixo.

## Componentes e portas

O componente de API escuta em `SERVER_ADDRESS` (por exemplo `:4014`). A porta principal serve as rotas da API, `GET /health` (uma resposta constante) e `GET /version`. Cada componente, workers incluídos, serve o readiness e as métricas em `HEALTH_PORT`. Veja [Health e readiness](#health-and-readiness) e [Portas de rede padrão](https://docs.lerian.studio/pt/reference/default-network-ports.md).

## Licença

Todo componente verifica a licença na inicialização. A API, o worker de conciliação, o worker de agendamento e os workers de webhooks de entrada e de saída não iniciam sem uma chave válida.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | 🔒 **Obrigatório** em todo componente | A chave de licença de todo o deploy. O componente não inicia com uma chave vazia. Se a licença for recusada após a inicialização, o componente drena e encerra com status `1`. |

Veja [A licença da Lerian](https://docs.lerian.studio/pt/start-here/evaluate-and-deploy/lerians-license.md).

## Integração com o BTG e mTLS

Essas variáveis guardam as credenciais do BTG e as configurações de TLS mútuo nas duas direções: o certificado de cliente que o plugin apresenta ao BTG e a verificação do certificado que o BTG apresenta nos webhooks recebidos.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `BTG_BASE_URL` | **Obrigatório** | URL base da API do BTG. Deve ser uma URL `https`. |
| `BTG_CERTIFICATE_URL` | **Obrigatório** quando `MTLS_ENABLED=true` | URL do certificado público do BTG. Deve ser uma URL `https`. A API o compara com o certificado que o BTG apresenta nos webhooks recebidos. |
| `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** quando a validação está habilitada | Segredo usado para validar as assinaturas dos webhooks recebidos do BTG. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica as assinaturas dos webhooks do BTG. Mantenha `true` em produção. |
| `MTLS_ENABLED` | `false` | Verifica o certificado que o BTG apresenta nos webhooks recebidos. Habilite em produção. |
| `MTLS_CERTIFICATE_HEADER` | `X-Client-Cert` | Header em que o seu ingress repassa o certificado apresentado pelo BTG. O seu ingress deve definir esse header a partir do handshake TLS e sobrescrever qualquer valor que o chamador enviar. |
| `MTLS_CERTIFICATE_TTL` | `24h` | Por quanto tempo o certificado buscado do BTG fica em cache antes da renovação. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout da chamada HTTP que busca o certificado. |
| `BTG_OUTBOUND_MTLS_ENABLED` | `false` | Apresenta um certificado de cliente nas chamadas ao BTG. |
| `CLIENT_TLS_CERT_FILE` · `CLIENT_TLS_KEY_FILE` | 🔒 **Obrigatório** quando o mTLS de saída está habilitado | Caminhos do certificado de cliente e da chave privada em PEM. |
| `CLIENT_TLS_CA_FILE` | — | Pacote PEM opcional que verifica o certificado do servidor do BTG. |

## Datastores

Este trilho usa o prefixo `DB_*` para datastores, não o formato compartilhado `POSTGRES_*`. Ele conecta a um PostgreSQL primário, a uma réplica de leitura separada, ao MongoDB e ao Redis.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `DB_HOST` · `DB_PORT` | **Obrigatório** | Host e porta do PostgreSQL primário. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Obrigatório** | Credenciais do PostgreSQL primário. |
| `DB_NAME` | **Obrigatório** | Nome do banco primário. |
| `DB_SSL_MODE` | `require` | Modo TLS do libpq. Use `require` ou mais forte em produção. |
| `DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD` | 🔒 — | Conexão opcional com a réplica de leitura (mesmo formato do primário). |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Obrigatório** | Conexão com o MongoDB. `MONGO_URI` define o esquema da conexão (`mongodb` ou `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD` e `MONGO_NAME` fornecem o host, as credenciais e o banco. Todas se combinam em uma única string de conexão. Elas não são alternativas entre URI e campos separados. A senha é um segredo. |
| `MONGO_TLS` | `false` | Habilita o TLS para o MongoDB. |
| `REDIS_HOST` · `REDIS_PASSWORD` | 🔒 — | Endpoint `host:port` do Redis/Valkey e senha de autenticação. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Habilita o TLS para o Redis e fornece um CA PEM codificado em base64. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc` ou `saas`. Com `saas`, um componente não inicia se um datastore que ele usa não tem TLS. O PostgreSQL exige `DB_SSL_MODE` igual a `require`, `verify-ca` ou `verify-full`. O Redis exige `REDIS_TLS=true`. O MongoDB exige `MONGO_TLS=true`. |

## Midaz, CRM e Fees

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Obrigatório** | URLs dos serviços de onboarding e de transação do Midaz. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Obrigatório** | UUIDs da organização e do ledger do Midaz para os lançamentos de Pix. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 **Obrigatório** | Credenciais OAuth para o M2M do Midaz. |
| `MIDAZ_COUNTERPARTY_ACCOUNT_ALIAS` | `@external/BRL` | Conta do Midaz que a perna externa de um lançamento de cash-out Pix credita. Um lançamento intra-PSP não a credita. |
| `MIDAZ_CASHOUT_TRANSACTION_ROUTE` · `MIDAZ_CASHOUT_SOURCE_OPERATION_ROUTE` · `MIDAZ_CASHOUT_DESTINATION_OPERATION_ROUTE` | — | Rota de transação, rota de operação de débito e rota de operação de crédito do Midaz para os lançamentos de cash-out Pix. Se um valor está vazio, o plugin não envia rota para ele. Um lançamento intra-PSP usa a rota de transação e a rota de operação de débito, e suas pernas de crédito não carregam rota de operação. |
| `MIDAZ_CASHOUT_REFUND_TRANSACTION_ROUTE` · `MIDAZ_CASHOUT_REFUND_SOURCE_OPERATION_ROUTE` · `MIDAZ_CASHOUT_REFUND_DESTINATION_OPERATION_ROUTE` | — | Rota de transação, rota de operação de débito e rota de operação de crédito do Midaz para os lançamentos de uma devolução de cash-out. Se um valor está vazio, o plugin usa a rota de cash-out correspondente. Os débitos de contas de tarifa não carregam rota. Uma devolução intra-PSP não carrega rota de operação de crédito. |
| `MIDAZ_CASHIN_TRANSACTION_ROUTE` · `MIDAZ_CASHIN_DESTINATION_OPERATION_ROUTE` | — | Rota de transação e rota de operação de crédito do Midaz para os lançamentos de cash-in Pix. Se um valor está vazio, o plugin não envia rota para ele. Os créditos de contas de tarifa não carregam rota. |
| `MIDAZ_CASHIN_REFUND_TRANSACTION_ROUTE` · `MIDAZ_CASHIN_REFUND_DESTINATION_OPERATION_ROUTE` | — | Rota de transação e rota de operação de crédito do Midaz para os lançamentos de uma devolução que você recebe. Se um valor está vazio, o plugin usa a rota de cash-in correspondente. |
| `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 **Obrigatório** | Credenciais OAuth do CRM que o Midaz serve. |
| `PLUGIN_CRM_BASE_URL` | Opcional na API com Midaz 4. Defina no worker de conciliação | URL do CRM que o Midaz serve. Na API com Midaz 4, um valor vazio faz a API usar `MIDAZ_ONBOARDING_URL` como CRM. Se a API não conseguir ler a versão do Midaz nessa URL, ou se o Midaz for 3.x, a API não inicia. Sem a URL, cada consulta ao CRM falha. |
| `FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET` | 🔒 **Obrigatório** quando `CASHIN_FEE_CALCULATION_TYPE=segment` | URL do serviço Fees Engine e credenciais OAuth. |
| `FEE_SERVICE_TIMEOUT` | `5000` | Timeout da requisição de tarifa, em milissegundos. |
| `CASHIN_FEE_CALCULATION_TYPE` | — | Defina `segment` para calcular as tarifas de cash-in pelo segmento da conta. Deixe vazio para não cobrar tarifas de cash-in. |

## Webhooks internos e agendamento

A API e os workers trocam eventos por um canal interno de webhooks. Eles também executam fluxos de Pix recorrentes e agendados.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Obrigatório** | Segredo HMAC compartilhado entre a API e os workers para assinar os webhooks internos. Pelo menos 32 caracteres. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `true` | Verifica as assinaturas dos webhooks internos. Mantenha `true` em produção. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | `300` | Desvio de relógio permitido, em segundos, ao validar os timestamps dos webhooks internos. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | `10485760` (10 MB) · `3` | Limite do payload dos webhooks recebidos e teto de novas tentativas. |
| `WEBHOOK_INBOUND_RETENTION` | — | Worker de webhooks de entrada. Por quanto tempo o plugin guarda os webhooks recebidos que já terminaram: uma duração como `2160h`, ou um número de segundos. Sem valor ou `0` guarda todos os webhooks. Um valor negativo ou malformado recusa o boot. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | `1` · `720h` · `150ms` · `3` | Controles de agendamento do Pix recorrente e de tratamento das respostas. |
| `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | `2` · `180` · `60` | Janela e limites de execução dos pagamentos agendados. |
| `RECONCILIATION_INTERNAL_CIDR` | — | Faixa de rede do seu serviço interno de conciliação. |

## Escopo do Pix e do ledger

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `PIX_ISPB` | **Obrigatório** | O ISPB (código do participante) sob o qual este deploy opera: 8 caracteres, dígitos ou letras maiúsculas. |
| `REQUEST_TIMEOUT_SEC` | `60` | API. O tempo que cada requisição de negócio pode durar, em segundos. Um valor `0` ou menor significa `60`. Quando o limite termina, ou a API não consegue alcançar um banco de dados ou um cache, e nenhum erro mais específico se aplica, a API responde `503` `PIX-0016`. Depois do débito no Midaz de um cash-out ou de uma devolução, o envio ao BTG passa desse limite, então um timeout do cliente não prova que nada foi enviado. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Janela diária (`HH:MM`, horário de São Paulo) durante a qual a API bloqueia a criação, a atualização e a exclusão de chaves Pix. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Credenciais de conta de serviço do Google (um caminho de arquivo ou o conteúdo JSON) para a autenticação IAM da GCP no Redis. |

## Access Manager

Estas variáveis se aplicam ao componente da API. Para `PLUGIN_AUTH_ENABLED` e `PLUGIN_AUTH_ADDRESS`, veja [Fundamentos de configuração BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md).

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `TRUSTED_PROXIES` | — | Faixas CIDR, separadas por vírgula, dos proxies que se conectam direto à API. A API resolve o endereço de quem chama por meio deles e o envia ao Access Manager para a [lista de IPs permitidos](https://docs.lerian.studio/pt/platform/access-manager/features/ip-allowlist/deployment.md). Se a variável não estiver definida, a API não envia o endereço de quem chama. |
| `DECLARATION_ENABLED` | `false` | Defina `true` para publicar a declaração de permissões do plugin no Access Manager na inicialização. |
| `PLUGIN_IDENTITY_HOST` | — | URL absoluta `http` ou `https` do serviço Identity do Access Manager. |
| `M2M_CLIENT_ID` · `M2M_CLIENT_SECRET` | 🔒 — | As credenciais de cliente com que a API publica a declaração. |

Com `DECLARATION_ENABLED=true`, a API não inicia quando `PLUGIN_IDENTITY_HOST`, `M2M_CLIENT_ID` ou `M2M_CLIENT_SECRET` está vazio. Ela também não inicia quando `PLUGIN_AUTH_ENABLED` não é `true`, ou quando `PLUGIN_IDENTITY_HOST` ou `PLUGIN_AUTH_ADDRESS` não é uma URL absoluta `http` ou `https`.

## Verificação de fraude em Pix recebido

Estas variáveis configuram a [verificação de fraude em Pix recebido](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-transfers.md#fraud-check-on-incoming-pix) no componente da API. Quando `ANTIFRAUD_HOOK_ENABLED` é `false`, a API ignora as outras variáveis desta tabela.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `ANTIFRAUD_HOOK_ENABLED` | `false` | Defina `true` para consultar o seu endpoint de decisão antes de a API aceitar um Pix recebido ou uma devolução recebida. |
| `ANTIFRAUD_HOOK_URL` | **Obrigatório** quando ativada | URL do seu endpoint de decisão. Ela deve usar `https`, a menos que `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK=true`. |
| `ANTIFRAUD_HOOK_TIMEOUT_MS` | `500` | Quanto tempo a API espera por uma decisão, em milissegundos. O mínimo é `100`. |
| `ANTIFRAUD_HOOK_FALLBACK_DECISION` | — | `APPROVE` ou `REJECT`: a decisão que a API aplica quando não recebe uma decisão. |
| `ANTIFRAUD_HOOK_FALLBACK_MAX_APPROVE_AMOUNT` | — | Quando a API não recebe uma decisão, ela aprova um valor até este limite e rejeita um valor maior. Defina exatamente uma das duas variáveis de fallback. |
| `ANTIFRAUD_HOOK_HMAC_SECRET` | 🔒 **Obrigatório** quando ativada | Segredo que assina cada requisição com HMAC-SHA256. Pelo menos 32 caracteres. |
| `ANTIFRAUD_HOOK_AUTH_HEADER_NAME` · `ANTIFRAUD_HOOK_AUTH_HEADER_VALUE` | 🔒 — | Um header que a API adiciona a cada requisição. Defina os dois ou nenhum. |
| `ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK` | `false` | Defina `true` para permitir uma URL `http` e um endpoint em uma rede privada. |
| `ANTIFRAUD_HOOK_CB_ENABLED` | `true` | Circuit breaker para as chamadas ao seu endpoint. Enquanto o circuit breaker está aberto, a API aplica o fallback sem fazer a chamada. |
| `ANTIFRAUD_HOOK_CB_FAILURE_THRESHOLD` · `ANTIFRAUD_HOOK_CB_TIMEOUT` · `ANTIFRAUD_HOOK_CB_MAX_REQUESTS` · `ANTIFRAUD_HOOK_CB_INTERVAL` | `5` · `30s` · `3` · `60s` | Falhas consecutivas que abrem o circuit breaker, quanto tempo ele fica aberto, chamadas de teste depois disso e o período que zera a contagem de falhas. Um intervalo de `0` nunca a zera. |
| `ANTIFRAUD_HOOK_PREWARM_ENABLED` | `true` | Envia um `GET` sem assinatura à URL do endpoint a cada 60 segundos para manter uma conexão aberta. |

## Eventos de negócio

Estas variáveis configuram os [eventos do Pix BTG](https://docs.lerian.studio/pt/reference/events/pix-btg.md) no componente da API. Quando `STREAMING_ENABLED` é `false`, a API ignora as outras variáveis desta tabela.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Defina `true` para publicar eventos de negócio. |
| `STREAMING_BROKERS` | **Obrigatório** quando ativado | Brokers Kafka de bootstrap, em uma lista `host:port` separada por vírgulas. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `plugin-br-pix-indirect-btg` | O `ce-source` de cada evento. Ele também dá nome ao tópico `lerian.streaming.<source>`. |
| `STREAMING_TENANT_ID` | `default` | O `ce-tenantid` de cada evento: de 1 a 256 letras ASCII, dígitos, `-` ou `_`, começando por uma letra ou um dígito. |
| `STREAMING_CLIENT_ID` | — | ID de cliente Kafka. |
| `STREAMING_TLS_ENABLED` · `STREAMING_TLS_CA_CERT` | `false` · — | TLS com os brokers e uma CA PEM codificada em base64. Sem uma CA, a API usa o repositório de confiança do sistema. |
| `STREAMING_SASL_MECHANISM` · `STREAMING_SASL_USERNAME` · `STREAMING_SASL_PASSWORD` | 🔒 — | Autenticação SASL com os brokers: `PLAIN`, `SCRAM-SHA-256` ou `SCRAM-SHA-512`. Um mecanismo vazio desliga o SASL. |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Permite SASL sem TLS. Use apenas em desenvolvimento local. |
| `STREAMING_CB_FAILURE_RATIO` · `STREAMING_CB_MIN_REQUESTS` · `STREAMING_CB_TIMEOUT_S` | `0.5` · `10` · `30` | Circuit breaker para os brokers. Enquanto ele está aberto, os eventos com fallback para o outbox vão para o outbox. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Tempo máximo, em segundos, para descarregar os eventos no desligamento. |
| `STREAMING_TOPIC_AUTO_PROVISION` · `STREAMING_TOPIC_PARTITIONS` · `STREAMING_TOPIC_REPLICATION_FACTOR` | `true` · `-1` · `-1` | Cria os tópicos na inicialização. `-1` usa o padrão do broker. Defina `false` quando você cria os tópicos com antecedência. |
| `STREAMING_OUTBOX_RETENTION_PUBLISHED_H` · `STREAMING_OUTBOX_RETENTION_INVALID_H` | `72` · `720` | Horas para manter os registros publicados e inválidos do outbox. `0` desliga a exclusão deles. |

## Health e readiness

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `HEALTH_PORT` | **Obrigatório** em cada worker | A porta do listener de health, por exemplo `8099` na API. Ele serve `GET /health`, `GET /readyz`, `GET /metrics` e `GET /version`. Um worker sem ela falha na inicialização. A API sem ela não tem endpoint de readiness. Mantenha essa porta interna. |

Aponte a probe de readiness de cada componente para o `HEALTH_PORT` dele.

A API e o worker de conciliação só ficam prontos quando o PostgreSQL (primário) e o Redis respondem. Os workers de webhooks de entrada e de saída esperam apenas o PostgreSQL. O worker de agendamento informa apenas o próprio loop. Após a inicialização, uma réplica do PostgreSQL ou um MongoDB com falha aparece como `degraded` e o pod continua em rotação. Com `STREAMING_ENABLED=true`, a verificação `streaming` informa da mesma forma. Cada worker também informa o próprio loop de trabalho como uma verificação de liveness. 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.