> ## 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 do Lerian SPI — runtime, conectividade SPI/DICT do BACEN, assinatura de mensagens e certificados, criptografia de PII, persistência, streaming e segurança.
O Lerian SPI é a integração de mensageria nativa da Lerian para o Pix, alcançando o sistema de pagamentos instantâneos do BACEN (SPI) e o diretório DICT sobre a RSFN. É um único deployable com três superfícies cooperantes — o core de liquidação SPI, o cliente DICT e o BR Code — então seu conjunto de variáveis é amplo. Todas as variáveis são definidas no momento do deploy e exigem uma reinicialização do serviço. Para os parâmetros que se comportam da mesma forma em todos os serviços Go da Lerian — postura de deployment, datastores, multi-tenancy, telemetria, streaming — consulte a [referência de configuração BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, **Obrigatória** marca uma variável que deve ser definida (globalmente, ou sob a condição indicada). `—` significa que não há padrão.
A maioria das variáveis voltadas ao BACEN é namespaced por superfície: `BACEN_SPI_*` para o transporte de liquidação SPI, `BACEN_DICT_*` para o cliente DICT, `BACEN_BRCODE_*` para a assinatura JOSE do BR Code, e `BACEN_ICOM_*` para o canal de long-poll de entrada.
## Runtime e servidor
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ----------- |
| `ENV_NAME` | Rótulo do ambiente de runtime. Production arma controles de segurança mais estritos. | `development` | Não |
| `LOG_LEVEL` | Verbosidade dos logs (`debug`, `info`, `warn`, `error`). | `info` | Não |
| `SERVER_ADDRESS` | Endereço de escuta HTTP principal (`host:port`). Liveness, readiness e systemplane se vinculam a essa porta. | `:8080` | Não |
| `HTTP_BODY_LIMIT_BYTES` | Tamanho máximo do corpo da requisição em bytes. | `1048576` | Não |
| `PUBLIC_BASE_URL` | URL base do serviço acessível externamente, usada para construir URLs de callback absolutas. | — | Não |
| `ACCESS_CONTROL_ALLOW_ORIGIN` | Origens CORS permitidas. | `http://localhost:3000` | Não |
| `ACCESS_CONTROL_ALLOW_METHODS` | Métodos CORS permitidos. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | Não |
| `ACCESS_CONTROL_ALLOW_HEADERS` | Headers de requisição CORS permitidos. | (conjunto padrão) | Não |
| `TRUSTED_PROXIES` | IPs/CIDRs de proxy, separados por vírgula, confiáveis para definir o IP real do cliente. | — | Não |
| `SERVER_TLS_CERT_FILE` | Caminho para o certificado TLS do servidor. Defina junto com o arquivo de chave. | — | Não |
| `SERVER_TLS_KEY_FILE` | Caminho para a chave privada TLS do servidor. Sensível. | — | Não |
| `SERVER_TLS_CLIENT_CA_FILE` | Arquivo CA para verificar certificados de cliente (TLS mútuo). | — | Não |
| `TLS_TERMINATED_UPSTREAM` | Defina `true` quando o TLS é terminado por um load balancer ou proxy reverso. | `false` | Não |
## Autenticação
O Lerian SPI autoriza rotas protegidas — incluindo a API de administração do systemplane — através do Access Manager.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------- | ------------- |
| `AUTH_ENABLED` | Exige autenticação via Access Manager em rotas protegidas. Habilite em produção. | `false` | Não |
| `PLUGIN_AUTH_ADDRESS` | Endereço do serviço Access Manager. | — | Se habilitado |
| `AUTH_TRUST_UPSTREAM_METADATA` | Confia nos metadados de identidade encaminhados por um proxy upstream. Mantenha `false` a menos que o proxy seja confiável. | `false` | Não |
## Callback do BACEN (entrada a partir do SPI)
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------------ | --------------------------------------------------------------------------------------------- | ------ | ----------- |
| `BACEN_CALLBACK_TRUSTED_PROXY_CIDRS` | CIDRs confiáveis como origem dos callbacks do BACEN. | — | Não |
| `BACEN_CALLBACK_MTLS_HEADER_SECRET` | Segredo compartilhado que comprova que o upstream terminou o TLS mútuo do callback. Sensível. | — | Não |
## Transporte de liquidação SPI (`BACEN_SPI_*`)
Conexão com o endpoint de liquidação SPI do BACEN sobre a RSFN, com um endpoint secundário opcional e o endpoint de arquivo (ARQ).
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------------------- | -------------------------------------------------------------------- | ----------------------- | ------------------- |
| `BACEN_SPI_ENDPOINT` | URL do endpoint SPI primário. | `http://localhost:9900` | Sim (SPI real) |
| `BACEN_SPI_SECONDARY_ENDPOINT` | URL do endpoint SPI secundário para failover. | — | Não |
| `BACEN_ARQ_ENDPOINT` | URL do endpoint ARQ (arquivo/batch). | — | Não |
| `BACEN_SPI_PARTICIPANT_ISPB` | O ISPB do participante para a superfície SPI. | — | Sim (SPI real) |
| `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS` | Allow-list de hosts que o cliente SPI pode alcançar (proteção SSRF). | — | Não |
| `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Allow-list para o endpoint secundário. | — | Não |
| `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS` | Allow-list para o endpoint ARQ. | — | Não |
| `BACEN_SPI_TIMEOUT_SEC` | Timeout de requisição (segundos). | `30` | Não |
| `BACEN_SPI_INITIATION_TIMEOUT_MS` | Timeout de iniciação de pagamento (milissegundos). | `150` | Não |
| `BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS` | Timeout de processamento de callback de entrada (milissegundos). | `250` | Não |
| `BACEN_SPI_RETRY_ATTEMPTS` | Tentativas de retry em falha de transporte. | `3` | Não |
| `BACEN_SPI_RETRY_INITIAL_BACKOFF_MS` | Backoff inicial de retry (milissegundos). | `500` | Não |
| `BACEN_SPI_RETRY_MAX_BACKOFF_MS` | Backoff máximo de retry (milissegundos). | `5000` | Não |
| `BACEN_SPI_OUTBOUND_QUOTA_ENABLED` | Habilita a quota de rate de saída do lado do cliente. | `false` | Não |
| `BACEN_SPI_OUTBOUND_QUOTA_LIMIT` | Quota de saída sustentada (requisições). | — | Se quota habilitada |
| `BACEN_SPI_OUTBOUND_QUOTA_BURST` | Tolerância de burst acima da quota. | — | Se quota habilitada |
| `BACEN_SPI_CATALOGUE_VERSION` | Versão do catálogo de mensagens SPI do BACEN. | `5.12.1` | Não |
| `BACEN_SPI_XSD_DIR` | Diretório dos schemas XSD do BACEN empacotados para o catálogo. | Caminho empacotado | Não |
| `BACEN_SPI_CATALOGUE_ROOT` | Raiz de override para o catálogo de mensagens. | — | Não |
| `BACEN_SPI_INTERNAL_CALLBACK_SECRET` | Segredo compartilhado para o caminho de callback interno. Sensível. | — | Não |
### TLS mútuo com o BACEN
Os arquivos `BACEN_TLS_*` dão suporte ao canal de TLS mútuo com o BACEN e são compartilhados pelos clientes SPI e DICT.
| Variável | Descrição | Padrão | Obrigatória |
| --------------------- | --------------------------------------------------------------------- | ------ | ----------- |
| `BACEN_TLS_CERT_FILE` | Certificado de cliente apresentado ao BACEN. | — | Sim (real) |
| `BACEN_TLS_KEY_FILE` | Chave privada do cliente. Sensível. | — | Sim (real) |
| `BACEN_TLS_CA_FILE` | Bundle de CA usado para verificar o certificado de servidor do BACEN. | — | Sim (real) |
## Assinatura de mensagens e certificados
As mensagens SPI são assinadas digitalmente. Escolha um backend de custódia com `BACEN_SPI_SIGNER_KIND`.
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ----------- |
| `BACEN_SPI_SIGNER_KIND` | Backend de custódia de assinatura: `file`, `pkcs11` ou `kmip`. Use um backend de hardware em produção. | `file` | Não |
| `BACEN_SPI_SIGNER_COMMON_NAME` | Common name esperado do certificado de assinatura. | — | Não |
| `BACEN_SPI_SIGNING_CERT_FILE` | Caminho para o certificado de assinatura. | — | Não |
| `BACEN_SPI_INBOUND_SIGNER_COMMON_NAME` | Common name esperado do signatário nas mensagens de entrada. | — | Não |
| `CERT_READINESS_MIN_DAYS` | Mínimo de dias até o vencimento antes de a verificação de readiness do certificado reportar estado degradado. | `14` | Não |
| `BACEN_SPI_PKCS11_MODULE_PATH` | Caminho da biblioteca do módulo PKCS#11. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_TOKEN_LABEL` | Label do token PKCS#11. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_PIN_FILE` | Caminho para um arquivo que contém o PIN do token. Sensível. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_KEY_LABEL` | Label da chave de assinatura no token. | — | Se `pkcs11` |
| `BACEN_SPI_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se `kmip` |
| `BACEN_SPI_KMIP_VHSM` | Identificador do HSM virtual. | — | Se `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER` | Usuário cripto do KMIP. | — | Se `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER_TOKEN` | Token do usuário cripto do KMIP. Sensível. | — | Se `kmip` |
| `BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada de assinatura. | — | Se `kmip` |
| `BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública de assinatura. | — | Se `kmip` |
| `BACEN_SPI_KMIP_DIGEST_INFO_PREFIX` | Prefixa o prefixo ASN.1 DigestInfo antes da chamada de assinatura KMIP. | `false` | Não |
### Validação de certificado (OCSP/CRL)
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------------------- | ------------------------------------------------------------------ | ----------- | ----------- |
| `BACEN_SPI_OCSP_MODE` | Modo de verificação de revogação de certificado (ex: `soft_fail`). | `soft_fail` | Não |
| `BACEN_SPI_OCSP_TIMEOUT_MS` | Timeout de requisição OCSP (milissegundos). | `3000` | Não |
| `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Limite no TTL da resposta OCSP em cache (segundos). | `3600` | Não |
| `BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC` | TTL do cache de CRL (segundos). | `3600` | Não |
### Resolvedor de payload
Controla como payloads SPI grandes são armazenados e referenciados.
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------------------------ | ----------------------------------------------------------- | ----------- | ----------- |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND` | Backend de armazenamento de payload (ex: `in_memory`). | `in_memory` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Máximo de bytes mantidos pelo resolvedor in-memory. | `134217728` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC` | TTL de retenção para payloads resolvidos (segundos). | `86400` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY` | Chave AES para criptografar payloads armazenados. Sensível. | — | Não |
## Canal de entrada (`BACEN_ICOM_*`)
Canal de long-poll para mensagens que o BACEN envia de volta ao participante.
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------------------- | ----------------------------------------------- | ------- | ----------- |
| `BACEN_ICOM_BASE_URL` | URL base do canal de entrada. | — | Não |
| `BACEN_ICOM_ISPB` | ISPB do participante para o canal de entrada. | — | Não |
| `BACEN_ICOM_CONSUMER_ENABLED` | Habilita o consumidor de entrada primário. | `false` | Não |
| `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED` | Habilita o consumidor de entrada secundário. | `false` | Não |
| `BACEN_ICOM_LONGPOLL_TIMEOUT_MS` | Timeout de espera do long-poll (milissegundos). | `90000` | Não |
## Cliente DICT (`BACEN_DICT_*`)
Cliente para o diretório de chaves Pix do BACEN (DICT), incluindo o endpoint antifraude (NP).
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------------- | -------------------------------------------------------------------------------- | ----------------------- | --------------- |
| `BACEN_DICT_ENDPOINT` | URL do endpoint DICT. | `http://localhost:9900` | Sim (DICT real) |
| `BACEN_DICT_PARTICIPANT_ISPB` | ISPB do participante para a superfície DICT. | — | Sim (DICT real) |
| `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS` | Allow-list de hosts que o cliente DICT pode alcançar. | — | Não |
| `BACEN_DICT_TIMEOUT_SEC` | Timeout de requisição DICT (segundos). | `10` | Não |
| `BACEN_DICT_NP_ENDPOINT` | URL do endpoint antifraude (NP). | — | Não |
| `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Allow-list para o endpoint NP. | — | Não |
| `BACEN_DICT_SIGNER_KIND` | Backend de custódia de assinatura DICT: `file`, `pkcs11` ou `kmip`. | `file` | Não |
| `BACEN_DICT_SIGNING_CERT_FILE` | Caminho para o certificado de assinatura DICT. | — | Não |
| `BACEN_DICT_SIGNING_KEY_FILE` | Caminho para a chave privada de assinatura DICT (backend de arquivo). Sensível. | — | Se `file` |
| `BACEN_DICT_VERIFY_CERT_FILE` | Certificado usado para verificar respostas DICT. | — | Não |
| `BACEN_DICT_PKCS11_MODULE_PATH` | Caminho do módulo PKCS#11. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_TOKEN_LABEL` | Label do token PKCS#11. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_PIN_FILE` | Caminho para o arquivo do PIN do token. Sensível. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_KEY_LABEL` | Label da chave de assinatura no token. | — | Se `pkcs11` |
| `BACEN_DICT_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se `kmip` |
| `BACEN_DICT_KMIP_VHSM` | Identificador do HSM virtual. | — | Se `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER` | Usuário cripto do KMIP. | — | Se `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER_TOKEN` | Token do usuário cripto do KMIP. Sensível. | — | Se `kmip` |
| `BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada de assinatura. | — | Se `kmip` |
| `BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública de assinatura. | — | Se `kmip` |
| `BACEN_DICT_KMIP_DIGEST_INFO_PREFIX` | Prefixa o prefixo ASN.1 DigestInfo antes da chamada de assinatura KMIP. | `false` | Não |
| `BACEN_DICT_INTENT_ENCRYPTION_KEY` | Chave AES para criptografar intents de reivindicação DICT armazenados. Sensível. | — | Não |
## Assinatura JOSE do BR Code (`BACEN_BRCODE_JOSE_*`)
Assina payloads dinâmicos de BR Code (JWS).
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------------------------- | ------------------------------------------------------------------------------- | ------- | ----------- |
| `BACEN_BRCODE_JOSE_SIGNER_KIND` | Backend de custódia de assinatura JOSE: `file`, `pkcs11` ou `kmip`. | — | Não |
| `BACEN_BRCODE_JOSE_SIGNING_CERT_FILE` | Caminho para o certificado de assinatura JOSE. | — | Não |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE` | Caminho para a chave privada de assinatura JOSE (backend de arquivo). Sensível. | — | Se `file` |
| `BACEN_BRCODE_JOSE_KID` | Valor do header identificador de chave JWS (`kid`). | — | Não |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH` | Caminho do módulo PKCS#11. | — | Se `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL` | Label do token PKCS#11. | — | Se `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE` | Caminho para o arquivo do PIN do token. Sensível. | — | Se `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL` | Label da chave de assinatura no token. | — | Se `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_VHSM` | Identificador do HSM virtual. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER` | Usuário cripto do KMIP. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN` | Token do usuário cripto do KMIP. Sensível. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada de assinatura. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública de assinatura. | — | Se `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX` | Prefixa o prefixo ASN.1 DigestInfo antes da chamada de assinatura KMIP. | `false` | Não |
## Criptografia e hashing de PII
Cada variável abaixo é material sensível de chave ou pepper para criptografar e fazer blind-indexing de dados pessoais em repouso. Nunca faça commit nem registre em log um valor; injete-o no momento do deploy através do seu gerenciador de segredos. Rotacionar um pepper ou uma chave exige um re-index/re-encryption planejado.
| Variável | Descrição | Padrão | Obrigatória |
| ----------------------------------- | ------------------------------------------------------------- | ------ | ----------- |
| `DICT_KEY_PII_ENCRYPTION_KEY` | Chave AES para PII do titular de chave DICT. Sensível. | — | Não |
| `DICT_KEY_BLIND_INDEX_PEPPER` | Pepper para blind-indexing de PII de chave DICT. Sensível. | — | Não |
| `DICT_AUDIT_HASH_PEPPER` | Pepper para hashing de registros de auditoria DICT. Sensível. | — | Não |
| `AUDIT_HASH_PEPPER` | Pepper de hash de auditoria legado. Sensível. | — | Não |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY` | Chave AES para PII de parte responsável. Sensível. | — | Não |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | Chave AES para PII de operação. Sensível. | — | Não |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper para blind-indexing de PII de operação. Sensível. | — | Não |
| `BRCODE_PII_ENCRYPTION_KEY` | Chave AES para PII de BR Code. Sensível. | — | Não |
| `BRCODE_PII_BLIND_INDEX_PEPPER` | Pepper para blind-indexing de PII de BR Code. Sensível. | — | Não |
## PostgreSQL
| Variável | Descrição | Padrão | Obrigatória |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- | ----------- | ----------- |
| `POSTGRES_HOST` | Host primário do PostgreSQL. | `localhost` | Sim |
| `POSTGRES_PORT` | Porta primária do PostgreSQL. | `5432` | Não |
| `POSTGRES_USER` | Usuário do banco de dados. | — | Sim |
| `POSTGRES_PASSWORD` | Senha do banco de dados. Sensível. | — | Em produção |
| `POSTGRES_DB` | Nome do banco de dados. | — | Sim |
| `POSTGRES_SSLMODE` | Modo TLS do libpq. Use `require` ou mais forte em produção. | `disable` | Não |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexões ociosas. | `5` | Não |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Tempo máximo de vida da conexão (minutos). | `30` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Tempo máximo ocioso da conexão (minutos). | `5` | Não |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Timeout de conexão (segundos). | `10` | Não |
| `POSTGRES_REPLICA_HOST` | Host de réplica de leitura opcional. Os demais campos de réplica usam o primário como fallback. | — | Não |
| `POSTGRES_REPLICA_PORT` | Porta da réplica. | — | Não |
| `POSTGRES_REPLICA_USER` | Usuário da réplica. | — | Não |
| `POSTGRES_REPLICA_PASSWORD` | Senha da réplica. Sensível. | — | Não |
| `POSTGRES_REPLICA_DB` | Nome do banco da réplica. | — | Não |
| `POSTGRES_REPLICA_SSLMODE` | Modo TLS da réplica. | — | Não |
## Redis
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------ | --------------------------------------------- | ---------------- | ----------- |
| `REDIS_HOST` | Host e porta do Redis. | `localhost:6379` | Não |
| `REDIS_MASTER_NAME` | Nome do master Sentinel (se usando Sentinel). | — | Não |
| `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Não |
| `REDIS_DB` | Número do banco de dados Redis. | `0` | Não |
| `REDIS_PROTOCOL` | Versão do protocolo Redis (2 ou 3). | `3` | Não |
| `REDIS_TLS` | Habilita TLS para o Redis. | `false` | Não |
| `REDIS_CA_CERT` | Certificado CA para o TLS do Redis. | — | Não |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões. | `10` | Não |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexões ociosas. | `2` | Não |
| `REDIS_READ_TIMEOUT_MS` | Timeout de leitura (milissegundos). | `3000` | Não |
| `REDIS_WRITE_TIMEOUT_MS` | Timeout de escrita (milissegundos). | `3000` | Não |
| `REDIS_DIAL_TIMEOUT_MS` | Timeout de conexão (milissegundos). | `5000` | Não |
## Outbox e streaming
O Lerian SPI publica eventos através de um outbox transacional e de um produtor lib-streaming, e consome eventos de liquidação para o BR Code. As variáveis de streaming (`STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_CLOUDEVENTS_SOURCE`, `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS`, `STREAMING_EVENT_POLICIES`) seguem o backbone compartilhado — consulte [Streaming e outbox](/pt/reference/byoc-configuration#streaming-e-outbox). `STREAMING_BROKERS` é obrigatória sempre que `STREAMING_ENABLED=true`.
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------------- | ----------------------------------------------------------------------------- | -------- | ----------- |
| `OUTBOX_ENABLED` | Habilita o dispatcher de outbox transacional. | `true` | Não |
| `OUTBOX_DISPATCH_INTERVAL_MS` | Intervalo entre ciclos de dispatch (milissegundos). | `2000` | Não |
| `OUTBOX_BATCH_SIZE` | Linhas drenadas por ciclo de dispatch. | `50` | Não |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Tentativas de dispatch antes de um evento ser estacionado. | `10` | Não |
| `OUTBOX_PROCESSING_TIMEOUT_MS` | Timeout de processamento por batch (milissegundos). | `600000` | Não |
| `OUTBOX_RETRY_WINDOW_MS` | Janela de retry antes de uma linha travada ser recuperada (milissegundos). | `300000` | Não |
| `BRCODE_SETTLEMENT_CONSUMER_TOPIC` | Tópico que o consumidor de liquidação do BR Code lê. Definido por deployment. | — | Não |
| `BRCODE_SETTLEMENT_CONSUMER_GROUP` | Consumer group para a liquidação do BR Code. | — | Não |
| `BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID` | Client ID apresentado ao broker pelo consumidor de liquidação. | — | Não |
## Agendadores
Jobs em segundo plano, cada um controlado de forma independente. Todos desligados por padrão.
| Variável | Descrição | Padrão | Obrigatória |
| --------------------------------------------------- | ------------------------------------------------------ | ------- | ----------- |
| `SCHEDULER_ENABLED` | Chave mestra para o subsistema de agendamento. | `false` | Não |
| `SCHEDULER_MED_DEADLINE_ENABLED` | Executa o job de deadline do MED (devolução especial). | `false` | Não |
| `SCHEDULER_QUOTA_RESET_ENABLED` | Executa o job de reset da quota de saída. | `false` | Não |
| `SCHEDULER_CLAIM_DEADLINE_ENABLED` | Executa o job de deadline de reivindicação DICT. | `false` | Não |
| `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Executa a reconciliação DICT incremental. | `false` | Não |
| `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED` | Executa a reconciliação DICT completa. | `false` | Não |
| `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED` | Executa o job de retenção de auditoria DICT. | `false` | Não |
| `SCHEDULER_INBOUND_DISCOVERY_ENABLED` | Executa o job de descoberta de mensagens de entrada. | `false` | Não |
| `SCHEDULER_APPROVAL_EXPIRY_ENABLED` | Executa a varredura de expiração de aprovações. | `false` | Não |
| `SCHEDULER_PORTABILITY_DEADLINE_ENABLED` | Executa o job de deadline de portabilidade. | `false` | Não |
## Rate limiting, idempotência e conectividade
| Variável | Descrição | Padrão | Obrigatória |
| ------------------------------ | ----------------------------------------------------------------------------------- | ------- | ----------- |
| `RATE_LIMIT_ENABLED` | Habilita o rate limiting de requisições. | `true` | Não |
| `RATE_LIMIT_MAX` | Máximo de requisições por janela. | `100` | Não |
| `RATE_LIMIT_EXPIRY_SEC` | Janela de rate-limit (segundos). | `60` | Não |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Por quanto tempo (segundos) uma chave de idempotência é retida. | `86400` | Não |
| `INFRA_CONNECT_TIMEOUT_SEC` | Timeout de conexão para dependências de infraestrutura na inicialização (segundos). | `30` | Não |
## Systemplane e configuração de runtime
| Variável | Descrição | Padrão | Obrigatória |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- |
| `SYSTEMPLANE_ENABLED` | Habilita a API de administração de configuração de runtime do systemplane, montada em `/v1/system` na porta principal. Quando `false`, o serviço roda em modo env-only sem plano de administração. **O SPI o ativa por padrão** — ao contrário da maioria dos serviços da Lerian, onde o systemplane fica desativado por padrão. | `true` | Não |
Consulte [Systemplane](/pt/reference/systemplane/overview) para a API, os namespaces e as permissões necessárias.
## Observabilidade
| Variável | Descrição | Padrão | Obrigatória |
| -------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | ------------------------ |
| `ENABLE_TELEMETRY` | Habilita tracing e métricas OpenTelemetry. | `false` | Não |
| `TELEMETRY_REQUIRED` | Falha na inicialização se a telemetria não puder inicializar. | `false` | Não |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. | `localhost:4317` | Se telemetria habilitada |
| `OTEL_RESOURCE_SERVICE_NAME` | Nome do serviço anexado à telemetria exportada. | Padrão do serviço | Não |
| `OTEL_RESOURCE_SERVICE_VERSION` | Rótulo de versão do serviço. | Por release | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo do ambiente de deployment. | `development` | Não |
| `OTEL_LIBRARY_NAME` | Nome da biblioteca de instrumentação. | Padrão do serviço | Não |
| `METRICS_PROMETHEUS_ENABLED` | Expõe um endpoint dedicado de scrape do Prometheus. | `false` | Não |
| `METRICS_PROMETHEUS_ADDRESS` | Endereço de escuta do endpoint Prometheus. Vincula-se ao loopback por padrão. | `127.0.0.1:9090` | Não |
## Documentação
| Variável | Descrição | Padrão | Obrigatória |
| ----------------- | ---------------------------------------------------------------------------- | ------- | ----------- |
| `SWAGGER_ENABLED` | Serve a spec OpenAPI e a UI de docs da API. Forçado a desligado em produção. | `false` | Não |
## Saúde e prontidão
O Lerian SPI expõe `GET /health` (liveness), `GET /readyz` (readiness) e `GET /version` na porta HTTP principal; `/metrics` roda em seu próprio listener quando habilitado. Consulte [Saúde e prontidão](/pt/reference/health-and-readiness) para o contrato das probes.