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. Um valor que não pode ser lido no seu tipo, como yes em uma chave, impede a 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, telemetria), consulte Fundamentos de configuração do BYOC. Nas tabelas abaixo, Obrigatório marca uma variável que você deve definir, sempre (Sim) ou sob a condição indicada. — significa que não há padrão. As condições usam três termos:

Em operação real: o endpoint do BACEN usa https. Um ambiente local também aceita um endpoint http.
Ambiente local: ENV_NAME é development, local ou test.
Ambiente protegido: ENV_NAME é production, prod, staging, stage, pre-prod, preprod, pre-production ou preproduction.

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.	`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. Ela monta os links de payload do BR Code e a URL do conjunto de chaves JWS.	—	Em um ambiente protegido ou se o BR Code JOSE estiver habilitado
`ACCESS_CONTROL_ALLOW_ORIGIN`	Origens de CORS permitidas. Um ambiente protegido recusa um curinga.	`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 ou CIDRs de proxy, separados por vírgula, confiáveis para definir o IP real do cliente. Curingas são recusados.	—	Em um ambiente protegido com `TLS_TERMINATED_UPSTREAM=true`
`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). Exige os arquivos de certificado e de chave.	—	Não
`TLS_TERMINATED_UPSTREAM`	Defina como `true` quando o TLS é terminado por um load balancer ou proxy reverso.	`false`	Não

Um ambiente protegido exige os arquivos de certificado e de chave do servidor, ou TLS_TERMINATED_UPSTREAM=true.

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. Defina `true` ou `false`. Um valor em branco impede a inicialização. `false` inicia apenas quando `ENV_NAME` é `development`, `develop`, `dev`, `local` ou `test`, e nunca com `DEPLOYMENT_MODE=saas`.	—	Sim
`PLUGIN_AUTH_ADDRESS`	Endereço do serviço Access Manager. Um ambiente protegido exige `https://`.	—	Se `AUTH_ENABLED=true` ou em um ambiente protegido

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. Defina junto com o segredo de header.	—	Com o segredo de header
`BACEN_CALLBACK_MTLS_HEADER_SECRET`	Segredo compartilhado que comprova que o upstream terminou o TLS mútuo do callback. Pelo menos 32 caracteres. Sensível.	—	Se um consumidor ICOM estiver habilitado

Fora de um ambiente local, o trilho precisa de exatamente um modo de TLS mútuo de callback. No modo direto, defina SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE e SERVER_TLS_CLIENT_CA_FILE. No modo proxy, defina TLS_TERMINATED_UPSTREAM=true, os CIDRs confiáveis e o segredo de header.

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

Conexão com o endpoint de liquidação do SPI do BACEN pela RSFN, com o canal secundário de mensageria e o endpoint de transferência de arquivos (ARQ).

Variável	Descrição	Padrão	Obrigatório
`BACEN_SPI_ENDPOINT`	URL do endpoint primário do SPI.	`http://localhost:9900`	Fora de um ambiente local
`BACEN_SPI_SECONDARY_ENDPOINT`	URL do canal secundário de mensageria. O trilho envia `pain.013`, `pain.014`, `camt.025` e `trck.002` nesse canal. Quando não definida, esses envios falham.	—	Se o consumidor ICOM secundário estiver habilitado
`BACEN_ARQ_ENDPOINT`	URL do endpoint de transferência de arquivos do BACEN. O trilho busca nele arquivos grandes de extrato.	—	Não
`BACEN_SPI_PARTICIPANT_ISPB`	O ISPB de 8 caracteres (dígitos ou letras maiúsculas) do participante para a superfície do SPI.	—	Em operação real ou se um consumidor ICOM estiver habilitado
`BACEN_SPI_ALLOWED_ENDPOINT_HOSTS`	Lista de hosts permitidos que o cliente SPI pode acessar (proteção contra SSRF). Ela deve incluir o host do endpoint.	—	Fora de um ambiente local
`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_RETRY_ATTEMPTS`	Máximo de tentativas por requisição de transporte, incluindo a primeira.	`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 taxa de saída no lado do cliente. Deve ser `true` fora de um ambiente local.	`false`	Fora de um ambiente local
`BACEN_SPI_OUTBOUND_QUOTA_LIMIT`	Cota de saída sustentada (requisições por segundo). Deve ser positiva.	—	Se a cota estiver habilitada
`BACEN_SPI_OUTBOUND_QUOTA_BURST`	Margem de burst acima da cota. Deve ser positiva.	—	Se a cota estiver habilitada
`BACEN_SPI_CATALOGUE_VERSION`	Versão do catálogo de mensagens do SPI do BACEN.	`5.13.2`	Não
`BACEN_SPI_XSD_DIR`	Diretório dos esquemas XSD do BACEN que validam as mensagens. Um valor que você define é usado como está, então ele deve conter os esquemas de `BACEN_SPI_CATALOGUE_VERSION`.	O pacote da versão do catálogo	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 de callback interno. Pelo menos 32 caracteres quando definido. Sensível.	—	Em um ambiente protegido ou se um consumidor ICOM 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.	—	Em operação real
`BACEN_TLS_KEY_FILE`	Chave privada do cliente. Sensível.	—	Em operação real
`BACEN_TLS_CA_FILE`	Pacote de CA usado para verificar o certificado de servidor do BACEN.	—	Em 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`. Um ambiente protegido recusa `file`.	`file`	Em um ambiente protegido
`BACEN_SPI_SIGNER_COMMON_NAME`	Common name esperado do certificado de assinatura.	—	Fora de um ambiente local
`BACEN_SPI_SIGNING_CERT_FILE`	Caminho do certificado ligado à chave de assinatura.	—	Em operação real, ou se `pkcs11` ou `kmip`
`BACEN_SPI_SIGNING_KEY_FILE`	Caminho da chave privada de assinatura (backend file). Sensível.	—	Em operação real com `file`
`BACEN_SPI_VERIFY_CERT_FILE`	Bundle de certificados usado para verificar a assinatura do BACEN nas mensagens de entrada.	—	Em operação real
`BACEN_SPI_INBOUND_SIGNER_COMMON_NAME`	Common name esperado do signatário nas mensagens de entrada.	—	Fora de um ambiente local
`CERT_READINESS_MIN_DAYS`	Mínimo de dias até o vencimento de um certificado. Um certificado válido com menos dias restantes mantém sua verificação de readiness ativa e registra um aviso.	`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: `soft_fail`, `hard_fail` ou `disabled`. Um ambiente protegido recusa `disabled`.	`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`. Um ambiente protegido recusa `in_memory`.	`in_memory`	Em um ambiente protegido
`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. Ele deve ser igual a `BACEN_SPI_PARTICIPANT_ISPB`.	—	Se um consumidor ICOM 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

Cada consumidor exige um backend de persistência configurado, BACEN_ICOM_ISPB, BACEN_SPI_INTERNAL_CALLBACK_SECRET e BACEN_CALLBACK_MTLS_HEADER_SECRET. O consumidor primário também exige BACEN_ICOM_BASE_URL. O consumidor secundário também exige BACEN_SPI_SECONDARY_ENDPOINT. Um consumidor habilitado exige o modo proxy de callback: TLS_TERMINATED_UPSTREAM=true, nenhum SERVER_TLS_CLIENT_CA_FILE e BACEN_CALLBACK_TRUSTED_PROXY_CIDRS com o endereço de onde o consumidor encaminha. Com o SERVER_ADDRESS padrão, esse endereço é 127.0.0.1.

Cliente DICT (`BACEN_DICT_*`)

Cliente para o diretório de chaves Pix do BACEN (DICT), incluindo o endpoint NP para verificações de existência de chaves em lote.

Variável	Descrição	Padrão	Obrigatório
`BACEN_DICT_ENDPOINT`	URL do endpoint do DICT.	`http://localhost:9900`	Fora de um ambiente local
`BACEN_DICT_PARTICIPANT_ISPB`	ISPB do participante para a superfície do DICT.	—	Fora de um ambiente local
`BACEN_DICT_ALLOWED_ENDPOINT_HOSTS`	Lista de hosts permitidos que o cliente DICT pode acessar. Ela deve incluir o host do endpoint.	—	Fora de um ambiente local
`BACEN_DICT_TIMEOUT_SEC`	Timeout de requisição do DICT, em segundos.	`10`	Não
`BACEN_DICT_CID_SET_FILE_MAX_BYTES`	Maior arquivo do conjunto de CIDs, em bytes, que o trilho baixa. O trilho recusa um arquivo que declara um tamanho maior.	`8589934592`	Não
`BACEN_DICT_CID_SET_FILE_IDLE_TIMEOUT_SEC`	Timeout de cada leitura do download de um arquivo do conjunto de CIDs, em segundos.	`60`	Não
`BACEN_DICT_NP_ENDPOINT`	URL do endpoint NP para verificações de existência de chaves em lote. Quando não definida, a verificação em lote responde `501`.	—	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.	—	Em operação real
`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_OUTBOUND_QUOTA_ENABLED`	Habilita a cota de requisições ao DICT no lado do cliente. `false` inicia apenas em um ambiente local.	`true`	Não
`BACEN_DICT_ENTRIES_READ_CATEGORY`	A categoria de leitura de entradas DICT do participante, uma letra de `A` a `H`.	—	Para o binário `dict` enquanto a cota estiver habilitada
`BACEN_DICT_SPONSORED_ENTRIES_READ_CATEGORIES`	Categorias de leitura de entradas de participantes patrocinados, como pares `ispb:letter`. Um participante sem par usa `H`.	—	Não
`BACEN_DICT_QUERY_MONITOR_ENABLED`	Habilita o monitor de consultas do DICT. `false` inicia apenas em um ambiente local. Seus limites têm padrões.	`true`	Não

Assinatura JOSE do BR Code (`BACEN_BRCODE_JOSE_*`)

Assina payloads dinâmicos do BR Code (JWS). Quando BACEN_BRCODE_JOSE_SIGNER_KIND não está definida, o JOSE fica desabilitado e os endpoints públicos de payload se recusam a servir. Com o JOSE habilitado, roteie os caminhos de payload (/api/v1/brcode/payload/*) e o caminho do conjunto de chaves (/api/v1/brcode/.well-known/jwks.json) sob a PUBLIC_BASE_URL para o binário brcode, sem nenhum autorizador na frente deles. O PSP do pagador chama essas rotas sem credencial.

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

Resolução de QR do BR Code (`BACEN_BRCODE_QR_PAYER_*`)

Controla a resolução de um QR dinâmico no lado do pagador. Quando a resolução está desligada, a operação dela responde 503.

Variável	Descrição	Padrão	Obrigatório
`BACEN_BRCODE_QR_PAYER_ENABLED`	Habilita a resolução de QR codes dinâmicos no lado do pagador.	`false`	Não
`BACEN_BRCODE_QR_PAYER_CERT_LIST_FILE`	Caminho da lista do BACEN de certificados de site de QR autorizados. Um arquivo vazio ou ilegível interrompe a inicialização.	—	Se a resolução estiver habilitada

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.

Cada chave tem 32 bytes, em formato bruto ou base64. Cada pepper tem pelo menos 32 caracteres.

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.	—	Binário `dict` em um ambiente protegido
`DICT_KEY_BLIND_INDEX_PEPPER`	Pepper para indexação cega da PII de chaves DICT. Sensível.	—	Binário `dict` em um ambiente protegido
`DICT_AUDIT_HASH_PEPPER`	Pepper para o hash de registros de auditoria do DICT. Sensível.	—	Em um ambiente protegido, ou para o binário `dict` fora de um ambiente local
`AUDIT_HASH_PEPPER`	Pepper de hash de auditoria de fallback, lido apenas quando `DICT_AUDIT_HASH_PEPPER` não está definido. Sensível.	—	Não
`SPI_RESPONSIBLES_ENCRYPTION_KEY`	Chave AES para a PII de responsáveis. Sensível.	—	Binário `spi` em um ambiente protegido
`SPI_OPERATIONS_PII_ENCRYPTION_KEY`	Chave AES-256 para a PII de operação. Sensível.	—	Sim, para o binário `spi`
`SPI_OPERATIONS_BLIND_INDEX_PEPPER`	Pepper para indexação cega da PII de operação. Sensível.	—	Sim, para o binário `spi`
`BRCODE_PII_ENCRYPTION_KEY`	Chave AES para a PII do BR Code. Sensível.	—	Binário `brcode` em um ambiente protegido
`BRCODE_PII_BLIND_INDEX_PEPPER`	Pepper para indexação cega da PII do BR Code. Sensível.	—	Binário `brcode` em um ambiente protegido

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 um ambiente protegido.	Senha de desenvolvimento embutida no código	Não
`POSTGRES_DB`	Nome do banco de dados.	`brspi`	Não
`POSTGRES_SSLMODE`	Modo TLS do libpq. Um ambiente protegido recusa `disable`. Use `verify-full` com uma CA confiável para conexões remotas. `require` criptografa o canal, mas não verifica a identidade do servidor.	`disable`	Em um ambiente protegido
`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 da réplica de leitura. O serviço usa a réplica apenas quando o host e a porta dela estão definidos.	—	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 TLS da réplica. Quando não definido, a réplica usa o modo do primário.	—	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 de CA para TLS do Redis.	—	Se `REDIS_TLS=true`
`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

Arquivo regulatório (`REGULATORY_ARCHIVE_*`)

Os binários spi e dict mantêm o arquivo regulatório em um armazenamento compatível com S3. Os binários brcode e core não usam essas variáveis.

Variável	Descrição	Padrão	Obrigatório
`REGULATORY_ARCHIVE_BUCKET`	Bucket que guarda o arquivo.	—	Fora de um ambiente de desenvolvimento
`REGULATORY_ARCHIVE_ENDPOINT`	URL base da API S3. Quando não está definida, o trilho usa o endpoint regional da AWS. Com `DEPLOYMENT_MODE=saas`, ela deve usar `https`.	—	Não
`REGULATORY_ARCHIVE_REGION`	Região do armazenamento.	—	Se o bucket estiver definido
`REGULATORY_ARCHIVE_ACCESS_KEY`	Chave de acesso. Defina-a junto com a chave secreta. Sem as duas, o trilho usa as fontes de credenciais padrão da AWS.	—	Não
`REGULATORY_ARCHIVE_SECRET_KEY`	Chave secreta. Sensível.	—	Não
`REGULATORY_ARCHIVE_USE_PATH_STYLE`	Usa o endereçamento de bucket no estilo de caminho.	`false`	Não
`REGULATORY_ARCHIVE_SSE_ALGORITHM`	Criptografia no lado do servidor: `AES256`, `aws:kms` ou `none`. `none` inicia apenas em um ambiente de desenvolvimento.	—	Se o bucket estiver definido
`REGULATORY_ARCHIVE_SSE_KMS_KEY_ID`	ID da chave KMS para a criptografia `aws:kms`.	—	Se a criptografia for `aws:kms`
`REGULATORY_ARCHIVE_OBJECT_LOCK_MODE`	Modo de Object Lock: `COMPLIANCE`, `GOVERNANCE` ou `none`. `none` inicia apenas em um ambiente de desenvolvimento.	—	Se o bucket estiver definido

Aqui, um ambiente de desenvolvimento é aquele em que ENV_NAME é development, develop, dev, local ou test, e DEPLOYMENT_MODE não é saas. Essas regras leem ENV_NAME como definido, então um ENV_NAME não definido não é um ambiente de desenvolvimento. Uma variável obrigatória ausente impede a inicialização. Em um ambiente de desenvolvimento sem bucket, o trilho não arquiva nada. Com o arquivo ativo, /readyz em spi e dict informa o serviço como não pronto enquanto o bucket não responde.

Outbox e streaming

O Lerian SPI publica eventos por um outbox transacional e um produtor de 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. Cada binário exige seu próprio valor fixo de STREAMING_CLOUDEVENTS_SOURCE, e qualquer outro valor impede a inicialização: br-spi para spi, br-spi-dict para dict, br-spi-brcode para brcode e br-spi-core para core. Uma entrada de STREAMING_EVENT_POLICIES que desliga um evento do Lerian SPI impede a inicialização. Apenas os dois eventos spi_tracking e três eventos dict_med_operations (inconsistent_projection, feed_blocked e feed_record_abandoned) podem ser desligados.

Variável	Descrição	Padrão	Obrigatório
`OUTBOX_ENABLED`	Habilita o dispatcher do outbox transacional. Deve ser `true` para os binários `spi`, `dict` e `brcode` em um ambiente protegido.	`true`	Não
`OUTBOX_DISPATCH_INTERVAL_MS`	Intervalo entre ciclos de dispatch, em milissegundos.	`100`	Não
`OUTBOX_BATCH_SIZE`	Linhas processadas por ciclo de dispatch.	`50`	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
`CORE_PARTICIPANT_CONSUMER_ENABLED`	Habilita o consumidor do Core que aplica as confirmações de participante vindas do binário SPI. Defina `true` ou `false`. Qualquer outro valor impede a inicialização.	`false`	Não
`CORE_SETTLEMENT_COMPLETION_CONSUMER_ENABLED`	Habilita o consumidor do Core que move uma liquidação de `PENDING` para `SETTLED`. Defina `true` ou `false`. Qualquer outro valor impede a inicialização.	`false`	Não
`CORE_SETTLEMENT_TERMINATION_CONSUMER_ENABLED`	Habilita o consumidor do Core que aplica devoluções e falhas às liquidações. Defina `true` ou `false`. Qualquer outro valor impede a inicialização.	`false`	Não

Agendadores

Tarefas em segundo plano, cada uma com sua própria chave. As duas tarefas do DICT com padrão true carregam deveres regulatórios, então o binário dict inicia seu agendador para elas, a menos que SCHEDULER_ENABLED=false. O binário spi faz o mesmo para as tarefas de veredito dos agendamentos e de prazo de portabilidade. As tarefas com padrão false também exigem SCHEDULER_ENABLED=true. 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. Um `false` explícito para todas as tarefas abaixo.	`false`	Não
`SCHEDULER_CLAIM_DEADLINE_ENABLED`	Executa a tarefa de prazo de reivindicação do DICT.	`true`	Não
`SCHEDULER_INBOUND_DISCOVERY_ENABLED`	Executa as varreduras de descoberta de reivindicações do DICT, nos lados do doador e do reivindicante.	`true`	Não
`SCHEDULER_INBOUND_DISCOVERY_INTERVAL`	Intervalo entre os ciclos das varreduras de descoberta de reivindicações. Deve ser maior que zero e no máximo um minuto.	`15s`	Não
`SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES`	Limite de defasagem de readiness para as varreduras de descoberta de reivindicações. Deve ser maior que zero.	`15`	Não
`SCHEDULER_QUOTA_RESET_ENABLED`	Executa o reset diário da cota de participantes no Core, à meia-noite no horário de Brasília.	`false`	Não
`SCHEDULER_DICT_AUDIT_RETENTION_ENABLED`	Executa a limpeza de retenção dos logs de auditoria do DICT.	`false`	Não
`SCHEDULER_APPROVAL_EXPIRY_ENABLED`	A cada 5 minutos, move solicitações de aprovação expiradas para `EXPIRED`.	`false`	Não
`SCHEDULER_PORTABILITY_DEADLINE_ENABLED`	A cada 5 minutos, marca as operações de portabilidade cujo prazo de 24 horas passou. Ela também devolve ao operador uma operação de portabilidade cujo `reda.031` esperou 30 minutos pela resposta do BACEN. Ela nunca as confirma.	`true`	Não
`SCHEDULER_SCHEDULE_VERDICT_RECONCILER_ENABLED`	A cada 5 minutos, publica o evento de veredito ausente de uma operação de agendamento do Pix Automático encerrada de 15 minutos a 24 horas antes. Ela não roda quando `OUTBOX_ENABLED=false`.	`true`	Não

Descoberta e inventário do DICT

Os workers abaixo rodam independentemente de SCHEDULER_ENABLED, cada um com sua própria chave.

Variável	Descrição	Padrão	Obrigatório
`DICT_FUNDS_RECOVERY_EVENTS_ENABLED`	Habilita o feed de eventos de recuperação de fundos do DICT.	`true`	Não
`DICT_FUNDS_RECOVERY_EVENTS_MAX_STALENESS_MINUTES`	Limite de defasagem de readiness para o feed de eventos de recuperação de fundos.	`15`	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. Forçado a ligado em um ambiente protegido.	`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.	—	Sim
`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.	`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_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 UI de documentação da API. Forçado a desligado em um ambiente protegido.	`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_*)

​Resolução de QR do BR Code (BACEN_BRCODE_QR_PAYER_*)

​Criptografia e hashing de PII

​PostgreSQL

​Redis

​Arquivo regulatório (REGULATORY_ARCHIVE_*)

​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_*`)

Resolução de QR do BR Code (`BACEN_BRCODE_QR_PAYER_*`)

Criptografia e hashing de PII

PostgreSQL

Redis

Arquivo regulatório (`REGULATORY_ARCHIVE_*`)

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