> ## 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 distintivas do Lerian SLC — transporte Núclea/RSFN, o barramento de entrada SFN, o sidecar de assinatura e a agenda de liquidação.
O Lerian SLC é o rail de liquidação de propriedade da Lerian que compensa e liquida sobre o SLC da Núclea através da RSFN. Essas variáveis são definidas no momento do deploy e exigem uma reinicialização do serviço para entrar em vigor. O backbone universal que todo serviço Go da Lerian compartilha — servidor, datastores, multi-tenancy, telemetria, autenticação de plugin e licenciamento — é documentado uma única vez na [referência de configuração BYOC](/pt/reference/byoc-configuration); esta página cobre apenas as variáveis distintivas do Lerian SLC.
Nas tabelas abaixo, a coluna **Padrão / Obrigatória** mostra o valor padrão; um qualificador em negrito (ex: **Obrigatória**, **Obrigatória em produção**) marca variáveis que devem ser definidas. `—` significa que não há padrão. Qualquer variável marcada como **Sensível** carrega material de credencial ou de chave — injete-a a partir do seu gerenciador de segredos no momento do deploy e nunca faça commit de um valor.
## Serviço e runtime
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SERVER_ADDRESS` | `:4111` | Endereço de escuta HTTP principal. As probes de liveness, readiness, metrics e version se vinculam a essa mesma porta. |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita a API de administração de configuração de runtime do [Systemplane](/pt/reference/systemplane/overview) sob o prefixo `/system` na porta principal. Desligada por padrão (modo apenas variáveis de ambiente). |
| `TENANT_RUNTIME_CONFIG_ENABLED` | `false` | Habilita o store de configuração de runtime por tenant e sua superfície de administração, 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`, e — quando a multi-tenancy está habilitada — `GET /readyz/tenant/{id}`. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o contrato das probes.
## Transporte REST da Núclea
O canal de submissão online para a Núclea sobre TLS mútuo. Deixe `NUCLEA_REST_BASE_URL` vazio para manter o transporte não conectado.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NUCLEA_REST_BASE_URL` | — | URL base do nó da Núclea. Vazio desabilita o submitter online. Em produção isso 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 de TLS da Núclea apenas para desenvolvimento local. O boot é rejeitado quando isso é `true` sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`. |
| `NUCLEA_REST_CLIENT_CERT_PATH` | **Obrigatória em produção/SaaS** | Caminho para o certificado de cliente PEM apresentado à Núclea para TLS mútuo. |
| `NUCLEA_REST_CLIENT_KEY_PATH` | **Obrigatória em produção/SaaS** | Caminho para a chave privada de cliente PEM para TLS mútuo. Sensível — o arquivo contém material de chave privada. |
## Consumidor de entrada da RSFN
O canal de entrada para mensagens da RSFN, além de observação opcional de conformidade XSD.
| Variável | Padrão / Obrigatória | Descrição |
| --------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RSFN_CONSUMER_TRANSPORT` | `stub` | Transporte de entrada por trás da porta do consumidor da RSFN: `stub` (um canal REST de desenvolvimento) ou `mq` (o transporte de rede da RSFN, conectado na homologação). |
| `RSFN_CONSUMER_BASE_URL` | — | URL base para o transporte `stub`. Vazio deixa o consumidor não conectado. |
| `RSFN_CONSUMER_TIMEOUT_SEC` | `30` | Timeout por requisição em segundos. |
| `RSFN_CONSUMER_CB_CONSECUTIVE_FAILURES` | `5` | Falhas consecutivas que abrem o circuit breaker. |
| `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 de TLS do canal stub apenas para desenvolvimento local. Forçado a `false` sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`. |
| `RSFN_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Validação XSD apenas observação das mensagens RSFN/SILOC de entrada contra os schemas oficiais. Registra em log e mede a não-conformidade sem alterar o dispatch. |
| `ASLC_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Validação XSD apenas observação 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` | — | 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
Ingestão de mensagens SILOC retransmitidas pelo barramento SFN. Toda a família fica inerte a menos que `SFN_INGEST_ENABLED=true`.
| Variável | Padrão / Obrigatória | Descrição |
| ---------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| `SFN_INGEST_ENABLED` | `false` | Chave mestra para o caminho de ingestão SFN (consumidor do barramento e driver). |
| `SFN_BUS_PROVIDER` | `kafka` | Adaptador de consumidor: `kafka` ou `stub` (desenvolvimento/CI). |
| `SFN_KAFKA_BROKERS` | **Obrigatória se ingest ligado 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` | `—` | Id do consumer group do Kafka; definido por implantação. |
| `SFN_KAFKA_BATCH_SIZE` | `100` | Registros lidos por batch. |
| `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 do SPB através de um sidecar de assinatura stateless, de modo que a chave privada nunca entre no processo do serviço. A custódia é selecionável por deployment.
| Variável | Padrão / Obrigatória | Descrição |
| ------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SIGNER_URL` | **Obrigatória** | URL base do sidecar de assinatura. |
| `SIGNER_TIMEOUT_SEC` | `10` | Timeout por requisição em segundos para chamadas de assinatura. |
| `SIGNER_SOFTKEY_PFX_PASSPHRASE` | — | Passphrase para o adaptador de custódia de chave em software. Sensível. A postura de chave em software é recusada sob `ENV_NAME=production` a menos que explicitamente permitida. |
| `SIGNER_SOFTKEY_ALLOW_IN_PRODUCTION` | `false` | Permite a postura de chave em software in-process em produção. Mantenha `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. A região de custódia vem do `AWS_REGION` compartilhado. |
## Agenda de liquidação
O Lerian SLC controla o dispatch para as janelas de liquidação da Núclea e roda um worker de agenda por tenant.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `SCHEDULE_CREDIT_WINDOW_OPEN` | `00:30` | Abertura da janela de aceitação de crédito, como `HH:MM` no horário local de São Paulo (intervalo semiaberto, inclusivo). |
| `SCHEDULE_CREDIT_WINDOW_CLOSE` | `17:30` | Fechamento da janela de aceitação de crédito, como `HH:MM` no horário local de São Paulo (exclusivo). |
| `SCHEDULE_WORKER_ENABLED` | `true` | Habilita o worker de agenda recorrente por tenant (alertas de cutoff e, quando habilitados, os drivers de dispatch e de retorno). |
| `SCHEDULE_WORKER_INTERVAL_SEC` | `30` | Período de tick do worker de agenda em segundos. |
| `SCHEDULE_GRID_GATE_ENABLED` | `false` | Controla o dispatch pela grade STR apoiada em calendário em vez da janela única de crédito. |
| `SCHEDULE_CUTOFF_ALERT_LEAD_MIN` | `30` | Minutos antes de um cutoff STR em que a janela entra em pré-cutoff e um alerta é emitido. |
| `SCHEDULE_HOLIDAYS` | — | Feriados bancários `YYYY-MM-DD` separados por vírgula no horário local de São Paulo; a grade nunca abre uma janela em um feriado. |
O Lerian SLC entrega uma família de toggles de runtime por driver que habilitam cada fluxo de liquidação no worker de agenda — dispatch e forward de crédito e débito, antecipação, cancelamento, relay de status, confirmação D+1 e alertas de operação travada. Cada um é um switch `SCHEDULE_*_ENABLED` que assume `false` por padrão e é habilitado durante a homologação assim que o material da Núclea por tenant é provisionado. Sua cadência e seus parâmetros de batch 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 através do seu próprio secret do Kubernetes.
| Variável | Padrão / Obrigatória | Descrição |
| -------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WEBHOOK_WORKER_ENABLED` | `false` | Habilita o worker de entrega de webhooks por tenant. |
| `WEBHOOK_DELIVERY_PROVIDER` | `direct` | Adaptador de entrega: `direct` (HTTP HMAC do BYOC) ou `notifications` (SaaS). |
| `WEBHOOK_API_KEY` | **Obrigatória se houver entrega** | Chave de API definida pelo cliente enviada no header de API-key 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ória se houver entrega** | Segredo compartilhado definido pelo cliente usado para assinar cada webhook. Sensível. Nunca vem do plano de configuração de 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_DELIVERY_TIMEOUT_SEC` | `10` | Limite para uma única tentativa de POST de webhook, em segundos. |
| `WEBHOOK_MAX_ATTEMPTS` | `6` | Orçamento de retries por assinatura antes de uma entrega ser estacionada na dead-letter queue. |
| `WEBHOOK_ALLOW_PRIVATE_NETWORK` | `false` | Relaxamento apenas para desenvolvimento do bloqueio SSRF da entrega. Deve permanecer `false` em produção/SaaS — caso contrário o boot falha fechado. |
| `WEBHOOK_NOTIFICATIONS_BASE_URL` | **Obrigatória se provider `notifications`** | URL base do serviço de notifications usado pelo provider SaaS. |