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

# Variables de entorno

> Variables de entorno en tiempo de despliegue para Lerian BC Correios: postura de runtime, almacenes de datos, la conexión con BC Correio, claves de cifrado, IA y configuración de auditoría.

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](/es/reference/byoc-configuration) 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](https://github.com/LerianStudio/helm/tree/main/charts/plugin-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.

<Note>
  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.
</Note>

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


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