> ## 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 SPB: runtime, conectividade STR/RSFN, assinatura de mensagens e certificados, persistência, eventos e segurança.

O Lerian SPB é a integração de mensageria nativa da Lerian para o STR (Sistema de Transferência de Reservas), o sistema de liquidação bruta em tempo real do BACEN, acessado pela RSFN. Defina essas variáveis no momento do deploy. Uma mudança apenas tem efeito depois que você reinicia o serviço. A maioria das variáveis é específica deste trilho. Para os parâmetros que se comportam da mesma forma em todo serviço Go da Lerian (postura de deploy, armazenamento de dados e telemetria), veja [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, de forma global ou na condição indicada. Um qualificador como *Em produção* ou *Se habilitado* restringe quando a exigência se aplica. `—` significa que não há padrão.

> [!NOTE]
>
> `ENV_NAME` ativa os portões de segurança mais rígidos. Defina-o como `production` ou `staging` e o serviço passa a exigir TLS no Redis e na conexão STR, e `verify-full` no PostgreSQL. Ele também exige custódia baseada em hardware para a chave privada SFN, e rejeita superfícies exclusivas de desenvolvimento. `ENV_NAME` não tem padrão. Defina-o explicitamente. O serviço se recusa a iniciar quando `ENV_NAME` não está definido ou contém um valor não reconhecido.

## Runtime e servidor

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENV_NAME` | Ambiente de runtime. Deve ser um dos seguintes: `production`, `staging` ou `develop`. Produção e staging ativam os portões de segurança descritos acima. | — | Sim |
| `DEPLOYMENT_MODE` | Variante de deploy: `local`, `byoc` ou `saas`. Produção e staging se recusam a iniciar sem ela. `saas` também exige `ENV_NAME` `production` ou `staging`, TLS nos armazenamentos de dados, nos upstreams e no broker, e SASL no broker. | `local` | Em produção/staging |
| `SERVICE_NAME` | Identificador do serviço usado em logs e telemetria. | Padrão do serviço | Não |
| `LOG_LEVEL` | Verbosidade do log (`debug`, `info`, `warn`, `error`). | `info` | Não |
| `SERVER_PORT` | Porta de escuta HTTP. As superfícies de liveness, readiness e systemplane vinculam essa mesma porta. | `3000` | Não |
| `CORS_ALLOWED_ORIGINS` | Origens CORS permitidas, separadas por vírgula. Em produção/staging, apenas origens `https://` são aceitas e origens localhost são rejeitadas. | `http://localhost:3000` | Não |
| `TRUSTED_PROXIES` | IPs/CIDRs de proxy, separados por vírgula, confiáveis para definir o IP real do cliente. Uma entrada que não é um endereço IP nem um intervalo CIDR impede o serviço de iniciar. | — | Não |

## Autenticação

O Lerian SPB delega a autorização, incluindo a API administrativa do systemplane, ao Access Manager. Veja [Fundamentos de configuração do BYOC](https://docs.lerian.studio/pt/reference/byoc-configuration.md#plugin-authentication).

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Exige autenticação do Access Manager nas rotas protegidas. Defina-a como `true` ou `false`; o serviço se recusa a iniciar quando ela não está definida ou tem qualquer outro valor. `false` apenas é aceito com `ENV_NAME=develop` e com um `DEPLOYMENT_MODE` diferente de `saas`. | — | Sim |
| `PLUGIN_AUTH_ADDRESS` | Endereço do serviço Access Manager. Deve ser uma URL `https://` em produção/staging. | `http://localhost:4000` | Em produção/staging |

## Declaração de permissões

O Lerian SPB pode publicar seu próprio conjunto de permissões no Access Manager na inicialização. `IDP_DECLARATION_ENABLED=true` ativa isso, e qualquer valor diferente de `true` ou `false` impede o serviço de iniciar. Com a publicação ativa, uma variável ausente abaixo recusa iniciar.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `IDP_DECLARATION_ENABLED` | Publica o conjunto de permissões na inicialização. | `false` | Não |
| `IDP_HOST` | URL base do Access Manager para a qual o conjunto é publicado. | — | Com declaração |
| `IDP_M2M_CLIENT_ID` | Client ID da aplicação machine-to-machine do serviço, cujo nome deve ser `br-spb`. | — | Com declaração |
| `IDP_M2M_CLIENT_SECRET` | Client secret dessa aplicação. Sensível. | — | Com declaração |

Com a declaração ativa, `PLUGIN_AUTH_ENABLED` deve ser `true` e `PLUGIN_AUTH_ADDRESS` deve estar definido, porque o serviço os usa para obter o token que a publicação usa.

## Licença

O Lerian SPB precisa de uma licença em todo ambiente, inclusive no de desenvolvimento. Ele não inicia sem `LICENSE_FILE_PATH` ou `LICENSE_KEY`. A licença é global: o Lerian SPB não lê nenhum identificador de organização. Para o host que a verificação da chave consulta, veja [License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager.md).

| Variável | Descrição | Padrão | Obrigatória |
| - | - | - | - |
| `LICENSE_FILE_PATH` | Caminho de um arquivo de licença. Quando ela está definida, o Lerian SPB usa o arquivo e ignora `LICENSE_KEY`, e um arquivo que o Lerian SPB recusa impede a inicialização. Deixe-a vazia e defina `LICENSE_KEY`. | — | Não |
| `LICENSE_KEY` | Chave de licença que a Lerian emite. Sensível. | — | Sim |

A licença protege toda rota sob `/v1/str`. Uma licença recusada responde `403` com um código `LCS-`, como a [lista de erros](https://docs.lerian.studio/pt/reference/rails/spb/spb-error-list.md) descreve.

## PostgreSQL

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `POSTGRES_HOST` | Host primário do PostgreSQL. Não deve ser `localhost` em produção/staging. | `localhost` | Em produção/staging |
| `POSTGRES_PORT` | Porta primária do PostgreSQL. | `5432` | Não |
| `POSTGRES_USER` | Usuário do banco de dados. | `postgres` | Não |
| `POSTGRES_PASSWORD` | Senha do banco de dados. Sensível. Injete-a no momento do deploy e nunca faça commit dela. Não deve ser `postgres` em produção/staging. | `postgres` | Em produção/staging |
| `POSTGRES_DB` | Nome do banco de dados. | Padrão do serviço | Não |
| `POSTGRES_SSLMODE` | Modo TLS do libpq. Deve ser `verify-full` em produção/staging. | `require` | Não |
| `POSTGRES_MAX_OPEN_CONNS` | Número máximo de conexões abertas. | `25` | Não |
| `POSTGRES_MAX_IDLE_CONNS` | Número máximo de conexões ociosas. | `10` | Não |
| `POSTGRES_CONN_MAX_LIFETIME` | Tempo máximo de vida da conexão (duração Go, por exemplo `5m`). | `5m` | Não |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Tempo máximo ocioso da conexão (duração Go). | `2m` | Não |

### Réplica do PostgreSQL

Réplica de leitura opcional. Todos os campos usam o primário como padrão quando não definidos.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `POSTGRES_REPLICA_HOST` | Host da réplica. Não definido = sem réplica. | — | 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. Deve ser `verify-full` em produção/staging quando uma réplica está definida. | — | Não |

## Redis

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `REDIS_HOST` | Host do Redis. Deve ser explícito e não local em produção/staging. | `localhost` | Em produção/staging |
| `REDIS_PORT` | Porta do Redis. | `6379` | Não |
| `REDIS_PASSWORD` | Senha do Redis. Sensível. | — | Em produção/staging |
| `REDIS_DB` | Número do banco de dados do Redis. | `0` | Não |
| `REDIS_TLS_ENABLED` | Habilita TLS para o Redis. Deve ser `true` em produção/staging. | `false` | Em produção/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Certificado CA em base64 para o TLS do Redis. | — | Em produção/staging |
| `REDIS_POOL_SIZE` | Tamanho do pool de conexões. | `20` | Não |
| `REDIS_MIN_IDLE_CONNS` | Número mínimo de conexões ociosas. | `5` | Não |

## Conectividade STR (RSFN)

O Lerian SPB troca mensagens STR com o BACEN pela RSFN usando um transporte IBM MQ. Essas variáveis definem a identidade do participante, a conexão com o queue manager e as filas. Os três nomes de fila derivam de `STR_ISPB`. Produção e staging recusam um nome de fila diferente do nome derivado. O serviço inicia quando não consegue alcançar o queue manager e se conecta quando o queue manager volta. Qualquer outra falha de conexão impede a inicialização. Um exemplo é um queue manager que recusa o nome do queue manager, o canal, as credenciais, as configurações de TLS ou os nomes das filas.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STR_ISPB` | O ISPB de 8 dígitos do participante. Em produção/staging, deve ser um ISPB real explícito, e não `00000000`. | `00000000` | Em produção/staging |
| `SILOC_ISPB` | O ISPB de 8 dígitos da câmara SILOC, resolvido no lado do servidor nas mensagens de liquidação relacionadas ao SILOC (nunca fornecido pelo cliente). Em produção/staging, deve ser um ISPB de câmara de 8 dígitos diferente de `00000000`. | `02992335` | Não |
| `STR_MQ_HOST` | Host do queue manager. | — | Sim (STR ativo) |
| `STR_MQ_PORT` | Porta de escuta do queue manager. | `1414` | Não |
| `STR_MQ_CHANNEL` | Canal de conexão do servidor MQ. | `DEV.APP.SVRCONN` | Não |
| `STR_MQ_QUEUE_MGR` | Nome do queue manager. | `QM1` | Não |
| `STR_MQ_USER` | Usuário de conexão do MQ. | `app` | Não |
| `STR_MQ_PASSWORD` | Senha de conexão do MQ. Sensível. | — | Em produção/staging |
| `STR_MQ_TLS_ENABLED` | Habilita TLS mútuo no canal MQ. Obrigatório para uma conexão STR real. | `false` | Em produção/staging |
| `MQSSLKEYR` | Caminho, sem a extensão do arquivo, do repositório de chaves do GSKit que dá suporte ao TLS do MQ. A chave privada fica aqui, nunca em uma variável de ambiente. | — | Em produção/staging |
| `STR_MQ_CIPHER_SPEC` | CipherSpec TLS que o serviço define no canal MQ quando `STR_MQ_TLS_ENABLED` está habilitado. Defina-a como a CipherSpec do canal `STR_MQ_CHANNEL` no seu queue manager. Um canal que usa uma CipherSpec `TLS_RSA_*` também precisa dessa CipherSpec em `AMQ_ALLOWED_CIPHERS`. | `ECDHE_RSA_AES_256_CBC_SHA384` | Não |
| `STR_MQ_SEND_QUEUE` | Fila de requisições de saída. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `STR_MQ_RESPONSE_QUEUE` | Fila de resposta. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `STR_MQ_RECEIVE_QUEUE` | Fila de recebimento de entrada. Derivada de `STR_ISPB` quando não definida. | Derivado | Não |
| `MQ_HEARTBEAT_INTERVAL` | Intervalo de heartbeat do MQ que o serviço define no canal (duração Go). | `300s` | Não |
| `MQ_DISCONNECT_INTERVAL` | Intervalo de desconexão esperado no queue manager (duração Go). O serviço o registra em log na conexão e não o define. | `6000s` | Não |
| `MQ_SEQ_WRAP` | Teto de reinício da sequência de mensagens esperado no canal do queue manager. O serviço o registra em log e não o define. | `99999999` | Não |
| `MQ_ADOPTNEWMCA` | Configuração `AdoptNewMCA` esperada no queue manager. O serviço a registra em log e não a define. | `ALL` | Não |

### Circuit breaker

Protege o transporte STR contra falhas no queue manager.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `CB_MAX_REQUESTS` | Requisições permitidas enquanto o circuit breaker está semiaberto. | `3` | Não |
| `CB_INTERVAL` | Janela móvel na qual as falhas são contadas (duração Go). | `30s` | Não |
| `CB_TIMEOUT` | Tempo limite de recuperação do estado aberto (duração Go). | `10s` | Não |
| `CB_CONSECUTIVE_FAILURES` | Falhas consecutivas antes de o circuit breaker disparar. | `5` | Não |
| `CB_FAILURE_RATIO` | Proporção de falhas que dispara o circuit breaker (0–1). | `0.5` | Não |
| `CB_MIN_REQUESTS` | Número mínimo de requisições em uma janela antes de a proporção de falhas poder disparar o circuit breaker. | `10` | Não |

## Assinatura de mensagens e certificados

O certificado SFN em `PROCESS_CERT_PATH` é a identidade do Lerian SPB na RSFN. A chave privada dele assina toda mensagem STR de saída e descriptografa as mensagens de entrada que o BACEN criptografa para esse certificado. Em um HSM, permita assinatura e descriptografia nessa chave. `SPB_SIGNER_KIND` define onde a chave fica. Produção e staging rejeitam a custódia `file` e exigem `pkcs11` ou `kmip`.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SPB_SIGNER_KIND` | Custódia da chave privada SFN: `file`, `pkcs11` ou `kmip`. `file` apenas é permitido quando `ENV_NAME=develop`; produção e staging o rejeitam. O serviço recusa `hsm` e `kms`. | `file` | Não |
| `CERT_BASE_PATH` | Diretório de onde uma rotação de certificado lê os arquivos de certificado e de chave. | `/certs` | Não |
| `PROCESS_CERT_PATH` | Caminho para o certificado SFN. A chave pública dele precisa corresponder à chave privada em custódia. | — | Em produção/staging |
| `PROCESS_PRIVATE_KEY_PATH` | Caminho para a chave privada SFN quando `SPB_SIGNER_KIND=file`. Sensível. | — | Não |
| `BACEN_PUBLIC_CERT_PATH` | Caminho para o certificado público inicial do BACEN, usado para verificar assinaturas recebidas e para a criptografia do SFN. O serviço acompanha cada novo certificado do BACEN que um GEN0018 anuncia, sem mudança neste arquivo. | — | Em produção/staging |
| `CERT_READINESS_MIN_DAYS` | Número mínimo de dias até o vencimento. Um certificado que vence antes disso mantém o `/readyz` pronto: a verificação informa os dias restantes, e o serviço registra um aviso no log. | `30` | Não |

### Custódia PKCS#11

Obrigatório quando `SPB_SIGNER_KIND=pkcs11`.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SPB_PKCS11_MODULE_PATH` | Caminho para a biblioteca do módulo PKCS#11. | — | Se `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | Rótulo do token PKCS#11. | — | Se `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Caminho para um arquivo que contém o PIN do token. Sensível. | — | Se `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Rótulo da chave SFN no token. | — | Se `pkcs11` |

### Custódia KMIP

Obrigatório quando `SPB_SIGNER_KIND=kmip` (KMIP sobre HTTP para um HSM de rede).

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `SPB_KMIP_BASE_URL` | URL base do serviço KMIP. | — | Se `kmip` |
| `SPB_KMIP_CA_FILE` | Caminho de um pacote PEM com a autoridade certificadora privada de um HSM. O serviço o adiciona às raízes do sistema e mantém a verificação TLS ligada. O serviço se recusa a iniciar quando o arquivo não existe ou não contém nenhum certificado PEM. | — | Não |
| `SPB_KMIP_VHSM` | Identificador do HSM virtual. | — | Se `kmip` |
| `SPB_KMIP_CRYPTO_USER` | Usuário de criptografia do KMIP. | — | Se `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | Token de usuário de criptografia do KMIP. Sensível. | — | Se `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID da chave privada SFN. Na inicialização, o serviço assina um digest de teste com ela, e, em produção e staging, uma chave que não consegue assinar impede o serviço de iniciar. | — | Se `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID da chave pública SFN. | — | Se `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID da chave de descriptografia usada no caminho de descriptografia de entrada. Quando não definido, o serviço usa `SPB_KMIP_SIGN_PRIVATE_KEY_UID`. | — | Não |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Adiciona o prefixo ASN.1 DigestInfo antes da chamada de assinatura do KMIP. Em produção e staging, um valor que faz a assinatura de teste da inicialização falhar impede o serviço de iniciar. | `false` | Não |

## Eventos e outbox

O Lerian SPB registra toda mensagem antes do envio e publica eventos de ciclo de vida para o broker de streaming por meio de um outbox transacional. O streaming não tem modo desabilitado. Defina as configurações compartilhadas `STREAMING_*` conforme descrito em [Streaming e outbox](https://docs.lerian.studio/pt/reference/byoc-configuration.md#streaming-and-outbox). O serviço se recusa a iniciar quando `STREAMING_EVENT_POLICIES` desliga um evento do SPB que não seja `str.message.submitted`, `str.approval.signed`, `str.approval.quorumReached`, `str.reconciliation.opened`, `str.reconciliation.resolved`, `str.certificate.rotated` ou `str.certificate.expiring`.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STREAMING_BROKERS` | Endereços do broker para a publicação de eventos. O serviço se recusa a iniciar quando o valor está ausente ou é inválido. | — | Sim |
| `STREAMING_CLOUDEVENTS_SOURCE` | Identidade de origem do CloudEvents. Deve ser exatamente `br-spb`. Um valor diferente impede a inicialização; o serviço deriva os tópicos do broker a partir dele. | — | Sim |
| `EMISSION_REQUIRED` | Quando `true`, o bootstrap falha de forma fechada a menos que a emissão de eventos esteja totalmente configurada. | `false` | Não |
| `OUTBOX_DISPATCH_INTERVAL` | Intervalo entre ciclos de envio do outbox (duração Go). | `2s` | Não |
| `OUTBOX_BATCH_SIZE` | Linhas processadas por ciclo de envio. | `50` | Não |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Backoff máximo entre novas tentativas de envio (duração Go). | `30m` | Não |
| `LDL_ADVISORY_CONSUMER_ENABLED` | Consome os avisos de liquidação OT do SILOC. Defina-a como `true` ou `false`; o serviço se recusa a iniciar quando ela não está definida. Quando habilitado, exige `STREAMING_BROKERS` e persistência durável, e se recusa a iniciar sem eles. O tópico e o grupo do consumidor são fixos no serviço; nenhum dos dois é configurável pelo ambiente. A conexão com o broker vem das configurações compartilhadas `STREAMING_*` (veja [Streaming e outbox](https://docs.lerian.studio/pt/reference/byoc-configuration.md#streaming-and-outbox)). Quando desabilitado, sua verificação de prontidão reporta `skipped`. | — | Sim |

## Aprovação (maker-checker)

Aprovação opcional por faixa de valor que controla a emissão STR. Desativada por padrão. As faixas e as regras por tipo que um operador armazena pela API de governança têm precedência sobre `APPROVAL_ALCADA_BANDS`.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `APPROVAL_ALCADA_BANDS` | Tabela de faixas inicial: faixas `maxExclusive:requiredSignatures` separadas por ponto e vírgula (por exemplo, `10000.00:1;100000.00:2`). Vazio mantém a aprovação desativada até que um operador defina faixas ou regras por tipo pela API de governança. | — | Não |
| `APPROVAL_DEADLINE_WINDOW` | Por quanto tempo uma emissão estacionada pode esperar (duração Go). A espera termina no máximo à próxima meia-noite de Brasília. | — | Não |
| `APPROVAL_EXPIRY_ENABLED` | Executa a varredura em segundo plano que expira emissões estacionadas vencidas. | `true` | Não |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Intervalo da varredura (duração Go). | `1m` | Não |

## Rate limiting e idempotência

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `RATE_LIMIT_IP_MAX` | Número máximo de requisições por IP por janela. | `300` | Não |
| `RATE_LIMIT_IP_WINDOW` | Janela de rate limit por IP (duração Go). | `1m` | Não |
| `RATE_LIMIT_KEY_MAX` | Número máximo de requisições por chave de API por janela. | `100` | Não |
| `RATE_LIMIT_KEY_WINDOW` | Janela de rate limit por chave (duração Go). | `1m` | Não |
| `IDEMPOTENCY_ENABLED` | Habilita a deduplicação por chave de idempotência. Produção e staging recusam `false`. | `true` | Não |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | Por quanto tempo (em segundos) o trilho guarda a resposta em cache de uma chave de idempotência. | `86400` | Não |

## Systemplane e configuração de runtime

O Lerian SPB monta a API administrativa de configuração de runtime do systemplane em `/v1/system` na porta principal. O PostgreSQL dá suporte a esse plano, para que os operadores possam ler e alterar configurações com hot reload sem reiniciar o serviço. Veja [Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md) para a API, os namespaces e as permissões.

As origens CORS, os quatro valores de rate limit e os dois valores de envio do outbox aceitam hot reload. Para essas configurações, a variável define o valor inicial, e um valor armazenado no Systemplane tem precedência.

## Criptografia e segredos

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Chave AES-256 em base64 para criptografia em repouso dos payloads STR armazenados. Sensível. Obrigatória em produção/staging. | — | Em produção/staging |

> [!WARNING]
>
> Nunca faça commit nem registre em log os valores de nenhuma variável marcada como *Sensível* (senhas, tokens, PINs e chaves AES). Injete-os no momento do deploy por meio do seu gerenciador de segredos.

## Observabilidade

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Habilita tracing e métricas do OpenTelemetry. | `false` | Em produção/staging |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint do coletor OTLP. Deve usar `https://` em produção/staging. | `http://localhost:4318` | Se telemetria habilitada |
| `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. Vincula ao loopback por padrão. | `127.0.0.1:9090` | Não |

## Apenas desenvolvimento

> [!WARNING]
>
> Mantenha essas variáveis não definidas fora do desenvolvimento local. Elas ampliam a superfície de ataque, e produção ou staging as rejeita ou as força a desativar.

| Variável | Descrição | Padrão | Obrigatório |
| - | - | - | - |
| `ENABLE_DEV_DEBUG_ROUTES` | Expõe rotas de depuração. Proibido em produção/staging. | `false` | Não |
| `DEV_DEBUG_TOKEN` | Token que protege as rotas de depuração. Sensível. Obrigatório quando as rotas de depuração estão habilitadas. | — | Se debug habilitado |
| `SWAGGER_ENABLED` | Serve a especificação OpenAPI e a interface de documentação da API. Forçado a desativado em produção e staging. | `false` | Não |
| `STR_MQ_MOCK` | Roteia o transporte STR para um mock em vez de um queue manager real. | `false` | Não |
| `STR_MQ_MOCK_HOST` | Host do mock STR. Obrigatório quando `STR_MQ_MOCK=true`. | `http://localhost:8080` | Se mock habilitado |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Allowlist de hosts que o transporte mock pode acessar. | — | Não |
| `ALLOW_MOCK_TRANSPORT` | Permite que o serviço inicie em `develop` sem o certificado público do BACEN e sem a chave SFN. Recusado fora de `develop` e com um `STR_MQ_HOST` real. | `false` | Não |

## Health e readiness

O Lerian SPB expõe `GET /health` (liveness) e `GET /readyz` (readiness) na porta HTTP principal. Veja [Health and readiness](https://docs.lerian.studio/pt/reference/health-and-readiness.md) para o contrato de probes.

A resposta de `/readyz` inclui uma verificação `license`. Com `LICENSE_KEY`, a verificação não faz nenhuma chamada e aparece como no ar. Uma licença que deixa de ser válida após a inicialização não leva `/readyz` a 503.

As verificações `certificates`, `bacen-public-certificate`, `ibm-mq` e `ldl-advisory-consumer` reportam sem fazer `/readyz` falhar, então um serviço em execução continua em rotação. A verificação `certificates` aparece como fora do ar quando o certificado SFN está expirado ou ainda não é válido, ou quando a custódia não responde. A verificação `bacen-public-certificate` aparece como fora do ar quando o certificado público do BACEN tem um problema. Um signer ausente ainda faz `/readyz` falhar. Crie alertas sobre essas verificações, porque `/readyz` sozinho não sinaliza um certificado expirado.


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