Variables de entorno

Lerian BC Correios lee su configuración del entorno del proceso al arrancar. Configuras estas variables en tiempo de despliegue. Un reinicio del servicio hace que tomen efecto. Fundamentos de configuración de BYOC documenta la base común que comparte todo servicio Go de Lerian. Para instalar o actualizar Lerian BC Correios, consulta el README del chart de Lerian BC Correios. En las tablas siguientes, la columna Predeterminado / Obligatorio muestra el valor que aplica el servicio cuando dejas la variable sin definir. Un calificador en negrita marca una variable que debes configurar, como Obligatorio u Obligatorio fuera de desarrollo. “Fuera de desarrollo” significa un ENV_NAME diferente de development. — significa que el servicio no aplica ningún valor predeterminado. Una variable marcada con Sensitive. lleva material de credenciales o claves. Inyéctala desde tu gestor de secretos en tiempo de despliegue. Nunca hagas commit de un valor.

Cuando un valor del archivo de ejemplo publicado difiere del valor que aplica el código, esta página publica el valor del código.

Servicio y runtime

Variable	Predeterminado / Obligatorio	Descripción
`ENV_NAME`	`development`	Entorno de despliegue. Cualquier valor diferente de `development` activa las verificaciones de arranque más estrictas de esta página. Con `production`, el servicio rechaza `LOG_LEVEL=debug`.
`DEPLOYMENT_MODE`	`local`	Postura operativa: `local`, `byoc` o `saas`. En `saas`, cada dependencia configurada debe usar TLS. Otro valor detiene el arranque.
`APP_NAME`	`br-correios`	Nombre de la aplicación.
`LOG_LEVEL`	`info`	Nivel de log: `debug`, `info`, `warn` o `error`.
`SERVER_PORT`	`8080`	Puerto de escucha HTTP, de 1 a 65535.
`SERVER_READ_TIMEOUT_SEC`	`30`	Timeout de lectura HTTP, en segundos.
`SERVER_WRITE_TIMEOUT_SEC`	`30`	Timeout de escritura HTTP, en segundos.
`SERVER_SHUTDOWN_TIMEOUT_SEC`	`30`	Tiempo que el servicio espera las solicitudes abiertas al apagarse, en segundos.
`DEFAULT_TENANT_ID`	`00000000-0000-0000-0000-000000000001`	Tenant de un token sin claim de tenant, en modo single-tenant. Acepta un UUID.
`STREAMING_CLOUDEVENTS_SOURCE`	`—`	Déjala sin definir, o defínela exactamente como `br-correios`. Otro valor detiene el arranque.

Licencia

Variable	Predeterminado / Obligatorio	Descripción
`LICENSE_KEY`	Obligatorio	Credencial de licencia emitida por Lerian. Cada entorno la necesita. `Sensitive.`
`ORGANIZATION_IDS`	`global`	Ámbito de organización que cubre la licencia.
`READYZ_LICENSE_TIMEOUT_SECONDS`	`5`	Tiempo máximo de la verificación de licencia en `/readyz`, en segundos.

CORS y proxies

Variable	Predeterminado / Obligatorio	Descripción
`ALLOWED_ORIGINS`	`` en desarrollo. Obligatorio fuera de desarrollo*	Lista separada por comas de los orígenes de navegador permitidos. Fuera de desarrollo, el servicio rechaza `*`.
`TRUSTED_PROXIES`	`127.0.0.1,::1`	Lista separada por comas de las direcciones de proxy en cuyo header `X-Forwarded-For` confía el servicio.

PostgreSQL

Variable	Predeterminado / Obligatorio	Descripción
`POSTGRES_HOST`	`localhost`	Host de la base de datos.
`POSTGRES_PORT`	`5432`	Puerto de la base de datos.
`POSTGRES_USER`	Obligatorio fuera de desarrollo	Usuario de la base de datos.
`POSTGRES_PASSWORD`	`—`	Contraseña de la base de datos. `Sensitive.`
`POSTGRES_NAME`	Obligatorio fuera de desarrollo	Nombre de la base de datos.
`POSTGRES_SSLMODE`	`disable`	Modo TLS de la base de datos. Fuera de desarrollo, el servicio rechaza `disable`.
`POSTGRES_MAX_CONNS`	`50`	Máximo de conexiones del pool.
`POSTGRES_MIN_CONNS`	`5`	Mínimo de conexiones del pool.

Cache (Valkey)

La cache guarda las claves de idempotencia, los contadores de rate limit, la cuota compartida de solicitudes a BACEN y el presupuesto de descarga de adjuntos.

Variable	Predeterminado / Obligatorio	Descripción
`CACHE_ADDR`	`localhost:6379`	Dirección de la cache como `host:port`.
`CACHE_PASSWORD`	`—`	Contraseña de la cache. `Sensitive.`
`CACHE_DB`	`0`	Número de la base de datos lógica de la cache.
`CACHE_TLS`	`false`	Usa TLS en la conexión con la cache.
`CACHE_CA_CERT`	`—`	Certificado de CA personalizado para la conexión TLS con la cache, como PEM o PEM codificado en base64. Sin él, el servicio usa el almacén de confianza del sistema.
`CACHE_TTL_SEC`	`60`	Tiempo que el servicio conserva la configuración del tenant en la cache, en segundos.
`CACHE_POOL_SIZE`	`10`	Tamaño del pool de conexiones de la cache.
`CACHE_MAX_ACTIVE_CONNS`	`20`	Máximo de conexiones activas con la cache.

RabbitMQ (pipeline de auditoría)

Variable	Predeterminado / Obligatorio	Descripción
`RABBITMQ_URL`	`amqp://guest:guest@localhost:5672/`	URL del broker. Fuera de desarrollo, el servicio rechaza las credenciales `guest:guest`, y una conexión fallida detiene el arranque. `Sensitive.`

Cifrado e idempotencia

Variable	Predeterminado / Obligatorio	Descripción
`ENCRYPTION_KEY`	Obligatorio fuera de desarrollo	Clave AES-256-GCM para las credenciales de BC Correio almacenadas, las claves de API de IA y las respuestas de idempotencia. Exactamente 32 bytes. `Sensitive.`
`AMQP_SIGNING_KEY`	Derivada de `ENCRYPTION_KEY`	Clave que firma los mensajes de auditoría en RabbitMQ. Cuando se define, exactamente 32 bytes y diferente de `ENCRYPTION_KEY`. `Sensitive.`
`IDEMPOTENCY_TTL_SEC`	`86400`	Tiempo que el servicio conserva una clave `X-Idempotency`, en segundos, de 90 a 86400.

Conexión con BC Correio

Variable	Predeterminado / Obligatorio	Descripción
`BC_CORREIO_ENVIRONMENT`	`—`	Entorno de BACEN: `homologation` o `production`. Selecciona el host de BC Correio.
`BC_CORREIO_ENDPOINT_URL`	Según `BC_CORREIO_ENVIRONMENT`	URL completa del endpoint de BC Correio. Cuando se define, tiene prioridad sobre `BC_CORREIO_ENVIRONMENT`.
`BC_CORREIO_TLS_MIN_VERSION`	`TLSv1.2`	Versión mínima de TLS para BC Correio.
`BC_CORREIO_CONNECT_TIMEOUT_SEC`	`30`	Timeout de una llamada a BC Correio, en segundos, de 1 a 300.
`BC_CORREIO_RATE_LIMIT_PER_MINUTE`	`50`	Máximo de llamadas a BC Correio por minuto para cada credencial Sisbacen, de 1 a 60.
`BC_CORREIO_RATE_LIMIT_PER_HOUR`	`2700`	Máximo de llamadas a BC Correio por hora para cada credencial Sisbacen, de 1 a 3000.
`BC_CORREIO_RATE_LIMIT_MAX_WAIT_SEC`	`90`	Espera máxima de una llamada por un espacio libre de la cuota, en segundos, de 1 a 300.

Almacenamiento de objetos

Variable	Predeterminado / Obligatorio	Descripción
`OBJECT_STORAGE_PROVIDER`	`s3`	Almacenamiento de adjuntos: `s3` para un almacenamiento de objetos compatible con S3, o `local` para el sistema de archivos local.
`OBJECT_STORAGE_ENDPOINT`	`—`	URL del endpoint compatible con S3.
`OBJECT_STORAGE_REGION`	`us-east-1`	Región del almacenamiento.
`OBJECT_STORAGE_BUCKET`	`bc-correios-attachments`	Bucket de los adjuntos.
`OBJECT_STORAGE_ACCESS_KEY`	`—`	Clave de acceso del almacenamiento. `Sensitive.`
`OBJECT_STORAGE_SECRET_KEY`	`—`	Clave secreta del almacenamiento. `Sensitive.`
`OBJECT_STORAGE_PATH_STYLE`	`false`	Usa direcciones S3 path-style.
`OBJECT_STORAGE_LOCAL_PATH`	`/data/bc-correios/storage`	Directorio base del proveedor `local`.

Multi-tenancy

Variable	Predeterminado / Obligatorio	Descripción
`MULTI_TENANT_ENABLED`	`false`	Activa el modo multi-tenant. Necesita `PLUGIN_AUTH_ENABLED=true` y un `ENV_NAME` de `staging` o `production`.
`MULTI_TENANT_URL`	Obligatorio en modo multi-tenant	URL del Tenant Manager. Debe usar `https://` a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` sea `true`.
`MULTI_TENANT_SERVICE_API_KEY`	Obligatorio en modo multi-tenant	Clave de API para el Tenant Manager. `Sensitive.`
`MULTI_TENANT_REDIS_HOST`	Obligatorio en modo multi-tenant	Host del Redis que lleva los eventos de tenant.
`MULTI_TENANT_REDIS_PORT`	`6379`	Puerto del Redis de eventos de tenant.
`MULTI_TENANT_REDIS_PASSWORD`	`—`	Contraseña del Redis de eventos de tenant. `Sensitive.`
`MULTI_TENANT_REDIS_TLS`	`false`	Usa TLS para el Redis de eventos de tenant.
`MULTI_TENANT_REDIS_CA_CERT`	`—`	Certificado de CA personalizado para el Redis de eventos de tenant, como PEM o PEM codificado en base64.
`MULTI_TENANT_EVENT_CHANNEL`	Obligatorio en modo multi-tenant	Canal de Redis para los eventos de tenant.
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	`5`	Fallas antes de que se abra el circuit breaker del Tenant Manager.
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	`30`	Tiempo antes de que el circuit breaker del Tenant Manager vuelva a intentarlo, en segundos.
`MULTI_TENANT_MAX_TENANT_POOLS`	`100`	Número máximo de pools de base de datos de tenant.
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	`300`	Tiempo de inactividad antes de que el servicio cierre un pool de tenant, en segundos.
`MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`	`30`	Intervalo entre las verificaciones de las conexiones de tenant inactivas, en segundos.
`MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT`	`0`	Máximo de conexiones abiertas en cada pool de tenant. `0` mantiene el valor predeterminado de la biblioteca.
`MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT`	`0`	Máximo de conexiones inactivas en cada pool de tenant. `0` mantiene el valor predeterminado de la biblioteca.
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	`false`	Permite direcciones `http://` para el Tenant Manager y Access Manager en modo multi-tenant.
`STREAMING_OUTBOX_MULTI_TENANT_ENABLED`	`false`	Debe ser `true` cuando `MULTI_TENANT_ENABLED` es `true`, o el servicio no arranca.

IA

Variable	Predeterminado / Obligatorio	Descripción
`FEATURE_AI_INSIGHTS_ENABLED`	`true`	Activa o desactiva el análisis de correos con IA.
`AI_DEFAULT_MODEL_OPENAI`	`gpt-4o-mini`	Modelo para un tenant que usa `openai` y no define un modelo.
`AI_DEFAULT_MODEL_ANTHROPIC`	`claude-sonnet-4-20250514`	Modelo para un tenant que usa `anthropic` y no define un modelo.
`AI_DEFAULT_MODEL_GEMINI`	`gemini-2.0-flash`	Modelo para un tenant que usa `gemini` y no define un modelo.
`AI_DEFAULT_SYSTEM_PROMPT`	Prompt incorporado	Prompt de sistema predeterminado para el análisis con IA.
`AI_TENANT_RATE_LIMIT_PER_MIN`	`50`	Máximo de llamadas a la IA por minuto para cada tenant.
`AI_CIRCUIT_BREAKER_THRESHOLD`	`5`	Fallas seguidas antes de que se abra el circuit breaker de IA de un tenant y un proveedor.
`AI_CIRCUIT_BREAKER_HALF_OPEN_SEC`	`30`	Tiempo antes de que un circuit breaker de IA abierto vuelva a intentar una llamada, en segundos.
`AI_TENANT_MAX_CONCURRENT`	`3`	Máximo de llamadas a la IA concurrentes para cada tenant.
`AI_GLOBAL_MAX_CONCURRENT`	`15`	Máximo de llamadas a la IA concurrentes para toda la instancia.
`AI_ACQUIRE_TIMEOUT_SEC`	`30`	Espera máxima de una llamada a la IA en segundo plano por un espacio libre, en segundos.
`AI_HTTP_ACQUIRE_TIMEOUT_SEC`	`5`	Espera máxima de una solicitud de nuevo análisis por un espacio libre, en segundos. Después de ella, la solicitud responde `202`.
`AI_INLINE_PROVIDER_TIMEOUT_SEC`	`15`	Timeout de una llamada a la IA durante el ciclo de sondeo, en segundos.
`AI_BODY_INLINE_THRESHOLD`	`200`	Longitud mínima del cuerpo, en caracteres, para un análisis durante el ciclo de sondeo.

Transmisión

Variable	Predeterminado / Obligatorio	Descripción
`TRANSMISSION_PENDING_GRACE_SEC`	`30`	Ventana de gracia de un envío `PENDING`, en segundos, de 5 a 300. Cuando una repetición encuentra un envío `PENDING` más antiguo que este valor, el envío pasa a `AMBIGUOUS`.
`TRANSMISSION_RETRY_MAX_ATTEMPTS`	`3`	Intentos para registrar un envío que BC Correio aceptó, de 1 a 10.
`TRANSMISSION_METRICS_QUERY_TIMEOUT_SEC`	`2`	Tiempo máximo de la consulta a la base de datos detrás de la métrica de envíos pendientes, en segundos, de 1 a 8.

Auditoría

Variable	Predeterminado / Obligatorio	Descripción
`FEATURE_AUDIT_ENABLED`	`true`	Activa o desactiva el pipeline de auditoría. Fuera de desarrollo, el servicio rechaza `false`.
`AUDIT_OUTBOX_POLL_INTERVAL_SEC`	`2`	Intervalo entre las lecturas del outbox de auditoría, en segundos, de 1 a 300.
`AUDIT_OUTBOX_BATCH_LIMIT`	`50`	Máximo de eventos de auditoría en una lectura para cada tenant, de 1 a 1000.
`AUDIT_OUTBOX_MAX_ATTEMPTS`	`50`	Intentos para publicar un evento de auditoría, de 1 a 1000.
`AUDIT_OUTBOX_RETENTION_DAYS`	`7`	Días antes de que el servicio elimine una fila de outbox publicada, de 1 a 90.

Autenticación

Variable	Predeterminado / Obligatorio	Descripción
`PLUGIN_AUTH_ENABLED`	Obligatorio	`true` o `false`. Un valor vacío detiene el arranque. `false` necesita un `ENV_NAME` de `development`, `develop`, `dev`, `local` o `test`, y nunca funciona con `DEPLOYMENT_MODE=saas`. Con `false`, las solicitudes siguen necesitando un bearer token.
`PLUGIN_AUTH_ADDRESS`	Obligatorio cuando `PLUGIN_AUTH_ENABLED` es `true`	Dirección de Lerian Access Manager. En modo multi-tenant, debe usar `https://` a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP` sea `true`.

Telemetría y métricas

Variable	Predeterminado / Obligatorio	Descripción
`TRACING_ENABLED`	`false`	Exporta trazas por OTLP.
`METRICS_ENABLED`	`false`	Exporta métricas por OTLP.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`—`	Endpoint del colector OTLP.
`OTEL_SERVICE_NAME`	`br-correios`	Nombre del servicio en la telemetría.
`OTEL_LIBRARY_NAME`	`br-correios`	Nombre de la biblioteca de instrumentación en la telemetría.
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Valor de `ENV_NAME`	Entorno de despliegue en la telemetría.
`METRICS_PROMETHEUS_ENABLED`	`false`	Abre un listener separado para un scrape de Prometheus.
`METRICS_PROMETHEUS_ADDRESS`	`127.0.0.1:9076`	Dirección del listener de Prometheus.

Rate limits

Variable	Predeterminado / Obligatorio	Descripción
`RATE_LIMIT_ENABLED`	`false`	Activa los presupuestos de solicitudes por tenant y por operación.
`RATE_LIMIT_REDIS_TIMEOUT_MS`	`500`	Timeout de una llamada de contador de rate limit a la cache, en milisegundos.
`ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN`	`500`	Presupuesto de descarga de adjuntos por tenant, en megabytes por minuto, de 1 a 102400.

​Servicio y runtime

​Licencia

​CORS y proxies

​PostgreSQL

​Cache (Valkey)

​RabbitMQ (pipeline de auditoría)

​Cifrado e idempotencia

​Conexión con BC Correio

​Almacenamiento de objetos

​Multi-tenancy

​IA

​Transmisión

​Auditoría

​Autenticación

​Telemetría y métricas

​Rate limits

Servicio y runtime

Licencia

CORS y proxies

PostgreSQL

Cache (Valkey)

RabbitMQ (pipeline de auditoría)

Cifrado e idempotencia

Conexión con BC Correio

Almacenamiento de objetos

Multi-tenancy

IA

Transmisión

Auditoría

Autenticación

Telemetría y métricas

Rate limits