> ## 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 propriedade da Lerian para a mensageria de liquidação de cartões com o SLC da Núclea. 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, telemetria e autenticação de plugin. [Fundamentos de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md) documenta essa base uma única vez. Esta página cobre 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](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) 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. |

> [!NOTE]
>
> O Lerian SLC expõe `/health` (liveness) e `/readyz` (readiness) na porta principal, além de `/version` e `/metrics`. Veja [Saúde e prontidão](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato dos probes. Uma instalação atende uma instituição.

## Licença

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `LICENSE_KEY` | **Obrigatório** | Credencial de licença emitida pela Lerian. Sensível. |
| `ORGANIZATION_IDS` | **Obrigatório** | Defina como `global`. Veja [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md). |

## Entrada de operações

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `INTAKE_BATCH_MAX_LINES` | `50000` | Limite de linhas da entrada em lote. Um lote acima dele responde `413` e não salva nada. |
| `INTAKE_BATCH_SPOOL_MAX_BYTES` | `268435456` | Limite de bytes da entrada em lote. Um lote acima dele responde `413` e não salva nada. |
| `INTAKE_BATCH_SPOOL_DIR` | diretório temporário do sistema | Diretório em que a entrada em lote armazena temporariamente o corpo enquanto conta as linhas. Aponte-o para um volume gravável quando o sistema de arquivos raiz for somente leitura. |

## 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 todo o transporte REST: submissão online, polling de retornos, consultas e submissão de arquivos. Sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`, a URL deve usar `https`. Localmente, ela 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_RESPONSE_CERT_PATH` | **Obrigatório, a menos que a URL base seja um destino de desenvolvimento** | Caminho do certificado público da Núclea, que verifica a assinatura de cada resposta. A inicialização falha quando ele está vazio e a URL base aponta para qualquer outro lugar. |
| `NUCLEA_REST_CLIENT_CERT_PATH` | **Obrigatório em produção/SaaS quando a URL base está definida** | Caminho do certificado de cliente PEM apresentado à Núclea para TLS mútuo. |
| `NUCLEA_REST_CLIENT_KEY_PATH` | **Obrigatório em produção/SaaS quando a URL base está definida** | 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 pela ponte MQ). Outro valor impede a inicialização. O consumidor drena as mensagens apenas quando `SCHEDULE_RSFN_INGEST_ENABLED=true`. |
| `MQ_BRIDGE_URL` | **Obrigatório quando o transporte MQ está em uso** | URL base da ponte MQ. Você deve declará-la explicitamente com `RSFN_CONSUMER_TRANSPORT=mq` ou com a seleção de transporte por tenant ativa; ela não pode herdar `http://localhost:9121`, porque o endereço correto depende da topologia do seu deploy. |
| `MQ_BRIDGE_QUEUE_MANAGER`, `MQ_BRIDGE_CHANNEL`, `MQ_BRIDGE_CONN_NAME`, `MQ_BRIDGE_QUEUE` | **Obrigatório quando o transporte MQ está em uso** | Detalhes de conexão do IBM MQ que o transporte MQ entrega à ponte. Com uma fila em branco, cada drenagem falha de forma fechada. |
| `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: sem ele, a inicialização falha de forma fechada quando o canal `stub` tem uma URL base, quando o transporte MQ está em uso ou quando `NUCLEA_REST_BASE_URL` está definida. |
| `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. Em produção ou SaaS, o canal stub sempre verifica o TLS. |
| `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. |
| `RSFN_INBOUND_XSD_FAIL_CLOSED_CODMSGS` | — | Tipos de mensagem da RSFN e do Lerian SILOC, separados por vírgula, que saem do modo apenas observacional: uma falha de XSD envia a mensagem para a fila de dead-letter. Um tipo de mensagem que o serviço não roteia faz a inicialização ser recusada. |
| `ASLC_INBOUND_XSD_FAIL_CLOSED_CODMSGS` | — | Tipos de retorno ASLC, separados por vírgula, que saem do modo apenas observacional: uma falha de XSD deixa o retorno sem confirmação para a próxima consulta. Um tipo de retorno que o serviço não roteia faz a inicialização ser recusada. |
| `XSD_VALIDATOR_URL` | `http://localhost:9091` | URL base do sidecar de validação XSD. Os observadores de entrada o chamam, assim como a construção do arquivo de saída, que falha de forma fechada quando o sidecar não responde. |
| `XSD_VALIDATOR_TIMEOUT_SEC` | `10` | Timeout por requisição, em segundos, para chamadas de validação XSD. |

## Barramento de entrada SFN

O Lerian SILOC repassa suas mensagens ao Lerian SLC pelo barramento SFN. `SFN_INGEST_ENABLED` ativa a ingestão das mensagens repassadas. `SFN_FACTS_INGEST_ENABLED` ativa a ingestão dos resultados dos comandos de liquidação que o Lerian SLC envia. Os dois consumidores usam os mesmos brokers e o mesmo tamanho de lote.

| 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 a ingestão estiver ativa com o provider `kafka`, ou se a ingestão de fatos estiver ativa** | 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 deploy 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`. |
| `SFN_FACTS_INGEST_ENABLED` | `false` | Chave mestra do consumidor dos resultados dos comandos de liquidação. |
| `SFN_FACTS_KAFKA_TOPIC` | `siloc.outbound.facts` | Tópico no qual o Lerian SILOC publica os resultados dos comandos. |
| `SFN_FACTS_KAFKA_GROUP_ID` | padrão com escopo de serviço | ID do grupo de consumidores Kafka do consumidor de fatos, distinto de `SFN_KAFKA_GROUP_ID`. |

## Streaming

O Lerian SLC e a biblioteca de streaming da Lerian leem a família `STREAMING_`. O [Lerian Streaming Hub](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) entrega os eventos publicados.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Chave mestra do produtor de streaming. O produtor publica eventos de negócio e entrega os comandos LBTR ao Lerian SILOC. Ela também exige `OUTBOX_ENABLED=true`. |
| `STREAMING_BROKERS` | **Obrigatório** quando o streaming está ativado | Lista de bootstrap de brokers separada por vírgulas. Uma configuração ativada com uma lista vazia recusa o boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Obrigatório** quando o streaming está ativado | A fonte CloudEvents deste serviço. Defina-a com o valor de `publisher.source` do manifesto de eventos que `GET /v1/streaming/manifest` retorna. O serviço serve o manifesto com o streaming desativado. Um valor vazio ou malformado recusa o boot quando o streaming está ativado. |
| `STREAMING_CLIENT_ID` | `primary` | Identificador de cliente do broker usado para diagnósticos do lado do broker. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Janela máxima de drenagem e flush, em segundos, quando o produtor encerra. |
| `STREAMING_TOPIC_AUTO_PROVISION` | `true` | Com o streaming ativado, cria o tópico de eventos `lerian.streaming.<source>` e o tópico de dead-letter `lerian.streaming.<source>.dlq` quando eles não existem no boot. `<source>` é o valor de `STREAMING_CLOUDEVENTS_SOURCE`. Uma criação recusada ou com falha registra um aviso, e o boot continua. Defina `false` quando você mesmo provisiona os tópicos. |
| `STREAMING_TOPIC_PARTITIONS` | Padrão do broker | Número de partições dos tópicos que o serviço cria. Um valor ausente, zero ou inválido usa o padrão do broker. |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | Padrão do broker | Fator de replicação dos tópicos que o serviço cria. Um valor ausente, zero ou inválido usa o padrão do broker. |
| `STREAMING_HEALTH_CHECK_TIMEOUT` | `2s` | Tempo limite da verificação de streaming na probe de readiness. |

## 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 de assinatura nunca entra no processo do serviço. O registro de custódia ativo de cada participante seleciona o adaptador de custódia e a chave que assinam as mensagens dele. O sidecar ativa cada adaptador de custódia apenas quando as configurações próprias desse adaptador estão presentes.

| Variável | Padrão / Obrigatório | Descrição |
| - | - | - |
| `SIGNING_CUSTODY_ADAPTER` | `softkey` | Adaptador de custódia que a verificação de inicialização espera no sidecar de assinatura: `softkey`, `pkcs11` ou `awskms`. Ele não seleciona a custódia de cada participante. Sob `DEPLOYMENT_MODE=saas`, ele é sempre `awskms`, e o Lerian SLC recusa um registro de custódia que aponta para outro adaptador. |
| `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_PATH` | — | Caminho do arquivo PKCS#12 do adaptador de chave de software. Defini-lo ativa o adaptador. |
| `SIGNER_SOFTKEY_PFX_PASSPHRASE` | — | Frase-senha para o adaptador de custódia de chave de software. Sensível. |
| `SIGNER_SOFTKEY_ALLOW_IN_PRODUCTION` | `false` | Sob `ENV_NAME=production`, o sidecar de assinatura inicia apenas quando isso é `true`, seja qual for o adaptador de custódia que você usa. |
| `SIGNER_AWSKMS_REGION` | — | Região AWS das chaves KMS. Defini-la ativa o adaptador cloud KMS e a importação de chaves de assinatura. |
| `SIGNER_PKCS11_MODULE` | padrão da imagem | Caminho do módulo PKCS#11 do HSM. |
| `SIGNER_PKCS11_TOKEN_LABEL` ou `SIGNER_PKCS11_SLOT` | — | Token do HSM, por rótulo ou por slot. Definir um deles ativa o adaptador HSM, que então exige o módulo, o PIN e o rótulo da chave. |
| `SIGNER_PKCS11_PIN` | **Obrigatório com um token de HSM** | PIN do token do HSM. Sensível. |
| `SIGNER_PKCS11_KEY_LABEL` | **Obrigatório com um token de HSM** | Rótulo da chave de assinatura dentro do token. |

## Grade de liquidação

O Lerian SLC condiciona o despacho às janelas de liquidação da Núclea e executa um worker de grade.

| 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. `HH:MM+1` atravessa a meia-noite, e apenas a grade `especial1` o aceita. |
| `SCHEDULE_SPECIAL_GRADE` | `none` | Grade da Núclea que a janela de crédito deve obedecer: `none`, `especial1` ou `especial2`. Outro valor impede a inicialização. Sob `ENV_NAME=production` ou `DEPLOYMENT_MODE=saas`, a janela de crédito deve caber na grade. |
| `SCHEDULE_WORKER_ENABLED` | `true` | Habilita o worker recorrente de grade (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` | Recusas consecutivas da contraparte que uma submissão de saída pode receber antes que o Lerian SLC coloque a operação em espera para revisão do operador. Uma falha de transporte não conta, e um sucesso zera a contagem. No tick padrão de 30 segundos, 20 recusas 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; nenhuma janela abre em um feriado. Uma data malformada impede a inicialização. |

> [!NOTE]
>
> Você deve declarar as duas variáveis de janela de crédito, mesmo quando usa a grade permanente. O serviço se recusa a 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.

> [!NOTE]
>
> Cada fluxo roda no worker de grade apenas quando o toggle dele é `true`. Cada toggle tem `false` como padrão: `SCHEDULE_DISPATCH_ENABLED`, `SCHEDULE_FORWARD_ENABLED`, `SCHEDULE_DEBIT_DISPATCH_ENABLED`, `SCHEDULE_DEBIT_FORWARD_ENABLED`, `SCHEDULE_ANTICIPATION_DISPATCH_ENABLED`, `SCHEDULE_ANTICIPATION_FORWARD_ENABLED`, `SCHEDULE_ANTICIPATION_SETTLE_ENABLED`, `SCHEDULE_CANCELLATION_DISPATCH_ENABLED`, `SCHEDULE_CANCELLATION_FORWARD_ENABLED`, `SCHEDULE_RETURN_POLL_ENABLED`, `SCHEDULE_RELAY_STATUS_ENABLED`, `SCHEDULE_VARREDURA_ENABLED`, `SCHEDULE_RSFN_INGEST_ENABLED`, `SCHEDULE_D1_CONFIRMATION_ENABLED`, `SCHEDULE_CONFIRMATION_OVERDUE_ENABLED`, `SCHEDULE_OPERATION_STUCK_ENABLED`, `SCHEDULE_CERT_EXPIRY_ENABLED`, `SCHEDULE_SILOC_WINDOWS_ENABLED`, `SCHEDULE_STR_SETTLED_ENABLED` e `OP107_VERDICT_POLL_ENABLED`.

## 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. |
| `WEBHOOK_DELIVERY_PROVIDER` | `direct` | Adaptador de entrega. `direct` entrega cada webhook por HTTP com uma assinatura HMAC. |
| `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 novas tentativas por subscription 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. |


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