Variáveis de ambiente

O Lerian BC Correios lê sua configuração a partir do ambiente do processo na inicialização. Você define essas variáveis no momento do deploy. Um restart do serviço as torna efetivas. A referência de configuração do BYOC documenta a base que todo serviço Go da Lerian compartilha. Para instalar ou atualizar o Lerian BC Correios, consulte o README do chart do Lerian BC Correios. Nas tabelas abaixo, a coluna Padrão / Obrigatório mostra o valor que o serviço aplica quando você deixa a variável sem definir. Um qualificador em negrito marca uma variável que você deve definir, como Obrigatório ou Obrigatório fora de desenvolvimento. “Fora de desenvolvimento” significa um ENV_NAME diferente de development. — significa que o serviço não aplica nenhum padrão. Uma variável marcada com Sensitive. carrega material de credencial ou de chave. Injete-a a partir do seu gerenciador de segredos no momento do deploy. Nunca faça commit de um valor.

Quando um valor no arquivo de exemplo publicado difere do valor que o código aplica, esta página publica o valor do código.

Serviço e runtime

Variável	Padrão / Obrigatório	Descrição
`ENV_NAME`	`development`	Ambiente de deploy. Qualquer valor diferente de `development` ativa as verificações de inicialização mais rígidas desta página. Com `production`, o serviço recusa `LOG_LEVEL=debug`.
`DEPLOYMENT_MODE`	`local`	Postura operacional: `local`, `byoc` ou `saas`. Em `saas`, cada dependência configurada deve usar TLS. Outro valor interrompe o boot.
`APP_NAME`	`br-correios`	Nome da aplicação.
`LOG_LEVEL`	`info`	Nível de log: `debug`, `info`, `warn` ou `error`.
`SERVER_PORT`	`8080`	Porta HTTP de escuta, de 1 a 65535.
`SERVER_READ_TIMEOUT_SEC`	`30`	Timeout de leitura HTTP, em segundos.
`SERVER_WRITE_TIMEOUT_SEC`	`30`	Timeout de escrita HTTP, em segundos.
`SERVER_SHUTDOWN_TIMEOUT_SEC`	`30`	Tempo que o serviço aguarda as requisições abertas no desligamento, em segundos.
`DEFAULT_TENANT_ID`	`00000000-0000-0000-0000-000000000001`	Tenant de um token sem claim de tenant, no modo single-tenant. Aceita um UUID.
`STREAMING_CLOUDEVENTS_SOURCE`	`—`	Deixe sem definir ou defina exatamente como `br-correios`. Outro valor interrompe o boot.

Licença

Variável	Padrão / Obrigatório	Descrição
`LICENSE_KEY`	Obrigatório	Credencial de licença emitida pela Lerian. Todo ambiente precisa dela. `Sensitive.`
`ORGANIZATION_IDS`	`global`	Escopo de organização que a licença cobre.
`READYZ_LICENSE_TIMEOUT_SECONDS`	`5`	Tempo máximo da verificação de licença no `/readyz`, em segundos.

CORS e proxies

Variável	Padrão / Obrigatório	Descrição
`ALLOWED_ORIGINS`	`` em desenvolvimento. Obrigatório fora de desenvolvimento*	Lista separada por vírgulas das origens de navegador permitidas. Fora de desenvolvimento, o serviço recusa `*`.
`TRUSTED_PROXIES`	`127.0.0.1,::1`	Lista separada por vírgulas dos endereços de proxy cujo header `X-Forwarded-For` o serviço aceita como confiável.

PostgreSQL

Variável	Padrão / Obrigatório	Descrição
`POSTGRES_HOST`	`localhost`	Host do banco de dados.
`POSTGRES_PORT`	`5432`	Porta do banco de dados.
`POSTGRES_USER`	Obrigatório fora de desenvolvimento	Usuário do banco de dados.
`POSTGRES_PASSWORD`	`—`	Senha do banco de dados. `Sensitive.`
`POSTGRES_NAME`	Obrigatório fora de desenvolvimento	Nome do banco de dados.
`POSTGRES_SSLMODE`	`disable`	Modo TLS do banco de dados. Fora de desenvolvimento, o serviço recusa `disable`.
`POSTGRES_MAX_CONNS`	`50`	Máximo de conexões no pool.
`POSTGRES_MIN_CONNS`	`5`	Mínimo de conexões no pool.

Cache (Valkey)

O cache guarda as chaves de idempotência, os contadores de rate limit, a cota compartilhada de requisições ao BACEN e a cota de download de anexos.

Variável	Padrão / Obrigatório	Descrição
`CACHE_ADDR`	`localhost:6379`	Endereço do cache como `host:port`.
`CACHE_PASSWORD`	`—`	Senha do cache. `Sensitive.`
`CACHE_DB`	`0`	Número do banco de dados lógico do cache.
`CACHE_TLS`	`false`	Usa TLS na conexão com o cache.
`CACHE_CA_CERT`	`—`	Certificado de CA personalizado para a conexão TLS com o cache, em PEM ou PEM codificado em base64. Sem ele, o serviço usa o repositório de confiança do sistema.
`CACHE_TTL_SEC`	`60`	Tempo que o serviço mantém as configurações do tenant no cache, em segundos.
`CACHE_POOL_SIZE`	`10`	Tamanho do pool de conexões do cache.
`CACHE_MAX_ACTIVE_CONNS`	`20`	Máximo de conexões ativas com o cache.

RabbitMQ (pipeline de auditoria)

Variável	Padrão / Obrigatório	Descrição
`RABBITMQ_URL`	`amqp://guest:guest@localhost:5672/`	URL do broker. Fora de desenvolvimento, o serviço recusa as credenciais `guest:guest`, e uma falha de conexão interrompe o boot. `Sensitive.`

Criptografia e idempotência

Variável	Padrão / Obrigatório	Descrição
`ENCRYPTION_KEY`	Obrigatório fora de desenvolvimento	Chave AES-256-GCM das credenciais do BC Correio armazenadas, das chaves de API de IA e das respostas de idempotência. Exatamente 32 bytes. `Sensitive.`
`AMQP_SIGNING_KEY`	Derivada de `ENCRYPTION_KEY`	Chave que assina as mensagens de auditoria no RabbitMQ. Quando definida, tem exatamente 32 bytes e é diferente de `ENCRYPTION_KEY`. `Sensitive.`
`IDEMPOTENCY_TTL_SEC`	`86400`	Tempo que o serviço guarda uma chave `X-Idempotency`, em segundos, de 90 a 86400.

Conexão com o BC Correio

Variável	Padrão / Obrigatório	Descrição
`BC_CORREIO_ENVIRONMENT`	`—`	Ambiente do BACEN: `homologation` ou `production`. Ele seleciona o host do BC Correio.
`BC_CORREIO_ENDPOINT_URL`	A partir de `BC_CORREIO_ENVIRONMENT`	URL completa do endpoint do BC Correio. Quando definida, tem precedência sobre `BC_CORREIO_ENVIRONMENT`.
`BC_CORREIO_TLS_MIN_VERSION`	`TLSv1.2`	Versão mínima de TLS para o BC Correio.
`BC_CORREIO_CONNECT_TIMEOUT_SEC`	`30`	Timeout de uma chamada ao BC Correio, em segundos, de 1 a 300.
`BC_CORREIO_RATE_LIMIT_PER_MINUTE`	`50`	Máximo de chamadas ao BC Correio por minuto para cada credencial Sisbacen, de 1 a 60.
`BC_CORREIO_RATE_LIMIT_PER_HOUR`	`2700`	Máximo de chamadas ao BC Correio por hora para cada credencial Sisbacen, de 1 a 3000.
`BC_CORREIO_RATE_LIMIT_MAX_WAIT_SEC`	`90`	Espera máxima de uma chamada por uma vaga livre na cota, em segundos, de 1 a 300.

Armazenamento de objetos

Variável	Padrão / Obrigatório	Descrição
`OBJECT_STORAGE_PROVIDER`	`s3`	Armazenamento de anexos: `s3` para armazenamento de objetos compatível com S3, ou `local` para o sistema de arquivos local.
`OBJECT_STORAGE_ENDPOINT`	`—`	URL do endpoint compatível com S3.
`OBJECT_STORAGE_REGION`	`us-east-1`	Região do armazenamento.
`OBJECT_STORAGE_BUCKET`	`bc-correios-attachments`	Bucket dos anexos.
`OBJECT_STORAGE_ACCESS_KEY`	`—`	Chave de acesso do armazenamento. `Sensitive.`
`OBJECT_STORAGE_SECRET_KEY`	`—`	Chave secreta do armazenamento. `Sensitive.`
`OBJECT_STORAGE_PATH_STYLE`	`false`	Usa endereços S3 path-style.
`OBJECT_STORAGE_LOCAL_PATH`	`/data/bc-correios/storage`	Diretório base do provedor `local`.

Multi-tenancy

Variável	Padrão / Obrigatório	Descrição
`MULTI_TENANT_ENABLED`	`false`	Ativa o modo multi-tenant. Exige `PLUGIN_AUTH_ENABLED=true` e um `ENV_NAME` igual a `staging` ou `production`.
`MULTI_TENANT_URL`	Obrigatório no modo multi-tenant	URL do Tenant Manager. Deve usar `https://`, a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` seja `true`.
`MULTI_TENANT_SERVICE_API_KEY`	Obrigatório no modo multi-tenant	Chave de API do Tenant Manager. `Sensitive.`
`MULTI_TENANT_REDIS_HOST`	Obrigatório no modo multi-tenant	Host do Redis que transporta os eventos de tenant.
`MULTI_TENANT_REDIS_PORT`	`6379`	Porta do Redis de eventos de tenant.
`MULTI_TENANT_REDIS_PASSWORD`	`—`	Senha do Redis de eventos de tenant. `Sensitive.`
`MULTI_TENANT_REDIS_TLS`	`false`	Usa TLS no Redis de eventos de tenant.
`MULTI_TENANT_REDIS_CA_CERT`	`—`	Certificado de CA personalizado para o Redis de eventos de tenant, em PEM ou PEM codificado em base64.
`MULTI_TENANT_EVENT_CHANNEL`	Obrigatório no modo multi-tenant	Canal Redis dos eventos de tenant.
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	`5`	Falhas antes que o circuit breaker do Tenant Manager abra.
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	`30`	Tempo até o circuit breaker do Tenant Manager tentar de novo, em segundos.
`MULTI_TENANT_MAX_TENANT_POOLS`	`100`	Número máximo de pools de banco de dados de tenant.
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	`300`	Tempo ocioso até o serviço fechar um pool de tenant, em segundos.
`MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`	`30`	Intervalo entre as verificações de conexões ociosas de tenant, em segundos.
`MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT`	`0`	Máximo de conexões abertas em cada pool de tenant. `0` mantém o padrão da biblioteca.
`MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT`	`0`	Máximo de conexões ociosas em cada pool de tenant. `0` mantém o padrão da biblioteca.
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	`false`	Permite endereços `http://` para o Tenant Manager e o Access Manager no modo multi-tenant.
`STREAMING_OUTBOX_MULTI_TENANT_ENABLED`	`false`	Deve ser `true` quando `MULTI_TENANT_ENABLED` é `true`, ou o serviço não inicia.

IA

Variável	Padrão / Obrigatório	Descrição
`FEATURE_AI_INSIGHTS_ENABLED`	`true`	Ativa ou desativa a análise de correspondências por IA.
`AI_DEFAULT_MODEL_OPENAI`	`gpt-4o-mini`	Modelo de um tenant que usa `openai` e não define modelo.
`AI_DEFAULT_MODEL_ANTHROPIC`	`claude-sonnet-4-20250514`	Modelo de um tenant que usa `anthropic` e não define modelo.
`AI_DEFAULT_MODEL_GEMINI`	`gemini-2.0-flash`	Modelo de um tenant que usa `gemini` e não define modelo.
`AI_DEFAULT_SYSTEM_PROMPT`	Prompt embutido	System prompt padrão da análise por IA.
`AI_TENANT_RATE_LIMIT_PER_MIN`	`50`	Máximo de chamadas de IA por minuto para cada tenant.
`AI_CIRCUIT_BREAKER_THRESHOLD`	`5`	Falhas seguidas antes que o circuit breaker de IA de um tenant e provedor abra.
`AI_CIRCUIT_BREAKER_HALF_OPEN_SEC`	`30`	Tempo até um circuit breaker de IA aberto tentar uma chamada de novo, em segundos.
`AI_TENANT_MAX_CONCURRENT`	`3`	Máximo de chamadas de IA simultâneas para cada tenant.
`AI_GLOBAL_MAX_CONCURRENT`	`15`	Máximo de chamadas de IA simultâneas para a instância inteira.
`AI_ACQUIRE_TIMEOUT_SEC`	`30`	Espera máxima de uma chamada de IA em segundo plano por uma vaga livre, em segundos.
`AI_HTTP_ACQUIRE_TIMEOUT_SEC`	`5`	Espera máxima de uma requisição de reanálise por uma vaga livre, em segundos. Depois dela, a requisição responde `202`.
`AI_INLINE_PROVIDER_TIMEOUT_SEC`	`15`	Timeout de uma chamada de IA durante o ciclo de polling, em segundos.
`AI_BODY_INLINE_THRESHOLD`	`200`	Tamanho mínimo do corpo, em caracteres, para uma análise durante o ciclo de polling.

Transmissão

Variável	Padrão / Obrigatório	Descrição
`TRANSMISSION_PENDING_GRACE_SEC`	`30`	Janela de tolerância de um envio `PENDING`, em segundos, de 5 a 300. Quando uma repetição encontra um envio `PENDING` mais antigo que ela, o envio passa a `AMBIGUOUS`.
`TRANSMISSION_RETRY_MAX_ATTEMPTS`	`3`	Tentativas de registrar um envio que o BC Correio aceitou, de 1 a 10.
`TRANSMISSION_METRICS_QUERY_TIMEOUT_SEC`	`2`	Tempo máximo da consulta ao banco de dados por trás da métrica de envios pendentes, em segundos, de 1 a 8.

Auditoria

Variável	Padrão / Obrigatório	Descrição
`FEATURE_AUDIT_ENABLED`	`true`	Ativa ou desativa o pipeline de auditoria. Fora de desenvolvimento, o serviço recusa `false`.
`AUDIT_OUTBOX_POLL_INTERVAL_SEC`	`2`	Intervalo entre as leituras do outbox de auditoria, em segundos, de 1 a 300.
`AUDIT_OUTBOX_BATCH_LIMIT`	`50`	Máximo de eventos de auditoria em uma leitura para cada tenant, de 1 a 1000.
`AUDIT_OUTBOX_MAX_ATTEMPTS`	`50`	Tentativas de publicar um evento de auditoria, de 1 a 1000.
`AUDIT_OUTBOX_RETENTION_DAYS`	`7`	Dias até o serviço excluir uma linha publicada do outbox, de 1 a 90.

Autenticação

Variável	Padrão / Obrigatório	Descrição
`PLUGIN_AUTH_ENABLED`	Obrigatório	`true` ou `false`. Um valor em branco interrompe o boot. `false` exige um `ENV_NAME` igual a `development`, `develop`, `dev`, `local` ou `test`, e nunca funciona com `DEPLOYMENT_MODE=saas`. Com `false`, as requisições ainda precisam de um bearer token.
`PLUGIN_AUTH_ADDRESS`	Obrigatório quando `PLUGIN_AUTH_ENABLED` é `true`	Endereço do Lerian Access Manager. No modo multi-tenant, deve usar `https://`, a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` seja `true`.

Telemetria e métricas

Variável	Padrão / Obrigatório	Descrição
`TRACING_ENABLED`	`false`	Exporta traces por OTLP.
`METRICS_ENABLED`	`false`	Exporta métricas por OTLP.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`—`	Endpoint do coletor OTLP.
`OTEL_SERVICE_NAME`	`br-correios`	Nome do serviço na telemetria.
`OTEL_LIBRARY_NAME`	`br-correios`	Nome da biblioteca de instrumentação na telemetria.
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Valor de `ENV_NAME`	Ambiente de deploy na telemetria.
`METRICS_PROMETHEUS_ENABLED`	`false`	Abre um listener separado para o scrape do Prometheus.
`METRICS_PROMETHEUS_ADDRESS`	`127.0.0.1:9076`	Endereço do listener do Prometheus.

Rate limits

Variável	Padrão / Obrigatório	Descrição
`RATE_LIMIT_ENABLED`	`false`	Ativa as cotas de requisições por tenant e operação.
`RATE_LIMIT_REDIS_TIMEOUT_MS`	`500`	Timeout de uma chamada de contador de rate limit ao cache, em milissegundos.
`ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN`	`500`	Cota de download de anexos por tenant, em megabytes por minuto, de 1 a 102400.

​Serviço e runtime

​Licença

​CORS e proxies

​PostgreSQL

​Cache (Valkey)

​RabbitMQ (pipeline de auditoria)

​Criptografia e idempotência

​Conexão com o BC Correio

​Armazenamento de objetos

​Multi-tenancy

​IA

​Transmissão

​Auditoria

​Autenticação

​Telemetria e métricas

​Rate limits

Serviço e runtime

Licença

CORS e proxies

PostgreSQL

Cache (Valkey)

RabbitMQ (pipeline de auditoria)

Criptografia e idempotência

Conexão com o BC Correio

Armazenamento de objetos

Multi-tenancy

IA

Transmissão

Auditoria

Autenticação

Telemetria e métricas

Rate limits