Variáveis de ambiente

O Lerian SPI é a integração de mensageria nativa da Lerian para o Pix. Ele alcança o sistema de pagamentos instantâneos do BACEN (SPI) e o diretório de chaves DICT sobre a RSFN. Ele é entregue como 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 em tempo de execução sem reiniciar. As demais variáveis exigem uma reinicialização para mudar. 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. Nas tabelas abaixo, Obrigatória marca uma variável que você deve definir — globalmente, 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 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ória
`ENV_NAME`	Rótulo do ambiente de runtime. Quando não definida, ela resolve para `development`; um `none` explícito é inválido. 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` ou `: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 e links de payload de BR Code.	—	Em produção ou se JOSE do BR Code estiver habilitado
`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.	`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. 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.	—	Se o consumidor ICOM primário estiver habilitado

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.	—	Se o consumidor ICOM secundário estiver habilitado
`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. Mínimo de 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_* dão suporte ao canal de TLS mútuo com o BACEN. Os clientes SPI e DICT os compartilham.

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

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ó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 vinculado à chave de assinatura. É obrigatório para `pkcs11` ou `kmip`; com `file`, usa `BACEN_TLS_CERT_FILE` como fallback quando não é definido.	`BACEN_TLS_CERT_FILE` (`file`)	Se `pkcs11` ou `kmip`
`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

Estas variáveis controlam como o serviço armazena e referencia os payloads SPI grandes.

Variável	Descrição	Padrão	Obrigatória
`BACEN_SPI_PAYLOAD_RESOLVER_KIND`	Backend de armazenamento de payload: `in_memory` ou `postgres`. Ambientes de tipo 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 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-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ória
`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 (milissegundos).	`90000`	Não

Com BACEN_ICOM_CONSUMER_ENABLED=true, a inicialização também requer um backend de persistência configurado, BACEN_SPI_INTERNAL_CALLBACK_SECRET e BACEN_CALLBACK_MTLS_HEADER_SECRET. Com BACEN_ICOM_SECONDARY_CONSUMER_ENABLED=true, também requer 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ó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.	—	Para o caminho de custódia DICT selecionado
`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-256 para criptografar intents de reivindicação DICT armazenados. Sensível.	—	Em produçã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.	—	Se JOSE do BR Code estiver habilitado
`BACEN_BRCODE_JOSE_SIGNING_KEY_FILE`	Caminho para a chave privada de assinatura JOSE (backend de arquivo). Sensível.	—	Se JOSE do BR Code estiver habilitado com `file`
`BACEN_BRCODE_JOSE_KID`	Valor do header identificador de chave JWS (`kid`).	—	Se JOSE do BR Code estiver habilitado
`BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH`	Caminho do módulo PKCS#11.	—	Se JOSE do BR Code estiver habilitado com `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL`	Label do token PKCS#11.	—	Se JOSE do BR Code estiver habilitado com `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_PIN_FILE`	Caminho para o arquivo do PIN do token. Sensível.	—	Se JOSE do BR Code estiver habilitado com `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL`	Label da chave de assinatura no token.	—	Se JOSE do BR Code estiver habilitado com `pkcs11`
`BACEN_BRCODE_JOSE_KMIP_BASE_URL`	URL base do serviço KMIP.	—	Se JOSE do BR Code estiver habilitado com `kmip`
`BACEN_BRCODE_JOSE_KMIP_VHSM`	Identificador do HSM virtual.	—	Se JOSE do BR Code estiver habilitado com `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`	Usuário cripto do KMIP.	—	Se JOSE do BR Code estiver habilitado com `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`	Token do usuário cripto do KMIP. Sensível.	—	Se JOSE do BR Code estiver habilitado com `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID`	UID da chave privada de assinatura.	—	Se JOSE do BR Code estiver habilitado com `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`	UID da chave pública de assinatura.	—	Se JOSE do BR Code estiver habilitado com `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 contém material sensível de chave ou pepper. Ela protege os dados pessoais em repouso por meio de criptografia e blind-indexing. Nunca faça commit nem registre em log um valor. Injete-o no momento do deploy através do seu gerenciador de segredos. Uma rotação de pepper ou de chave exige um re-index ou 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.	—	Runtime DICT protegido
`DICT_KEY_BLIND_INDEX_PEPPER`	Pepper para blind-indexing de PII de chave DICT. Sensível.	—	Runtime DICT protegido
`DICT_AUDIT_HASH_PEPPER`	Pepper para hashing de registros de auditoria DICT. Sensível.	—	Runtime protegido
`AUDIT_HASH_PEPPER`	Pepper de hash de auditoria legado. Sensível.	—	Runtime protegido
`SPI_RESPONSIBLES_ENCRYPTION_KEY`	Chave AES para PII de parte responsável. Sensível.	—	Runtime SPI protegido
`SPI_OPERATIONS_PII_ENCRYPTION_KEY`	Chave AES-256 para PII de operação. Sensível. O serviço SPI se recusa a iniciar se ela estiver ausente ou malformada.	—	Sim — serviço SPI em todos os ambientes
`SPI_OPERATIONS_BLIND_INDEX_PEPPER`	Pepper para blind-indexing de PII de operação. Sensível. Deve ter pelo menos 32 caracteres; o serviço SPI se recusa a iniciar se estiver ausente ou for menor.	—	Sim — serviço SPI em todos os ambientes
`BRCODE_PII_ENCRYPTION_KEY`	Chave AES para PII de BR Code. Sensível.	—	Runtime BR Code protegido
`BRCODE_PII_BLIND_INDEX_PEPPER`	Pepper para blind-indexing de PII de BR Code. Sensível.	—	Runtime BR Code protegido

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.	`brspi`	Não
`POSTGRES_PASSWORD`	Senha do banco de dados. Sensível. Use um segredo explícito em produção.	Senha de desenvolvimento no código	Não
`POSTGRES_DB`	Nome do banco de dados.	`brspi`	Não
`POSTGRES_SSLMODE`	Modo TLS do libpq. Para conexões remotas de produção, use `verify-full` com uma CA confiável; `require` cifra 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 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. O consumidor de liquidação do BR Code roda incondicionalmente. O streaming não tem uma chave de habilitação: STREAMING_BROKERS é obrigatório 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 Streaming e outbox.

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
`SPI_PARTICIPANT_CONSUMER_ENABLED`	Habilita o consumidor de solicitações de participante do Core para o SPI. Ele assina o stream da aplicação produtora Core; o tópico é derivado e não configurável. Requer `STREAMING_BROKERS`, transporte BACEN e persistência quando habilitado.	`false`	Não
`SPI_PARTICIPANT_CONSUMER_GROUP`	Consumer group durável para solicitações de participante.	Padrão interno do serviço	Não
`SPI_PARTICIPANT_CONSUMER_CLIENT_ID`	Client ID apresentado ao broker pelo consumidor de solicitações de participante. Usa o client ID compartilhado de streaming como fallback.	Client ID compartilhado	Não

Agendadores

Jobs em segundo plano, cada um controlado de forma independente. Os jobs controlados pelo agendador abaixo ficam desligados por padrão. Os workers de descoberta e inventário do DICT têm controles próprios na seção seguinte.

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

Descoberta e inventário do DICT

A descoberta de reivindicações recebidas só executa quando SCHEDULER_ENABLED e SCHEDULER_INBOUND_DISCOVERY_ENABLED são true. Os demais workers do DICT abaixo executam independentemente de SCHEDULER_ENABLED, cada um com sua própria chave explícita de habilitação.

Variável	Descrição	Padrão	Obrigatória
`SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES`	Limite de desatualização de readiness para os feeds de descoberta de reivindicações recebidas. Deve ser maior que zero.	`30`	Não
`DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS`	Limite de lacuna após o qual o feed de eventos de recuperação de fundos registra um marcador bloqueado. 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 desatualização 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ções do DICT.	`true`	Não
`DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES`	Limite de desatualização de readiness para a descoberta de devoluções. Deve ser maior que zero.	`15`	Não
`DICT_PERSON_WATCHLIST_ENABLED`	Habilita a sondagem de documentos na lista de observação de pessoas do DICT.	`true`	Não
`DICT_PERSON_WATCHLIST_CADENCE_MINUTES`	Idade mínima antes de observar novamente um documento monitorado. Deve ser maior que zero.	`60`	Não
`DICT_PERSON_WATCHLIST_BATCH_LIMIT`	Máximo de documentos monitorados observados em um ciclo de sondagem. 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 um documento monitorado. Deve ser maior que zero.	`360`	Não
`DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES`	Falhas consecutivas de observação antes de colocar um documento monitorado 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 do 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 reconciliados em uma varredura de inventário. Deve ser maior que zero.	`200`	Não
`DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES`	Limite de desatualização 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ó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
`IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY`	Chave AES-256 para criptografar respostas de idempotência armazenadas. Sensível.	—	Runtime SPI, DICT ou Core protegido
`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 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 associado à 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 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 para o contrato das probes.

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

Variáveis de ambiente

Runtime e servidor

Autenticação

Callback do BACEN (entrada a partir do SPI)

Transporte de liquidação 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 de runtime

Observabilidade

Documentação

Saúde e prontidão

​Runtime e servidor

​Autenticação

​Callback do BACEN (entrada a partir do SPI)

​Transporte de liquidação 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 de runtime

​Observabilidade

​Documentação

​Saúde e prontidão

Runtime e servidor

Autenticação

Callback do BACEN (entrada a partir do SPI)

Transporte de liquidação 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 de runtime

Observabilidade

Documentação

Saúde e prontidão