Variáveis de ambiente

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. 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.

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 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 para o contrato de probe.

​Runtime e servidor

​Autenticação

​Callback do BACEN (entrada vinda do SPI)

​Transporte de liquidação do SPI (BACEN_SPI_*)

​TLS mútuo com o BACEN

​Assinatura de mensagens e certificados

​Validação de certificado (OCSP/CRL)

​Resolvedor de payload

​Canal de entrada (BACEN_ICOM_*)

​Cliente DICT (BACEN_DICT_*)

​Assinatura JOSE do BR Code (BACEN_BRCODE_JOSE_*)

​Criptografia e hashing de PII

​PostgreSQL

​Redis

​Outbox e streaming

​Agendadores

​Descoberta e inventário do DICT

​Rate limiting, idempotência e conectividade

​Systemplane e configuração em runtime

​Observabilidade

​Documentação

​Health e readiness

Runtime e servidor

Autenticação

Callback do BACEN (entrada vinda do SPI)

Transporte de liquidação do SPI (`BACEN_SPI_*`)

TLS mútuo com o BACEN

Assinatura de mensagens e certificados

Validação de certificado (OCSP/CRL)

Resolvedor de payload

Canal de entrada (`BACEN_ICOM_*`)

Cliente DICT (`BACEN_DICT_*`)

Assinatura JOSE do BR Code (`BACEN_BRCODE_JOSE_*`)

Criptografia e hashing de PII

PostgreSQL

Redis

Outbox e streaming

Agendadores

Descoberta e inventário do DICT

Rate limiting, idempotência e conectividade

Systemplane e configuração em runtime

Observabilidade

Documentação

Health e readiness