> ## 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 de despliegue para Lerian SPB: runtime, conectividad STR/RSFN, firma de mensajes y certificados, persistencia, eventos y seguridad.
Lerian SPB es la integración de mensajería nativa de Lerian para el STR (Sistema de Transferência de Reservas), que alcanza el sistema de liquidación bruta en tiempo real de BACEN a través de la RSFN. Las variables siguientes se definen en el momento del despliegue y requieren reiniciar el servicio para surtir efecto. La mayoría son específicas de este rail; para los ajustes que se comportan igual en todos los servicios Go de Lerian —postura de despliegue, almacenes de datos, multi-tenancy, telemetría— consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, **Requerida** marca una variable que debe definirse (de forma global o bajo la condición indicada). Un calificador como *En producción* o *Si está habilitada* precisa cuándo se aplica el requisito. `—` significa que no hay valor por defecto.
Lerian SPB activa sus controles de seguridad más estrictos a partir de `ENV_NAME`: cuando se define como `production` o `staging`, el TLS pasa a ser obligatorio en Redis, RabbitMQ y la conexión STR, la firma de mensajes debe usar un backend de custodia respaldado por hardware y las superficies exclusivas de desarrollo se rechazan. `ENV_NAME` no tiene valor por defecto: defínelo de forma explícita; el servicio se niega a arrancar si está sin definir o tiene un valor no reconocido.
## Runtime y servidor
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | --------- |
| `ENV_NAME` | Entorno de runtime. Debe ser uno de `production`, `staging` o `develop`. `production` y `staging` activan los controles de seguridad descritos arriba. | — | Sí |
| `SERVICE_NAME` | Identificador del servicio usado en los logs y la telemetría. | Valor por defecto del servicio | No |
| `LOG_LEVEL` | Verbosidad de los logs (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_PORT` | Puerto de escucha HTTP. Las superficies de liveness, readiness y systemplane se enlazan a este mismo puerto. | `3000` | No |
| `CORS_ALLOWED_ORIGINS` | Orígenes CORS permitidos, separados por comas. En producción/staging solo se aceptan orígenes `https://` y se rechazan los orígenes de localhost. | `http://localhost:3000` | No |
| `TRUSTED_PROXIES` | IPs/CIDR de proxy de confianza, separados por comas, autorizados a establecer la IP real del cliente. | — | No |
## Autenticación
Lerian SPB delega la autorización —incluida la API de administración de systemplane— en Access Manager. Consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration#autenticación-de-plugins).
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------- | -------------------------------------------------------------- | ----------------------- | ------------------ |
| `PLUGIN_AUTH_ENABLED` | Exige autenticación de Access Manager en las rutas protegidas. | `true` | No |
| `PLUGIN_AUTH_ADDRESS` | Dirección del servicio Access Manager. | `http://localhost:4000` | Si está habilitada |
## PostgreSQL
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- |
| `POSTGRES_HOST` | Host principal de PostgreSQL. | `localhost` | Sí |
| `POSTGRES_PORT` | Puerto principal de PostgreSQL. | `5432` | No |
| `POSTGRES_USER` | Usuario de la base de datos. | — | Sí |
| `POSTGRES_PASSWORD` | Contraseña de la base de datos. Sensible: inyéctala en el momento del despliegue; nunca la guardes en el repositorio. | — | En producción/staging |
| `POSTGRES_DB` | Nombre de la base de datos. | — | Sí |
| `POSTGRES_SSLMODE` | Modo TLS de libpq. Usa `require` o más estricto en producción. | `require` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas. | `10` | No |
| `POSTGRES_CONN_MAX_LIFETIME` | Vida máxima de la conexión (duración de Go, p. ej. `5m`). | `5m` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Tiempo máximo de inactividad de la conexión (duración de Go). | `2m` | No |
### Réplica de PostgreSQL
Réplica de lectura opcional. Todos los campos recurren a la primaria cuando no se definen.
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------- | ---------------------------------------------- | ----------------- | --------- |
| `POSTGRES_REPLICA_HOST` | Host de la réplica. Sin definir = sin réplica. | — | No |
| `POSTGRES_REPLICA_PORT` | Puerto de la réplica. | — | No |
| `POSTGRES_REPLICA_USER` | Usuario de la réplica. | — | No |
| `POSTGRES_REPLICA_PASSWORD` | Contraseña de la réplica. Sensible. | — | No |
| `POSTGRES_REPLICA_DB` | Nombre de la base de datos de la réplica. | — | No |
| `POSTGRES_REPLICA_SSLMODE` | Modo TLS de la réplica. | — | No |
## Redis
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------- |
| `REDIS_HOST` | Host de Redis. Debe ser explícito y no local en producción/staging. | `localhost` | En producción/staging |
| `REDIS_PORT` | Puerto de Redis. | `6379` | No |
| `REDIS_PASSWORD` | Contraseña de Redis. Sensible. | — | En producción/staging |
| `REDIS_DB` | Número de base de datos de Redis. | `0` | No |
| `REDIS_TLS_ENABLED` | Habilita el TLS hacia Redis. Debe ser `true` en producción/staging. | `false` | En producción/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Certificado CA codificado en Base64 para el TLS de Redis. Requerido cuando `REDIS_TLS_ENABLED=true` en producción/staging. | — | Si TLS está habilitado |
| `REDIS_POOL_SIZE` | Tamaño del pool de conexiones. | `20` | No |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexiones inactivas. | `5` | No |
## Conectividad STR (RSFN)
Lerian SPB intercambia mensajes STR con BACEN a través de la RSFN mediante un transporte IBM MQ. Estas variables definen la identidad del participante, la conexión al gestor de colas y las colas.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ---------------------- |
| `STR_ISPB` | El ISPB de 8 dígitos del participante. En producción/staging debe ser un ISPB real explícito, no `00000000`. | `00000000` | En producción/staging |
| `STR_MQ_HOST` | Host del gestor de colas. | — | Sí (STR en vivo) |
| `STR_MQ_PORT` | Puerto de escucha del gestor de colas. | `1414` | No |
| `STR_MQ_CHANNEL` | Canal de conexión de servidor de MQ. | `DEV.APP.SVRCONN` | No |
| `STR_MQ_QUEUE_MGR` | Nombre del gestor de colas. | `QM1` | No |
| `STR_MQ_USER` | Usuario de la conexión MQ. | — | No |
| `STR_MQ_PASSWORD` | Contraseña de la conexión MQ. Sensible. | — | No |
| `STR_MQ_TLS_ENABLED` | Habilita el TLS mutuo en el canal MQ. Requerido para una conexión STR real. | `false` | En producción/staging |
| `MQSSLKEYR` | Ruta al repositorio de claves GSKit que respalda el TLS de MQ. La clave privada reside aquí, nunca en una variable de entorno. | — | Si TLS está habilitado |
| `STR_MQ_SEND_QUEUE` | Cola de solicitudes salientes. Se deriva de `STR_ISPB` cuando no se define. | Derivada | No |
| `STR_MQ_RESPONSE_QUEUE` | Cola de respuestas. Se deriva de `STR_ISPB` cuando no se define. | Derivada | No |
| `STR_MQ_RECEIVE_QUEUE` | Cola de recepción entrante. Se deriva de `STR_ISPB` cuando no se define. | Derivada | No |
| `MQ_HEARTBEAT_INTERVAL` | Intervalo de heartbeat de MQ (duración de Go). | `300s` | No |
| `MQ_DISCONNECT_INTERVAL` | Intervalo de desconexión de MQ (duración de Go). | `6000s` | No |
| `MQ_SEQ_WRAP` | Techo de reinicio de la secuencia de mensajes para el canal MQ. | `99999999` | No |
| `MQ_ADOPTNEWMCA` | Ajuste `AdoptNewMCA` del canal MQ. | `ALL` | No |
### Circuit breaker
Protege el transporte STR frente a un gestor de colas que falla.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------- | ----------------------------------------------------------------------------- | ----------------- | --------- |
| `CB_MAX_REQUESTS` | Peticiones permitidas mientras el breaker está en estado semiabierto. | `3` | No |
| `CB_INTERVAL` | Ventana móvil en la que se cuentan los fallos (duración de Go). | `30s` | No |
| `CB_TIMEOUT` | Tiempo de recuperación del estado abierto (duración de Go). | `10s` | No |
| `CB_CONSECUTIVE_FAILURES` | Fallos consecutivos antes de que el breaker se dispare. | `5` | No |
| `CB_FAILURE_RATIO` | Proporción de fallos que dispara el breaker (0–1). | `0.5` | No |
| `CB_MIN_REQUESTS` | Mínimo de peticiones en una ventana antes de que el breaker pueda dispararse. | `10` | No |
## Firma de mensajes y certificados
Los mensajes STR se firman digitalmente. Elige un backend de custodia con `SPB_SIGNER_KIND`; producción y staging rechazan el backend de archivo y requieren una clave respaldada por hardware (`pkcs11` o `kmip`).
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `SPB_SIGNER_KIND` | Backend de custodia de firma: `file`, `pkcs11` o `kmip`. `file` es solo para desarrollo/homologación: se rechaza en producción/staging. (`hsm` y `kms` están declarados pero no implementados.) | `file` | No |
| `CERT_BASE_PATH` | Directorio base para el material de certificados. | `/certs` | No |
| `CERT_PATH` | Ruta al certificado de firma. | — | No |
| `KEY_PATH` | Ruta a la clave privada de firma (solo backend de archivo). | — | Si `file` |
| `PROCESS_CERT_PATH` | Ruta al certificado de proceso/TLS. | — | No |
| `PROCESS_PRIVATE_KEY_PATH` | Ruta a la clave privada de proceso/TLS. Sensible. | — | No |
| `BACEN_PUBLIC_CERT_PATH` | Ruta al certificado público de BACEN, usado para verificar las firmas entrantes. | — | No |
| `CERT_READINESS_MIN_DAYS` | Días mínimos hasta la expiración antes de que la comprobación de readiness del certificado informe `degraded`. | `30` | No |
### Custodia PKCS#11
Requerido cuando `SPB_SIGNER_KIND=pkcs11`.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------ | ---------------------------------------------------------- | ----------------- | ----------- |
| `SPB_PKCS11_MODULE_PATH` | Ruta a la biblioteca del módulo PKCS#11. | — | Si `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Ruta a un archivo que contiene el PIN del token. Sensible. | — | Si `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si `pkcs11` |
### Custodia KMIP
Requerido cuando `SPB_SIGNER_KIND=kmip` (KMIP sobre HTTP hacia un HSM de red).
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------- | -------------------------------------------------------------------------- | ----------------- | --------- |
| `SPB_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si `kmip` |
| `SPB_KMIP_VHSM` | Identificador del HSM virtual. | — | Si `kmip` |
| `SPB_KMIP_CRYPTO_USER` | Usuario cripto de KMIP. | — | Si `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | Token del usuario cripto de KMIP. Sensible. | — | Si `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID de la clave de descifrado. | — | Si `kmip` |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP. | `false` | No |
## Eventos, outbox y RabbitMQ
Lerian SPB registra cada mensaje antes de despacharlo y publica eventos de ciclo de vida hacia RabbitMQ a través de un outbox transaccional.
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- |
| `EMISSION_REQUIRED` | Cuando es `true`, el arranque falla de forma cerrada salvo que la emisión de eventos esté completamente cableada. | `false` | No |
| `RABBITMQ_HOST` | Host de RabbitMQ. | — | Sí (eventos) |
| `RABBITMQ_PORT` | Puerto de RabbitMQ. | `5672` | No |
| `RABBITMQ_USER` | Usuario de RabbitMQ. No debe ser el `guest` por defecto en producción/staging. | `guest` | En producción/staging |
| `RABBITMQ_PASSWORD` | Contraseña de RabbitMQ. Sensible. No debe estar vacía ni ser la de por defecto en producción/staging. | `guest` | En producción/staging |
| `RABBITMQ_VHOST` | Host virtual de RabbitMQ. | `/` | No |
| `RABBITMQ_STR_EXCHANGE` | Nombre del exchange para los eventos de ciclo de vida de STR. | `str.events` | No |
| `RABBITMQ_TLS_ENABLED` | Habilita el TLS hacia RabbitMQ. Debe ser `true` en producción/staging cuando se define un host. | `false` | En producción/staging |
| `OUTBOX_DISPATCH_INTERVAL` | Intervalo entre ciclos de despacho del outbox (duración de Go). | `2s` | No |
| `OUTBOX_BATCH_SIZE` | Filas drenadas por ciclo de despacho. | `50` | No |
| `OUTBOX_MAX_PUBLISH_ATTEMPTS` | Intentos de publicación antes de aparcar un evento. | `3` | No |
| `OUTBOX_POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas para el pool del outbox. | `10` | No |
| `OUTBOX_POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas para el pool del outbox. | `5` | No |
| `EVENT_DELIVERY_BATCH_SIZE` | Eventos entregados por ciclo. | `25` | No |
| `EVENT_DELIVERY_MAX_ATTEMPTS` | Intentos de entrega antes de aparcar un evento. | `3` | No |
| `EVENT_DELIVERY_RETRY_BACKOFF` | Backoff base entre reintentos de entrega (duración de Go). | `30s` | No |
| `DISPATCH_MAX_AUTO_ATTEMPTS` | Intentos de despacho automático antes de la intervención manual. | `8` | No |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Backoff máximo entre reintentos de despacho (duración de Go). | `30m` | No |
## Aprobación (maker-checker)
Aprobación opcional por bandas de valor que controla la emisión STR. Desactivada por defecto: una tabla de bandas vacía permite que cada emisión avance en un solo paso.
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | --------- |
| `APPROVAL_ALCADA_BANDS` | Bandas `maxExclusive:requiredSignatures` separadas por punto y coma (p. ej. `10000.00:1;100000.00:2`). Vacío mantiene la aprobación desactivada. | — | No |
| `APPROVAL_DEADLINE_WINDOW` | Cuánto tiempo puede esperar una emisión aparcada (duración de Go, con un tope de 7 días). | `24h` | No |
| `APPROVAL_EXPIRY_ENABLED` | Ejecuta el barrido en segundo plano que expira las emisiones aparcadas vencidas. | `true` | No |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Intervalo del barrido (duración de Go). | `1m` | No |
## Limitación de tasa e idempotencia
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------------------- | --------------------------------------------------------------- | ----------------- | --------- |
| `RATE_LIMIT_IP_MAX` | Máximo de peticiones por IP por ventana. | `300` | No |
| `RATE_LIMIT_IP_WINDOW` | Ventana de limitación de tasa por IP (duración de Go). | `1m` | No |
| `RATE_LIMIT_KEY_MAX` | Máximo de peticiones por clave de API por ventana. | `100` | No |
| `RATE_LIMIT_KEY_WINDOW` | Ventana de limitación de tasa por clave (duración de Go). | `1m` | No |
| `IDEMPOTENCY_ENABLED` | Habilita la deduplicación por clave de idempotencia. | `true` | No |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | Cuánto tiempo (segundos) se conserva una clave de idempotencia. | `300` | No |
## Systemplane y configuración en tiempo de ejecución
Lerian SPB monta la API de administración de configuración en tiempo de ejecución de systemplane en `/v1/system` en el puerto principal; está respaldada por PostgreSQL, de modo que los operadores pueden leer y cambiar los ajustes recargables en caliente sin reiniciar. Consulta [Systemplane](/es/reference/systemplane/overview) para la API, los espacios de nombres y los permisos.
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------- |
| `SYSTEMPLANE_LISTEN_CHANNEL` | Canal `LISTEN`/`NOTIFY` de PostgreSQL al que el plano de configuración en tiempo de ejecución se suscribe para los cambios de configuración en caliente. | Valor por defecto del servicio | No |
## Cifrado y secretos
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------- |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Clave AES-256 codificada en Base64 para el cifrado en reposo de los payloads STR almacenados. Sensible. Requerida en producción/staging. | — | En producción/staging |
| `WEBHOOK_SECRET_KEY` | Clave usada para cifrar los secretos de webhook almacenados. Sensible. Requerida en producción/staging. | — | En producción/staging |
| `INBOUND_ALLOW_CLEARTEXT_FALLBACK` | Permite que la vía entrante acepte payloads sin cifrar. Déjala en `false` en producción. | `false` | No |
Nunca guardes en el repositorio ni registres en logs los valores de ninguna variable marcada como *Sensible* (contraseñas, tokens, PIN y claves AES). Inyéctalos en el momento del despliegue mediante tu gestor de secretos.
## Observabilidad
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------ | -------------------------------- |
| `ENABLE_TELEMETRY` | Habilita el tracing y las métricas de OpenTelemetry. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. | `http://localhost:4318` | Si la telemetría está habilitada |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio adjuntado a la telemetría exportada. | Valor por defecto del servicio | No |
| `METRICS_PROMETHEUS_ENABLED` | Expone un endpoint de scrape de Prometheus dedicado. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | Dirección de escucha del endpoint de Prometheus. Se enlaza a loopback por defecto. | `127.0.0.1:9090` | No |
## Solo para desarrollo
Estas variables amplían la superficie de ataque y se rechazan o se fuerzan a desactivarse en producción/staging. Mantenlas sin definir fuera del desarrollo local.
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------- |
| `ENABLE_DEV_DEBUG_ROUTES` | Expone rutas de depuración. Prohibido en producción/staging. | `false` | No |
| `DEV_DEBUG_TOKEN` | Token que protege las rutas de depuración. Sensible. Requerido cuando las rutas de depuración están habilitadas. | — | Si el debug está habilitado |
| `SWAGGER_ENABLED` | Sirve la especificación OpenAPI y la interfaz de documentación de la API. Se fuerza a desactivarse en producción. | `false` | No |
| `STR_MQ_MOCK` | Enruta el transporte STR a un mock en lugar de a un gestor de colas en vivo. | `false` | No |
| `STR_MQ_MOCK_HOST` | Host del mock de STR. Requerido cuando `STR_MQ_MOCK=true`. | `http://localhost:8080` | Si el mock está habilitado |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Lista de permitidos de hosts que el transporte mock puede alcanzar. | — | No |
| `ALLOW_MOCK_TRANSPORT` | Permite que el transporte mock pueda seleccionarse siquiera. | `false` | No |
## Salud y readiness
Lerian SPB expone `GET /health` (liveness) y `GET /readyz` (readiness) en el puerto HTTP principal. Consulta [Salud y readiness](/es/reference/health-and-readiness) para el contrato de las sondas.