> ## 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
> Variáveis de ambiente definidas no deploy, distintivas do Lerian SLC: transporte Núclea/RSFN, o barramento de entrada SFN, o sidecar de assinatura e a grade de liquidação.
O Lerian SLC é o trilho de liquidação de propriedade da Lerian que compensa e liquida pelo SLC da Núclea através da RSFN. Você define essas variáveis no momento do deploy. Um reinício do serviço as aplica. Todo serviço Go da Lerian compartilha uma base universal: servidor, datastores, multi-tenancy, telemetria, autenticação de plugin e licenciamento. [Fundamentos de configuração do BYOC](/pt/reference/byoc-configuration) documenta essa base uma única vez. Esta página cobre apenas as variáveis distintivas do Lerian SLC.
Nas tabelas abaixo, a coluna **Padrão / Obrigatório** mostra o valor padrão. Um qualificador em negrito (por exemplo, **Obrigatório**, **Obrigatório em produção**) marca uma variável que você deve definir. `—` significa que não há padrão. Uma variável marcada como **Sensível** carrega material de credencial ou chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor.
## Serviço e runtime
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS` | `:4111` | Endereço de escuta HTTP principal. Os probes de liveness, readiness, metrics e version usam essa mesma porta. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API administrativa de configuração em runtime do [Systemplane](/pt/reference/platform/systemplane/overview) sob o prefixo `/system` na porta principal. Desabilitada por padrão (modo apenas variáveis de ambiente). |
| `TENANT_RUNTIME_CONFIG_ENABLED` | `false` | Habilita o armazenamento de configuração em runtime por tenant e a superfície administrativa, resolvendo o transporte de conectividade de cada tenant a partir de um registro por tenant em vez da configuração compartilhada. Apenas seleção e política. |
O Lerian SLC expõe `/health` (liveness) e `/readyz` (readiness) na porta principal, além de `/version` e `/metrics`. Quando você habilita a multi-tenancy, ele também expõe `GET /readyz/tenant/{id}`. Veja [Saúde e prontidão](/pt/reference/health-and-readiness) para o contrato dos probes.
## Transporte REST da Núclea
Esse canal submete à Núclea online por TLS mútuo. Deixe `NUCLEA_REST_BASE_URL` vazio para manter o transporte desconectado.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NUCLEA_REST_BASE_URL` | — | URL base do nó da Núclea. Vazio desabilita o submissor online. Em produção, aponta para o endpoint da Núclea; localmente, aponta para um simulador. |
| `NUCLEA_REST_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos. |
| `NUCLEA_REST_CB_CONSECUTIVE_FAILURES` | `5` | Falhas consecutivas que abrem o circuit breaker. |
| `NUCLEA_REST_CB_OPEN_TIMEOUT_SEC` | `30` | Por quanto tempo o breaker permanece aberto antes de meio aberto. |
| `NUCLEA_REST_ALLOW_INSECURE_TLS` | `false` | Relaxa a verificação TLS da Núclea apenas para desenvolvimento local. A inicialização é recusada quando isso é `true` sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`. |
| `NUCLEA_REST_CLIENT_CERT_PATH` | **Obrigatório em produção/SaaS** | Caminho do certificado de cliente PEM apresentado à Núclea para TLS mútuo. |
| `NUCLEA_REST_CLIENT_KEY_PATH` | **Obrigatório em produção/SaaS** | Caminho da chave privada de cliente PEM para TLS mútuo. Sensível — o arquivo contém material de chave privada. |
## Consumidor de entrada RSFN
Esse canal recebe mensagens de entrada da RSFN. Ele também observa a conformidade com o XSD.
| Variável | Padrão / Obrigatório | Descrição |
| --------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RSFN_CONSUMER_TRANSPORT` | `stub` | Transporte de entrada por trás da porta do consumidor RSFN: `stub` (um canal REST de desenvolvimento) ou `mq` (o transporte de rede RSFN, conectado na homologação). |
| `MQ_BRIDGE_URL` | **Obrigatório se transporte `mq`** | URL base da ponte MQ. Você deve declará-la explicitamente quando `RSFN_CONSUMER_TRANSPORT=mq`; ela não pode herdar `http://localhost:9121`, porque o endereço correto depende da sua topologia de deployment. |
| `RSFN_CONSUMER_BASE_URL` | — | URL base para o transporte `stub`. Vazio deixa o consumidor desconectado. |
| `RSFN_CONSUMER_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos. |
| `CIRCUIT_BREAKER_ENABLED` | `false` | Habilita o gerenciador compartilhado de circuit breaker. O gerenciador protege mais do que este consumidor: a inicialização falha de forma fechada quando o consumidor RSFN (`stub` ou `mq`), o canal REST da Núclea (`NUCLEA_REST_BASE_URL` definida) ou o caminho Connect:Direct é configurado sem ele. |
| `RSFN_CONSUMER_CB_CONSECUTIVE_FAILURES` | `5` | Falhas consecutivas que abrem o breaker do consumidor RSFN quando `CIRCUIT_BREAKER_ENABLED=true`. |
| `RSFN_CONSUMER_CB_OPEN_TIMEOUT_SEC` | `30` | Por quanto tempo o breaker permanece aberto antes de meio aberto. |
| `RSFN_CONSUMER_ALLOW_INSECURE_TLS` | `false` | Relaxa a verificação TLS do canal stub apenas para desenvolvimento local. Forçado para `false` sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`. |
| `RSFN_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Validação XSD apenas observacional das mensagens de entrada RSFN/SILOC em relação aos schemas oficiais. Registra em log e mede a não conformidade sem alterar o despacho. |
| `ASLC_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Validação XSD apenas observacional das mensagens de retorno ASLC de entrada. Registra em log e mede a não conformidade sem alterar o pipeline de retorno. |
| `XSD_VALIDATOR_URL` | `http://localhost:9091` | URL base do sidecar de validação XSD que os observadores chamam. |
| `XSD_VALIDATOR_TIMEOUT_SEC` | `10` | Timeout por requisição, em segundos, para chamadas de validação XSD. |
## Barramento de entrada SFN
O barramento SFN retransmite mensagens SILOC. Esse caminho as ingere. Toda a família permanece inerte a menos que você defina `SFN_INGEST_ENABLED=true`.
| Variável | Padrão / Obrigatório | Descrição |
| ---------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- |
| `SFN_INGEST_ENABLED` | `false` | Chave mestra do caminho de ingestão SFN (consumidor de barramento e driver). |
| `SFN_BUS_PROVIDER` | `kafka` | Adaptador do consumidor: `kafka` ou `stub` (desenvolvimento/CI). |
| `SFN_KAFKA_BROKERS` | **Obrigatório se ingestão ativa e provider `kafka`** | Lista de brokers de bootstrap Kafka/RedPanda separados por vírgula. |
| `SFN_KAFKA_TOPIC` | `siloc.inbound` | Tópico no qual o relay do SILOC publica. |
| `SFN_KAFKA_GROUP_ID` | padrão com escopo de serviço | ID do grupo de consumidores Kafka; sobrescreva por deployment quando necessário. |
| `SFN_KAFKA_BATCH_SIZE` | `100` | Registros lidos por lote. |
| `SFN_STUB_TIMEOUT_SEC` | `30` | Timeout por requisição, em segundos, para o adaptador `stub`. |
## Sidecar de assinatura
O Lerian SLC assina o envelope de segurança SPB por meio de um sidecar de assinatura sem estado. A chave privada nunca entra no processo do serviço. Você seleciona o backend de custódia por deployment.
| Variável | Padrão / Obrigatório | Descrição |
| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGNER_URL` | `http://localhost:9101` | URL base do sidecar de assinatura. |
| `SIGNER_TIMEOUT_SEC` | `10` | Timeout por requisição, em segundos, para chamadas de assinatura. |
| `SIGNER_SOFTKEY_PFX_PASSPHRASE` | — | Frase-senha para o adaptador de custódia de chave de software. Sensível. A postura de chave de software é recusada sob `ENV_NAME=production`, a menos que explicitamente permitida. |
| `SIGNER_SOFTKEY_ALLOW_IN_PRODUCTION` | `false` | Permite a postura de chave de software em processo em produção. Deixe `false` — um caminho de custódia por hardware ou cloud KMS é a postura de produção. |
| `SIGNER_AWSKMS_DEFAULT_KEY_REF` | — | Referência de chave de fallback opcional para o adaptador de custódia cloud KMS, usada apenas quando uma requisição não fornece nenhuma. O material de chave nunca entra no processo — apenas a referência é passada. O adaptador cloud KMS precisa de `SIGNER_AWSKMS_REGION`, a região AWS da chave KMS, que o deployment padrão deriva da `AWS_REGION` compartilhada. |
## Grade de liquidação
O Lerian SLC condiciona o despacho às janelas de liquidação da Núclea e executa um worker de grade por tenant.
| Variável | Padrão / Obrigatório | Descrição |
| ----------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SCHEDULE_CREDIT_WINDOW_OPEN` | **Obrigatório em todo ambiente** | Abertura da janela de aceitação de crédito, no formato `HH:MM` do horário local de São Paulo (intervalo semiaberto, com o limite de abertura inclusivo). Declare-a explicitamente para a grade em vigor. |
| `SCHEDULE_CREDIT_WINDOW_CLOSE` | **Obrigatório em todo ambiente** | Fechamento da janela de aceitação de crédito, no formato `HH:MM` do horário local de São Paulo (exclusivo). Declare-o explicitamente para a grade em vigor. |
| `SCHEDULE_WORKER_ENABLED` | `true` | Habilita o worker recorrente de grade por tenant (alerta de corte e, quando habilitados, os drivers de despacho e retorno). |
| `SCHEDULE_WORKER_INTERVAL_SEC` | `30` | Período de tick do worker de grade, em segundos. |
| `SCHEDULE_GRID_GATE_ENABLED` | `false` | Condiciona o despacho à grade STR baseada em calendário, em vez da janela de crédito única. |
| `SCHEDULE_CUTOFF_ALERT_LEAD_MIN` | `30` | Minutos antes de um corte STR nos quais a janela entra em pré-corte e um alerta é emitido. |
| `SCHEDULE_DISPATCH_MAX_TRANSMIT_ATTEMPTS` | `20` | Tentativas de transmissão que um despacho pode consumir antes que a operação seja colocada em espera para revisão do operador, em vez de tentar novamente para sempre. No tick padrão de 30 segundos, 20 tentativas equivalem a cerca de dez minutos antes do primeiro alerta. |
| `SCHEDULE_HOLIDAYS` | — | Feriados bancários no formato `YYYY-MM-DD`, separados por vírgula, no horário local de São Paulo; a grade nunca abre uma janela em um feriado. |
Você deve declarar as duas variáveis de janela de crédito, mesmo quando usa a grade padrão. O serviço recusa iniciar se qualquer um dos valores for omitido ou estiver em branco. Ele nunca presume uma grade de crédito a partir de um padrão.
O Lerian SLC traz uma família de toggles de runtime por driver. Cada toggle habilita um fluxo no worker de grade: despacho e repasse de crédito e débito, antecipação, cancelamento, relay de status, confirmação D+1 e alertas de operação travada. Cada um é uma chave `SCHEDULE_*_ENABLED` cujo padrão é `false`. Você habilita cada um durante a homologação, assim que o material Núclea por tenant estiver pronto. Os parâmetros de cadência e lote seguem o padrão `*_INTERVAL_SEC` / `*_BATCH_SIZE` / `*_PAGE_SIZE`.
## Webhooks
O Lerian SLC pode entregar eventos de liquidação a um endpoint assinante. No BYOC, o cliente fornece o material de credencial por meio do seu próprio secret do Kubernetes.
| Variável | Padrão / Obrigatório | Descrição |
| -------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_WORKER_ENABLED` | `false` | Habilita o worker de entrega de webhook por tenant. |
| `WEBHOOK_DELIVERY_PROVIDER` | `direct` | Adaptador de entrega: `direct` (HTTP HMAC do BYOC) ou `notifications` (SaaS). |
| `WEBHOOK_API_KEY` | **Obrigatório se entregando** | Chave de API definida pelo cliente, enviada no header de chave de API do webhook. Sensível. |
| `WEBHOOK_API_KEY_FILE` | — | Caminho para um arquivo que contém a chave de API (um volume de secret montado). Quando definido, o valor inline é ignorado. |
| `WEBHOOK_HMAC_SECRET` | **Obrigatório se entregando** | Segredo compartilhado definido pelo cliente, usado para assinar cada webhook. Sensível. Nunca vem do plano de configuração em runtime nem do banco de dados. |
| `WEBHOOK_HMAC_SECRET_FILE` | — | Caminho para um arquivo que contém o segredo HMAC (um volume de secret montado). Quando definido, o valor inline é ignorado. |
| `WEBHOOK_MAX_ATTEMPTS` | `6` | Orçamento de tentativas por assinatura antes que uma entrega seja colocada em espera na fila de dead-letter. |
| `WEBHOOK_ALLOW_PRIVATE_NETWORK` | `false` | Relaxamento apenas para desenvolvimento do bloqueio de SSRF na entrega. Deve permanecer `false` em produção/SaaS — caso contrário, a inicialização falha de forma fechada. |
| `WEBHOOK_NOTIFICATIONS_BASE_URL` | **Obrigatório se provider `notifications`** | URL base do serviço de notificações usado pelo provider SaaS. |