> ## 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 de deploy do Lerian SPI: conectividade com o SPI/DICT do BACEN, certificados de assinatura ISO 20022, criptografia de PII, persistência e streaming.
O Lerian SPI é a integração de mensageria nativa da Lerian para o Pix. Ele alcança o sistema de pagamento instantâneo do BACEN (SPI) e o diretório de chaves DICT pela RSFN. Ele distribui quatro binários de runtime (`spi`, `dict`, `brcode` e `core`), então seu conjunto de variáveis é amplo.
O serviço lê cada variável na inicialização. Quando o systemplane está ativo (o padrão), ele pode sobrescrever um subconjunto delas em runtime sem reiniciar. As demais variáveis exigem um restart para mudar. Para os parâmetros que se comportam da mesma forma em todo serviço Go da Lerian (postura de deployment, datastores, multi-tenancy, telemetria, streaming), consulte [Fundamentos de configuração do BYOC](/pt/reference/byoc-configuration).
Nas tabelas abaixo, **Obrigatório** marca uma variável que você deve definir, de forma global ou sob a condição indicada. `—` significa que não há padrão.
A maioria das variáveis voltadas ao BACEN carrega um prefixo de superfície: `BACEN_SPI_*` para o transporte de liquidação do SPI, `BACEN_DICT_*` para o cliente DICT, `BACEN_BRCODE_JOSE_*` 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ório |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------- |
| `ENV_NAME` | Rótulo do ambiente de runtime. Quando não definido, resolve para `development`; um `none` explícito é inválido. A produção ativa controles de segurança mais rígidos. | `development` | Não |
| `LOG_LEVEL` | Verbosidade de log (`debug`, `info`, `warn`, `error`). | `info` | Não |
| `SERVER_ADDRESS` | Endereço HTTP principal de escuta (`host:port` ou `:port`). Liveness, readiness e systemplane se ligam 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 montar URLs de callback absolutas e links de payload do BR Code. | — | Em produção ou se o BR Code JOSE estiver habilitado |
| `ACCESS_CONTROL_ALLOW_ORIGIN` | Origens de CORS permitidas. | `http://localhost:3000` | Não |
| `ACCESS_CONTROL_ALLOW_METHODS` | Métodos de CORS permitidos. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | Não |
| `ACCESS_CONTROL_ALLOW_HEADERS` | Cabeçalhos 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 do certificado TLS do servidor. Defina junto com o arquivo de chave. | — | Não |
| `SERVER_TLS_KEY_FILE` | Caminho da chave privada TLS do servidor. Sensível. | — | Não |
| `SERVER_TLS_CLIENT_CA_FILE` | Arquivo de CA para verificar certificados de cliente (TLS mútuo). | — | Não |
| `TLS_TERMINATED_UPSTREAM` | Defina como `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 administrativa do systemplane, pelo Access Manager.
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------- |
| `AUTH_ENABLED` | Exige autenticação do Access Manager nas rotas protegidas. | `false` | Em produçã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. Deixe como `false`, a menos que o proxy seja confiável. | `false` | Não |
## Callback do BACEN (entrada vinda do SPI)
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------------------ | --------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------ |
| `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. | — | Se o consumidor ICOM primário estiver habilitado |
## Transporte de liquidação do SPI (`BACEN_SPI_*`)
Conexão com o endpoint de liquidação do SPI do BACEN pela RSFN, com um endpoint secundário opcional e o endpoint de arquivo (ARQ).
| Variável | Descrição | Padrão | Obrigatório |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------- |
| `BACEN_SPI_ENDPOINT` | URL do endpoint primário do SPI. | `http://localhost:9900` | Sim (SPI em operação real) |
| `BACEN_SPI_SECONDARY_ENDPOINT` | URL do endpoint secundário do SPI para failover. | — | Se o consumidor ICOM secundário estiver habilitado |
| `BACEN_ARQ_ENDPOINT` | URL do endpoint ARQ (arquivo/lote). | — | Não |
| `BACEN_SPI_PARTICIPANT_ISPB` | O ISPB do participante para a superfície do SPI. | — | Sim (SPI em operação real) |
| `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos que o cliente do SPI pode acessar (proteção contra SSRF). | — | Não |
| `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para o endpoint secundário. | — | Não |
| `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para o endpoint ARQ. | — | Não |
| `BACEN_SPI_TIMEOUT_SEC` | Timeout de requisição, em segundos. | `30` | Não |
| `BACEN_SPI_INITIATION_TIMEOUT_MS` | Timeout de iniciação de pagamento, em milissegundos. | `150` | Não |
| `BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS` | Timeout de processamento de callback de entrada, em milissegundos. | `250` | Não |
| `BACEN_SPI_RETRY_ATTEMPTS` | Tentativas de nova tentativa em falha de transporte. | `3` | Não |
| `BACEN_SPI_RETRY_INITIAL_BACKOFF_MS` | Backoff inicial de nova tentativa, em milissegundos. | `500` | Não |
| `BACEN_SPI_RETRY_MAX_BACKOFF_MS` | Backoff máximo de nova tentativa, em milissegundos. | `5000` | Não |
| `BACEN_SPI_OUTBOUND_QUOTA_ENABLED` | Habilita a cota de saída no lado do cliente. | `false` | Não |
| `BACEN_SPI_OUTBOUND_QUOTA_LIMIT` | Cota sustentada de saída, em requisições. | — | Se a cota estiver habilitada |
| `BACEN_SPI_OUTBOUND_QUOTA_BURST` | Margem de burst acima da cota. | — | Se a cota estiver habilitada |
| `BACEN_SPI_CATALOGUE_VERSION` | Versão do catálogo de mensagens do SPI do BACEN. | `5.12.1` | Não |
| `BACEN_SPI_XSD_DIR` | Diretório dos esquemas XSD do BACEN empacotados para o catálogo. | Caminho empacotado | Não |
| `BACEN_SPI_CATALOGUE_ROOT` | Substitui a raiz do catálogo de mensagens. | — | Não |
| `BACEN_SPI_INTERNAL_CALLBACK_SECRET` | Segredo compartilhado para o caminho interno de callback. Pelo menos 32 caracteres quando definido. Sensível. | — | Em produção ou se o consumidor ICOM primário estiver habilitado |
### TLS mútuo com o BACEN
Os arquivos `BACEN_TLS_*` sustentam o canal de TLS mútuo com o BACEN. Os clientes do SPI e do DICT os compartilham.
| Variável | Descrição | Padrão | Obrigatório |
| --------------------- | --------------------------------------------------------------------- | ------ | ------------------- |
| `BACEN_TLS_CERT_FILE` | Certificado de cliente apresentado ao BACEN. | — | Sim (operação real) |
| `BACEN_TLS_KEY_FILE` | Chave privada do cliente. Sensível. | — | Sim (operação real) |
| `BACEN_TLS_CA_FILE` | Pacote de CA usado para verificar o certificado de servidor do BACEN. | — | Sim (operação real) |
## Assinatura de mensagens e certificados
O Lerian SPI assina digitalmente suas mensagens de saída. Escolha um backend de custódia com `BACEN_SPI_SIGNER_KIND`.
| Variável | Descrição | Padrão | Obrigatório |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------- |
| `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` | Nome comum esperado do certificado de assinatura. | — | Não |
| `BACEN_SPI_SIGNING_CERT_FILE` | Caminho do certificado ligado à chave de assinatura. Obrigatório para `pkcs11` ou `kmip`; para `file`, volta a usar `BACEN_TLS_CERT_FILE` quando não definido. | `BACEN_TLS_CERT_FILE` (file) | Se `pkcs11` ou `kmip` |
| `BACEN_SPI_INBOUND_SIGNER_COMMON_NAME` | Nome comum esperado do assinante 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 degradação. | `14` | Não |
| `BACEN_SPI_PKCS11_MODULE_PATH` | Caminho da biblioteca do módulo PKCS#11. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_TOKEN_LABEL` | Rótulo do token PKCS#11. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_PIN_FILE` | Caminho de um arquivo que guarda o PIN do token. Sensível. | — | Se `pkcs11` |
| `BACEN_SPI_PKCS11_KEY_LABEL` | Rótulo 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 criptográfico do KMIP. | — | Se `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER_TOKEN` | Token do usuário criptográfico 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` | Antepõe o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP. | `false` | Não |
### Validação de certificado (OCSP/CRL)
| Variável | Descrição | Padrão | Obrigatório |
| ---------------------------------- | --------------------------------------------------------------------------- | ----------- | ----------- |
| `BACEN_SPI_OCSP_MODE` | Modo de verificação de revogação de certificado (por exemplo, `soft_fail`). | `soft_fail` | Não |
| `BACEN_SPI_OCSP_TIMEOUT_MS` | Timeout de requisição OCSP, em milissegundos. | `3000` | Não |
| `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Limite do TTL de cache da resposta OCSP, em segundos. | `3600` | Não |
| `BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC` | TTL de cache da CRL, em segundos. | `3600` | Não |
### Resolvedor de payload
Estas variáveis controlam como o serviço armazena e referencia payloads grandes do SPI.
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------ |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND` | Backend de armazenamento de payload: `in_memory` ou `postgres`. Ambientes semelhantes a produção recusam `in_memory` — use um backend durável. | `in_memory` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Máximo de bytes mantidos pelo resolvedor em memória. | `134217728` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC` | TTL de retenção para payloads resolvidos, em segundos. | `86400` | Não |
| `BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY` | Chave AES-256 para criptografar payloads armazenados. Sensível. | — | Se o tipo for `postgres` |
## 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ório |
| --------------------------------------- | ------------------------------------------------- | ------- | ------------------------------------------------ |
| `BACEN_ICOM_BASE_URL` | URL base do canal de entrada. | — | Se o consumidor ICOM primário estiver habilitado |
| `BACEN_ICOM_ISPB` | ISPB do participante para o canal de entrada. | — | Se o consumidor ICOM primário estiver habilitado |
| `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, em milissegundos. | `90000` | Não |
Com `BACEN_ICOM_CONSUMER_ENABLED=true`, a inicialização também exige um backend de persistência configurado, `BACEN_SPI_INTERNAL_CALLBACK_SECRET` e `BACEN_CALLBACK_MTLS_HEADER_SECRET`. Com `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED=true`, ela exige adicionalmente `BACEN_SPI_SECONDARY_ENDPOINT`.
## 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ório |
| -------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------- |
| `BACEN_DICT_ENDPOINT` | URL do endpoint do DICT. | `http://localhost:9900` | Sim (DICT em operação real) |
| `BACEN_DICT_PARTICIPANT_ISPB` | ISPB do participante para a superfície do DICT. | — | Sim (DICT em operação real) |
| `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos que o cliente do DICT pode acessar. | — | Não |
| `BACEN_DICT_TIMEOUT_SEC` | Timeout de requisição do DICT, em segundos. | `10` | Não |
| `BACEN_DICT_NP_ENDPOINT` | URL do endpoint antifraude (NP). | — | Não |
| `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para o endpoint NP. | — | Não |
| `BACEN_DICT_SIGNER_KIND` | Backend de custódia de assinatura do DICT: `file`, `pkcs11` ou `kmip`. | `file` | Não |
| `BACEN_DICT_SIGNING_CERT_FILE` | Caminho do certificado de assinatura do DICT. | — | Para o caminho de custódia do DICT selecionado |
| `BACEN_DICT_SIGNING_KEY_FILE` | Caminho da chave privada de assinatura do DICT (backend file). Sensível. | — | Se `file` |
| `BACEN_DICT_VERIFY_CERT_FILE` | Certificado usado para verificar as respostas do DICT. | — | Não |
| `BACEN_DICT_PKCS11_MODULE_PATH` | Caminho do módulo PKCS#11. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_TOKEN_LABEL` | Rótulo do token PKCS#11. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_PIN_FILE` | Caminho do arquivo de PIN do token. Sensível. | — | Se `pkcs11` |
| `BACEN_DICT_PKCS11_KEY_LABEL` | Rótulo 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 criptográfico do KMIP. | — | Se `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER_TOKEN` | Token do usuário criptográfico 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` | Antepõe o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP. | `false` | Não |
| `BACEN_DICT_INTENT_ENCRYPTION_KEY` | Chave AES-256 para criptografar as intenções de reivindicação do DICT armazenadas. Sensível. | — | Em produção |
## Assinatura JOSE do BR Code (`BACEN_BRCODE_JOSE_*`)
Assina payloads dinâmicos do BR Code (JWS).
| Variável | Descrição | Padrão | Obrigatório |
| --------------------------------------------- | -------------------------------------------------------------------------- | ------- | ------------------------------------------------- |
| `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 do certificado de assinatura JOSE. | — | Se o BR Code JOSE estiver habilitado |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE` | Caminho da chave privada de assinatura JOSE (backend file). Sensível. | — | Se o BR Code JOSE estiver habilitado com `file` |
| `BACEN_BRCODE_JOSE_KID` | Valor do cabeçalho identificador de chave JWS (`kid`). | — | Se o BR Code JOSE estiver habilitado |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH` | Caminho do módulo PKCS#11. | — | Se o BR Code JOSE estiver habilitado com `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL` | Rótulo do token PKCS#11. | — | Se o BR Code JOSE estiver habilitado com `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE` | Caminho do arquivo de PIN do token. Sensível. | — | Se o BR Code JOSE estiver habilitado com `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL` | Rótulo da chave de assinatura no token. | — | Se o BR Code JOSE estiver habilitado com `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_VHSM` | Identificador do HSM virtual. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER` | Usuário criptográfico do KMIP. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN` | Token do usuário criptográfico do KMIP. Sensível. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada de assinatura. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública de assinatura. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX` | Antepõe o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP. | `false` | Não |
## Criptografia e hashing de PII
Toda variável abaixo guarda material sensível de chave ou pepper. Ela protege dados pessoais em repouso por criptografia e indexação cega. Nunca faça commit nem registre em log um valor. Injete-o no momento do deploy pelo seu gerenciador de segredos. Uma rotação de pepper ou chave exige uma reindexação ou recriptografia planejada.
| Variável | Descrição | Padrão | Obrigatório |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------- |
| `DICT_KEY_PII_ENCRYPTION_KEY` | Chave AES para a PII do titular da chave DICT. Sensível. | — | Runtime protegido do DICT |
| `DICT_KEY_BLIND_INDEX_PEPPER` | Pepper para a indexação cega da PII da chave DICT. Sensível. | — | Runtime protegido do DICT |
| `DICT_AUDIT_HASH_PEPPER` | Pepper para o hashing dos registros de auditoria do DICT. Sensível. | — | Runtime protegido |
| `AUDIT_HASH_PEPPER` | Pepper legado de hash de auditoria. Sensível. | — | Runtime protegido |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY` | Chave AES para a PII da parte responsável. Sensível. | — | Runtime protegido do SPI |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | Chave AES-256 para a PII de operação. Sensível. O serviço SPI recusa iniciar se ela estiver ausente ou malformada. | — | Sim — serviço SPI em todo ambiente |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper para a indexação cega da PII de operação. Sensível. Deve conter pelo menos 32 caracteres; o serviço SPI recusa iniciar se ela estiver ausente ou for mais curta. | — | Sim — serviço SPI em todo ambiente |
| `BRCODE_PII_ENCRYPTION_KEY` | Chave AES para a PII do BR Code. Sensível. | — | Runtime protegido do BR Code |
| `BRCODE_PII_BLIND_INDEX_PEPPER` | Pepper para a indexação cega da PII do BR Code. Sensível. | — | Runtime protegido do BR Code |
## PostgreSQL
| Variável | Descrição | Padrão | Obrigatório |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------- |
| `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. | `brspi` | Não |
| `POSTGRES_PASSWORD` | Senha do banco de dados. Sensível. Use um segredo explícito em produção. | Senha de desenvolvimento embutida no código | Não |
| `POSTGRES_DB` | Nome do banco de dados. | `brspi` | Não |
| `POSTGRES_SSLMODE` | Modo de TLS do libpq. Para conexões remotas de produção, use `verify-full` com uma CA confiável; `require` criptografa o canal, mas não verifica a identidade do servidor. | `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 de vida máximo da conexão, em minutos. | `30` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Tempo máximo de ociosidade da conexão, em minutos. | `5` | Não |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Timeout de conexão, em segundos. | `10` | Não |
| `POSTGRES_REPLICA_HOST` | Host opcional de réplica de leitura. Os demais campos de réplica voltam a usar o primário. | — | 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 de dados da réplica. | — | Não |
| `POSTGRES_REPLICA_SSLMODE` | Modo de TLS da réplica. | — | Não |
## Redis
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------ | -------------------------------------------------------- | ---------------- | ----------- |
| `REDIS_HOST` | Host e porta do Redis. | `localhost:6379` | Não |
| `REDIS_MASTER_NAME` | Nome do master do Sentinel (se estiver 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 o 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, em milissegundos. | `3000` | Não |
| `REDIS_WRITE_TIMEOUT_MS` | Timeout de escrita, em milissegundos. | `3000` | Não |
| `REDIS_DIAL_TIMEOUT_MS` | Timeout de conexão, em milissegundos. | `5000` | Não |
Outbox e streaming
O Lerian SPI publica eventos por um outbox transacional e um produtor lib-streaming, e consome eventos de liquidação para o BR Code. O consumidor de liquidação do BR Code roda incondicionalmente. O streaming não tem chave de habilitação: `STREAMING_BROKERS` é obrigatória na inicialização, inclusive quando `OUTBOX_ENABLED=false`. Configure as opções compartilhadas `STREAMING_CLOUDEVENTS_SOURCE`, `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS` e `STREAMING_EVENT_POLICIES` conforme descrito em [Streaming e outbox](/pt/reference/byoc-configuration#streaming-and-outbox).
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- |
| `OUTBOX_ENABLED` | Habilita o dispatcher do outbox transacional. | `true` | Não |
| `OUTBOX_DISPATCH_INTERVAL_MS` | Intervalo entre ciclos de dispatch, em milissegundos. | `2000` | Não |
| `OUTBOX_BATCH_SIZE` | Linhas processadas 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 lote, em milissegundos. | `600000` | Não |
| `OUTBOX_RETRY_WINDOW_MS` | Janela de nova tentativa antes de uma linha travada ser recuperada, em milissegundos. | `300000` | Não |
| `SPI_PARTICIPANT_CONSUMER_ENABLED` | Habilita o consumidor de requisições de participante do Core para o SPI. Ele assina o stream de aplicação do produtor Core; o tópico é derivado e não é configurável. Quando habilitado, exige `STREAMING_BROKERS`, transporte com o BACEN e persistência. | `false` | Não |
| `SPI_PARTICIPANT_CONSUMER_GROUP` | Grupo de consumidores durável para requisições de participante. | Padrão interno do serviço | Não |
| `SPI_PARTICIPANT_CONSUMER_CLIENT_ID` | ID de cliente apresentado ao broker pelo consumidor de requisições de participante. Volta a usar o ID de cliente compartilhado de streaming. | ID de cliente compartilhado | Não |
## Agendadores
Tarefas em segundo plano, cada uma controlada de forma independente. As tarefas controladas pelo agendador abaixo vêm desabilitadas por padrão. Os workers de descoberta e inventário do DICT têm seus próprios controles na próxima seção.
| Variável | Descrição | Padrão | Obrigatório |
| --------------------------------------------------- | ---------------------------------------------------- | ------- | ----------- |
| `SCHEDULER_ENABLED` | Chave mestra do subsistema de agendador. | `false` | Não |
| `SCHEDULER_MED_DEADLINE_ENABLED` | Roda a tarefa de prazo do MED (devolução especial). | `false` | Não |
| `SCHEDULER_QUOTA_RESET_ENABLED` | Roda a tarefa de reset da cota de saída. | `false` | Não |
| `SCHEDULER_CLAIM_DEADLINE_ENABLED` | Roda a tarefa de prazo de reivindicação do DICT. | `false` | Não |
| `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Roda a conciliação incremental do DICT. | `false` | Não |
| `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED` | Roda a conciliação completa do DICT. | `false` | Não |
| `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED` | Roda a tarefa de retenção de auditoria do DICT. | `false` | Não |
| `SCHEDULER_INBOUND_DISCOVERY_ENABLED` | Roda a tarefa de descoberta de mensagens de entrada. | `false` | Não |
| `SCHEDULER_APPROVAL_EXPIRY_ENABLED` | Roda a varredura de expiração de aprovação. | `false` | Não |
| `SCHEDULER_PORTABILITY_DEADLINE_ENABLED` | Roda a tarefa de prazo de portabilidade. | `false` | Não |
## Descoberta e inventário do DICT
A descoberta de reivindicações de entrada roda apenas quando `SCHEDULER_ENABLED` e `SCHEDULER_INBOUND_DISCOVERY_ENABLED` estão como `true`. Os demais workers do DICT abaixo rodam independentemente de `SCHEDULER_ENABLED`, cada um com sua própria chave explícita de habilitação.
| Variável | Descrição | Padrão | Obrigatório |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- |
| `SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES` | Limite de obsolescência de readiness para os feeds de descoberta de reivindicações de entrada. Deve ser maior que zero. | `30` | Não |
| `DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS` | Limite de intervalo após o qual o feed de eventos de recuperação de fundos registra um marcador de bloqueio. Deve ser maior que zero. | `168` | Não |
| `DICT_INFRACTION_DISCOVERY_ENABLED` | Habilita a varredura de descoberta de infrações do DICT. | `true` | Não |
| `DICT_INFRACTION_DISCOVERY_MAX_STALENESS_MINUTES` | Limite de obsolescência de readiness para a descoberta de infrações. Deve ser maior que zero. | `15` | Não |
| `DICT_REFUND_DISCOVERY_ENABLED` | Habilita as varreduras de descoberta de devolução do DICT. | `true` | Não |
| `DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES` | Limite de obsolescência de readiness para a descoberta de devolução. Deve ser maior que zero. | `15` | Não |
| `DICT_PERSON_WATCHLIST_ENABLED` | Habilita o polling de documentos na watchlist de pessoas do DICT. | `true` | Não |
| `DICT_PERSON_WATCHLIST_CADENCE_MINUTES` | Idade mínima antes de um documento monitorado ser observado de novo. Deve ser maior que zero. | `60` | Não |
| `DICT_PERSON_WATCHLIST_BATCH_LIMIT` | Máximo de documentos monitorados observados em um ciclo de polling. Deve ser maior que zero. | `100` | Não |
| `DICT_PERSON_WATCHLIST_MAX_DOCUMENTS_PER_PARTICIPANT` | Máximo de documentos monitorados ativos por participante. Deve ser maior que zero. | `500` | Não |
| `DICT_PERSON_WATCHLIST_MAX_OBSERVATION_AGE_MINUTES` | Limite de readiness para a observação mais antiga de documento monitorado. Deve ser maior que zero. | `360` | Não |
| `DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES` | Observações falhas consecutivas antes de um documento monitorado ser colocado em quarentena. Deve ser maior que zero. | `6` | Não |
| `DICT_FRAUD_MARKER_INVENTORY_ENABLED` | Habilita a varredura de inventário de marcadores de fraude do DICT. | `true` | Não |
| `DICT_FRAUD_MARKER_INVENTORY_SWEEP_MINUTES` | Intervalo entre varreduras de inventário de marcadores de fraude. Deve ser maior que zero. | `60` | Não |
| `DICT_FRAUD_MARKER_INVENTORY_MAX_DOCUMENTS_PER_SWEEP` | Máximo de documentos conciliados em uma varredura de inventário. Deve ser maior que zero. | `200` | Não |
| `DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES` | Limite de obsolescência de readiness para o inventário de marcadores de fraude. Deve ser maior que zero. | `180` | Não |
## Rate limiting, idempotência e conectividade
| Variável | Descrição | Padrão | Obrigatório |
| ------------------------------------- | ------------------------------------------------------------------------------------- | ------- | -------------------------------------- |
| `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, em segundos. | `60` | Não |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Por quanto tempo, em segundos, uma chave de idempotência é retida. | `86400` | Não |
| `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | Chave AES-256 para criptografar as respostas de idempotência armazenadas. Sensível. | — | Runtime protegido do SPI, DICT ou Core |
| `INFRA_CONNECT_TIMEOUT_SEC` | Timeout de conexão para dependências de infraestrutura na inicialização, em segundos. | `30` | Não |
## Systemplane e configuração em runtime
| Variável | Descrição | Padrão | Obrigatório |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- |
| `SYSTEMPLANE_ENABLED` | Habilita a API administrativa de configuração em runtime do systemplane, montada em `/v1/system` na porta principal. Quando `false`, o serviço roda em modo apenas variável de ambiente, sem plano administrativo. **O SPI vem com isso habilitado por padrão** — diferente da maioria dos serviços Lerian, em que o systemplane vem desabilitado por padrão. | `true` | Não |
Consulte [Systemplane](/pt/reference/platform/systemplane/overview) para a API, os namespaces e as permissões exigidas.
## Observabilidade
| Variável | Descrição | Padrão | Obrigatório |
| -------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | ------------------------ |
| `ENABLE_TELEMETRY` | Habilita o tracing e as métricas do OpenTelemetry. | `false` | Não |
| `TELEMETRY_REQUIRED` | Falha a inicialização se a telemetria não conseguir 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. | `1.0.0` | Não |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Rótulo do ambiente de deploy. | `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 do Prometheus. Se liga ao loopback por padrão. | `127.0.0.1:9090` | Não |
## Documentação
| Variável | Descrição | Padrão | Obrigatório |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ------- | ----------- |
| `SWAGGER_ENABLED` | Serve a especificação OpenAPI e a interface de documentação da API. Forçado como desabilitado em produção. | `false` | Não |
## Health e readiness
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 [Health e readiness](/pt/reference/health-and-readiness) para o contrato de probe.