> ## 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. 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](https://docs.lerian.studio/pt/reference/byoc-configuration.md).

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

> [!NOTE]
>
> 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. A chave `brcode.server/public_base_url` do systemplane a sobrescreve em runtime. | — | Em um ambiente protegido ou se o BR Code JOSE estiver habilitado |
| `ACCESS_CONTROL_ALLOW_ORIGIN` | Origens de CORS permitidas, separadas por vírgula. Cada entrada é uma origem exata `scheme://host[:port]`, escrita como o navegador a envia: host em minúsculas, sem porta padrão, sem caminho e sem barra final. Um curinga, inclusive `*.domain`, interrompe a inicialização em qualquer ambiente. Um ambiente protegido aceita apenas origens `https`, então recusa o padrão. | `http://localhost:3000` | Em um ambiente protegido |
| `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 |
| `AUTH_REQUIRED` | Com `true`, as rotas protegidas respondem `503` quando a autenticação está desligada. | `false` | Não |
| `AUTH_TIMEOUT` | Limite de tempo da verificação de uma requisição no Access Manager, com as novas tentativas incluídas. Escreva com unidade, como `30s`. | `30s` | Não |
| `AUTH_CACHE_TTL` | Tempo que o trilho guarda cada decisão do Access Manager. Escreva com unidade, como `30s`. Uma mudança de permissão pode levar esse tempo para valer. Sem valor, o trilho não guarda decisões. | — | Não |
| `AUTH_BREAKER_ENABLED` | Liga um circuit breaker para as chamadas ao Access Manager. Após 5 chamadas seguidas com falha, ele interrompe as chamadas por 30 segundos. Nesse período, o trilho recusa toda requisição sem aprovação em cache. Defina `true` ou `false`. | `false` | Não |
| `AUTH_RETRY_MAX` | Máximo de novas tentativas de uma chamada ao Access Manager que falha sem decisão. `0` desliga as novas tentativas. | `0` | Não |
| `AUTH_JWT_VERIFY_CERT` | Uma ou mais chaves públicas RSA em PEM ou certificados X.509, separados por quebras de linha. Com uma chave carregada, o trilho verifica a assinatura RS256 e a expiração de cada token bearer, e responde `401` quando a verificação falha. Tem precedência sobre `AUTH_JWT_VERIFY_CERT_PATH`. | — | Não |
| `AUTH_JWT_VERIFY_CERT_PATH` | Caminho de um arquivo com o mesmo conteúdo. O trilho o lê somente quando `AUTH_JWT_VERIFY_CERT` está vazia. | — | Não |

## Declaração de permissões

Cada binário pode publicar sua declaração de permissões no Access Manager na inicialização. Essas variáveis são separadas de `AUTH_ENABLED`.

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `IDP_DECLARATION_ENABLED` | Defina `true` para publicar a declaração de permissões na inicialização. Defina `true` ou `false`. | `false` | Não |
| `IDP_HOST` | URL `http` ou `https` absoluta do serviço Identity do Access Manager. | — | Se a declaração estiver ligada |
| `IDP_M2M_CLIENT_ID` | ID de cliente com o qual o binário publica. | — | Se a declaração estiver ligada |
| `IDP_M2M_CLIENT_SECRET` | Segredo de cliente com o qual o binário publica. Sensível. | — | Se a declaração estiver ligada |
| `PLUGIN_AUTH_ENABLED` | Liga a solicitação de token de que a publicação precisa. Deve ser `true` quando a declaração está ligada. Defina `true` ou `false`. | `false` | Se a declaração estiver ligada |

Com `IDP_DECLARATION_ENABLED=true`, o binário não inicia quando uma das três variáveis obrigatórias está vazia, quando `IDP_HOST` não é válido ou quando `PLUGIN_AUTH_ENABLED` não é `true`. A publicação também precisa do endereço do Access Manager, definido em `PLUGIN_AUTH_ADDRESS`. Quando o Access Manager recusa a publicação ou não responde, o binário continua iniciando.

## Licença

Todo binário (`spi`, `dict`, `brcode` e `core`) precisa de uma licença para iniciar. Uma licença cobre os quatro binários e é global: o trilho não lê lista de organizações.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `LICENSE_KEY` | Chave de licença. O trilho a valida no serviço de licenças da Lerian, `license.lerian.io`, em todo ambiente. | — | Sim |
| `LICENSE_FILE_PATH` | Caminho de um arquivo de licença. Quando ela está definida, o trilho usa o arquivo e ignora `LICENSE_KEY`, e um arquivo que o trilho recusa impede a inicialização. Deixe-a vazia e defina `LICENSE_KEY`. | — | Não |

Um binário interrompe a inicialização quando nenhuma das duas variáveis está definida, seja qual for o valor de `ENV_NAME`. A verificação de licença cobre toda rota, exceto `/health`, `/readyz`, `/version`, `/metrics`, então cobre também as rotas de payload e de conjunto de chaves do BR Code. Quando a licença é recusada, na inicialização ou em uma verificação posterior em segundo plano, o binário é interrompido. Um pod com `LICENSE_KEY` precisa de HTTPS de saída para `license.lerian.io`.

## 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. O binário `spi` também baixa dele a lista de certificados de QR do BACEN. | — | No binário `spi`, com a resolução do lado do pagador habilitada e a confiança de teste desligada, a menos que `BACEN_ARQ_ENABLED` seja `false` |
| `BACEN_ARQ_ENABLED` | `false` desliga o cliente de transferência de arquivos, tanto a busca de arquivos de extrato quanto o download da lista de certificados de QR, mesmo com `BACEN_ARQ_ENDPOINT` definida. Qualquer outro valor deixa a decisão com o endpoint. Com `false`, o binário `spi` nunca atualiza a lista, e o `brcode` mantém a última lista armazenada. | — | 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_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`.

Com o backend `kmip`, um UID errado da chave privada de assinatura ou um ajuste errado de DigestInfo impede a inicialização. O mesmo vale para os backends KMIP do DICT e do BR Code JOSE.

| 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. Um certificado vencido indica falha em sua verificação, e `/readyz` continua pronto. | `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. Com `DEPLOYMENT_MODE=saas`, ela deve usar `https`. | — | Se `kmip` |
| `BACEN_SPI_KMIP_CA_FILE` | Pacote PEM da CA privada do HSM. O trilho confia nele além das raízes do sistema. | — | Não |
| `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. O cliente não lê `HTTP_PROXY` nem `HTTPS_PROXY`.

| 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`. Com `DEPLOYMENT_MODE=saas`, ele deve usar `https`. | — | 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`. Qualquer outro valor interrompe a inicialização. Um ambiente protegido recusa `file` no binário `dict`. | `file` | Em um ambiente protegido |
| `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. Com `DEPLOYMENT_MODE=saas`, ela deve usar `https`. | — | Se `kmip` |
| `BACEN_DICT_KMIP_CA_FILE` | Pacote PEM da CA privada do HSM. O trilho confia nele além das raízes do sistema. | — | Não |
| `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. Com `DEPLOYMENT_MODE=saas`, ela deve usar `https`. | — | Se o BR Code JOSE estiver habilitado com `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CA_FILE` | Pacote PEM da CA privada do HSM. O trilho confia nele além das raízes do sistema. | — | Não |
| `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` | Somente na confiança de teste: caminho do zip que contém a lista de certificados com o certificado do site de QR simulado. Um arquivo vazio ou ilegível interrompe a inicialização. Fora da confiança de teste, o `brcode` lê a lista do banco de dados e ignora esta variável. | — | Se a confiança de teste estiver ligada |
| `BACEN_BRCODE_QR_PAYER_TEST_TRUST` | Somente desenvolvimento: relaxa as verificações do site do QR (CAs raiz extras de `BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE`, um site em rede privada, sem política EV, revogação em soft-fail). A inicialização para, a menos que `ENV_NAME` seja `development`, `develop`, `dev`, `local` ou `test`, e com `DEPLOYMENT_MODE=saas`. | `false` | Não |
| `BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE` | Arquivo PEM das CAs raiz da confiança de teste. | — | Se a confiança de teste estiver ligada |

Com `BACEN_ARQ_ENDPOINT` definida e `BACEN_ARQ_ENABLED` diferente de `false`, o binário `spi` verifica a lista de certificados a cada hora. Quando a lista armazenada tem 24 horas, ele baixa a lista do BACEN pelos arquivos `BACEN_TLS_*`, a valida e a armazena no banco de dados. Um download com falha ou inválido mantém a última lista. O `ENV_NAME` do binário `spi` seleciona a lista: `production` baixa a lista de produção, e qualquer outro valor baixa a lista de homologação. O binário `brcode` lê a lista armazenada a cada minuto e não precisa dos arquivos `BACEN_TLS_*` nem de `BACEN_ARQ_ENDPOINT` para isso, então `brcode` e `spi` devem usar o mesmo banco PostgreSQL. Até a primeira lista ser armazenada, a resolução responde `503`. O binário `spi` interrompe a inicialização quando `BACEN_BRCODE_QR_PAYER_ENABLED` é `true` no próprio ambiente, a confiança de teste está desligada, `BACEN_ARQ_ENDPOINT` está vazia e `BACEN_ARQ_ENABLED` é diferente de `false`.

## Criptografia e hashing de PII

> [!WARNING]
>
> 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](https://docs.lerian.studio/pt/rails/spi/how-spi-works.md) 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` indica falha na verificação do arquivo enquanto o bucket não responde, e continua pronto.

## 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](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) 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](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato de probe.

A resposta de `/readyz` inclui uma verificação `license`. Com `LICENSE_KEY`, a verificação está sempre ativa e não faz chamada ao serviço de licenças, então uma licença inválida não leva `/readyz` a `503`. Uma licença que o trilho recusa interrompe o binário, na inicialização ou em uma verificação posterior em segundo plano.

As verificações de certificado, a de custódia do assinador e a do arquivo regulatório informam seu estado real no corpo de `/readyz`. Quando uma indica falha, `/readyz` continua pronto.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.