> ## 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 para Lerian SPI: runtime, conectividad SPI/DICT del BACEN, firma de mensajes y certificados, cifrado de PII, persistencia y streaming.
Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Alcanza el sistema de pagos instantáneos (SPI) de BACEN y el directorio de claves DICT a través de la RSFN. Se entrega como cuatro binarios de runtime —`spi`, `dict`, `brcode` y `core`—, por lo que su conjunto de variables es amplio.
El servicio lee cada variable al arrancar. Cuando systemplane está activo —el valor por defecto— puede sobrescribir un subconjunto en tiempo de ejecución sin reiniciar. El resto de las variables requieren un reinicio para cambiar. Para los ajustes que se comportan igual en todos los servicios Go de Lerian —postura de despliegue, almacenes de datos, multi-tenancy, telemetría, streaming— consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, **Requerida** marca una variable que debes definir —de forma global o bajo la condición indicada—. `—` significa que no hay valor por defecto.
La mayoría de las variables orientadas a BACEN llevan un prefijo de superficie: `BACEN_SPI_*` para el transporte de liquidación SPI, `BACEN_DICT_*` para el cliente DICT, `BACEN_BRCODE_JOSE_*` para la firma JOSE de BR Code y `BACEN_ICOM_*` para el canal entrante de long-poll.
## Runtime y servidor
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------- |
| `ENV_NAME` | Etiqueta del entorno de runtime. Si no está definida, se resuelve como `development`; un `none` explícito no es válido. `production` activa controles de seguridad más estrictos. | `development` | No |
| `LOG_LEVEL` | Verbosidad de los logs (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_ADDRESS` | Dirección de escucha HTTP principal (`host:port` o `:port`). Liveness, readiness y systemplane se enlazan a este puerto. | `:8080` | No |
| `HTTP_BODY_LIMIT_BYTES` | Tamaño máximo del cuerpo de la petición en bytes. | `1048576` | No |
| `PUBLIC_BASE_URL` | URL base del servicio accesible desde el exterior, usada para construir URLs de callback absolutas y enlaces de payload de BR Code. | — | En producción o si JOSE de BR Code está habilitado |
| `ACCESS_CONTROL_ALLOW_ORIGIN` | Orígenes CORS permitidos. | `http://localhost:3000` | No |
| `ACCESS_CONTROL_ALLOW_METHODS` | Métodos CORS permitidos. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | No |
| `ACCESS_CONTROL_ALLOW_HEADERS` | Encabezados de petición CORS permitidos. | (conjunto estándar) | No |
| `TRUSTED_PROXIES` | IPs/CIDR de proxy de confianza, separados por comas, autorizados a establecer la IP real del cliente. | — | No |
| `SERVER_TLS_CERT_FILE` | Ruta al certificado TLS del servidor. Se define junto con el archivo de clave. | — | No |
| `SERVER_TLS_KEY_FILE` | Ruta a la clave privada TLS del servidor. Sensible. | — | No |
| `SERVER_TLS_CLIENT_CA_FILE` | Archivo CA para verificar los certificados de cliente (TLS mutuo). | — | No |
| `TLS_TERMINATED_UPSTREAM` | Defínela como `true` cuando el TLS lo termina un balanceador de carga o un proxy inverso. | `false` | No |
## Autenticación
Lerian SPI autoriza las rutas protegidas —incluida la API de administración de systemplane— a través de Access Manager.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------ |
| `AUTH_ENABLED` | Exige autenticación de Access Manager en las rutas protegidas. | `false` | En producción |
| `PLUGIN_AUTH_ADDRESS` | Dirección del servicio Access Manager. | — | Si está habilitada |
| `AUTH_TRUST_UPSTREAM_METADATA` | Confía en los metadatos de identidad reenviados por un proxy upstream. Déjala en `false` salvo que el proxy sea de confianza. | `false` | No |
## Callback de BACEN (entrante desde SPI)
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------- | ---------------------------------------------- |
| `BACEN_CALLBACK_TRUSTED_PROXY_CIDRS` | CIDR de confianza como origen de los callbacks de BACEN. | — | No |
| `BACEN_CALLBACK_MTLS_HEADER_SECRET` | Secreto compartido que prueba que el upstream terminó el TLS mutuo del callback. Sensible. | — | Si el consumidor ICOM primario está habilitado |
## Transporte de liquidación SPI (`BACEN_SPI_*`)
Conexión al endpoint de liquidación SPI de BACEN a través de la RSFN, con un endpoint secundario opcional y el endpoint de archivo (ARQ).
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------- |
| `BACEN_SPI_ENDPOINT` | URL del endpoint SPI principal. | `http://localhost:9900` | Sí (SPI en vivo) |
| `BACEN_SPI_SECONDARY_ENDPOINT` | URL del endpoint SPI secundario para failover. | — | Si el consumidor ICOM secundario está habilitado |
| `BACEN_ARQ_ENDPOINT` | URL del endpoint ARQ (archivo/lote). | — | No |
| `BACEN_SPI_PARTICIPANT_ISPB` | El ISPB del participante para la superficie SPI. | — | Sí (SPI en vivo) |
| `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS` | Lista de permitidos de hosts que el cliente SPI puede alcanzar (protección SSRF). | — | No |
| `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Lista de permitidos para el endpoint secundario. | — | No |
| `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS` | Lista de permitidos para el endpoint ARQ. | — | No |
| `BACEN_SPI_TIMEOUT_SEC` | Tiempo de espera de la petición (segundos). | `30` | No |
| `BACEN_SPI_INITIATION_TIMEOUT_MS` | Tiempo de espera de la iniciación de pago (milisegundos). | `150` | No |
| `BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS` | Tiempo de espera del procesamiento del callback entrante (milisegundos). | `250` | No |
| `BACEN_SPI_RETRY_ATTEMPTS` | Intentos de reintento ante un fallo de transporte. | `3` | No |
| `BACEN_SPI_RETRY_INITIAL_BACKOFF_MS` | Backoff inicial de reintento (milisegundos). | `500` | No |
| `BACEN_SPI_RETRY_MAX_BACKOFF_MS` | Backoff máximo de reintento (milisegundos). | `5000` | No |
| `BACEN_SPI_OUTBOUND_QUOTA_ENABLED` | Habilita la cuota de tasa saliente del lado cliente. | `false` | No |
| `BACEN_SPI_OUTBOUND_QUOTA_LIMIT` | Cuota saliente sostenida (peticiones). | — | Si la cuota está habilitada |
| `BACEN_SPI_OUTBOUND_QUOTA_BURST` | Margen de ráfaga por encima de la cuota. | — | Si la cuota está habilitada |
| `BACEN_SPI_CATALOGUE_VERSION` | Versión del catálogo de mensajes SPI de BACEN. | `5.12.1` | No |
| `BACEN_SPI_XSD_DIR` | Directorio de los esquemas XSD de BACEN incluidos para el catálogo. | Ruta incluida | No |
| `BACEN_SPI_CATALOGUE_ROOT` | Raíz de sobrescritura para el catálogo de mensajes. | — | No |
| `BACEN_SPI_INTERNAL_CALLBACK_SECRET` | Secreto compartido para la vía de callback interna. Mínimo 32 caracteres cuando se define. Sensible. | — | En producción o si el consumidor ICOM primario está habilitado |
### TLS mutuo hacia BACEN
Los archivos `BACEN_TLS_*` respaldan el canal de TLS mutuo hacia BACEN. Los clientes SPI y DICT los comparten.
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------- | ----------------------------------------------------------------------- | ----------------- | ------------ |
| `BACEN_TLS_CERT_FILE` | Certificado de cliente presentado a BACEN. | — | Sí (en vivo) |
| `BACEN_TLS_KEY_FILE` | Clave privada del cliente. Sensible. | — | Sí (en vivo) |
| `BACEN_TLS_CA_FILE` | Paquete de CA usado para verificar el certificado de servidor de BACEN. | — | Sí (en vivo) |
## Firma de mensajes y certificados
Lerian SPI firma digitalmente sus mensajes salientes. Elige un backend de custodia con `BACEN_SPI_SIGNER_KIND`.
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------- |
| `BACEN_SPI_SIGNER_KIND` | Backend de custodia de firma: `file`, `pkcs11` o `kmip`. Usa un backend de hardware en producción. | `file` | No |
| `BACEN_SPI_SIGNER_COMMON_NAME` | Nombre común esperado del certificado de firma. | — | No |
| `BACEN_SPI_SIGNING_CERT_FILE` | Ruta al certificado vinculado a la clave de firma. Se requiere para `pkcs11` o `kmip`; con `file`, recurre a `BACEN_TLS_CERT_FILE` cuando no se define. | `BACEN_TLS_CERT_FILE` (`file`) | Si `pkcs11` o `kmip` |
| `BACEN_SPI_INBOUND_SIGNER_COMMON_NAME` | Nombre común esperado del firmante en los mensajes 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`. | `14` | No |
| `BACEN_SPI_PKCS11_MODULE_PATH` | Ruta a la biblioteca del módulo PKCS#11. | — | Si `pkcs11` |
| `BACEN_SPI_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si `pkcs11` |
| `BACEN_SPI_PKCS11_PIN_FILE` | Ruta a un archivo que contiene el PIN del token. Sensible. | — | Si `pkcs11` |
| `BACEN_SPI_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si `pkcs11` |
| `BACEN_SPI_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si `kmip` |
| `BACEN_SPI_KMIP_VHSM` | Identificador del HSM virtual. | — | Si `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER` | Usuario cripto de KMIP. | — | Si `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER_TOKEN` | Token del usuario cripto de KMIP. Sensible. | — | Si `kmip` |
| `BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si `kmip` |
| `BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si `kmip` |
| `BACEN_SPI_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP. | `false` | No |
### Validación de certificados (OCSP/CRL)
| Variable | Descripción | Valor por defecto | Requerida |
| ---------------------------------- | ------------------------------------------------------------------------ | ----------------- | --------- |
| `BACEN_SPI_OCSP_MODE` | Modo de comprobación de revocación de certificados (p. ej. `soft_fail`). | `soft_fail` | No |
| `BACEN_SPI_OCSP_TIMEOUT_MS` | Tiempo de espera de la petición OCSP (milisegundos). | `3000` | No |
| `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Tope del TTL de la respuesta OCSP en caché (segundos). | `3600` | No |
| `BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC` | TTL de la caché de CRL (segundos). | `3600` | No |
### Resolutor de payloads
Estas variables controlan cómo el servicio almacena y referencia los payloads SPI grandes.
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------ |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND` | Backend de almacenamiento de payloads: `in_memory` o `postgres`. Los entornos de tipo producción rechazan `in_memory` — usa un backend durable. | `in_memory` | No |
| `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Máximo de bytes retenidos por el resolutor en memoria. | `134217728` | No |
| `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC` | TTL de retención de los payloads resueltos (segundos). | `86400` | No |
| `BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY` | Clave AES-256 para cifrar los payloads almacenados. Sensible. | — | Si el tipo es `postgres` |
## Canal entrante (`BACEN_ICOM_*`)
Canal de long-poll para los mensajes que BACEN devuelve al participante.
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------------------- | ---------------------------------------------- | ----------------- | ---------------------------------------------- |
| `BACEN_ICOM_BASE_URL` | URL base del canal entrante. | — | Si el consumidor ICOM primario está habilitado |
| `BACEN_ICOM_ISPB` | ISPB del participante para el canal entrante. | — | Si el consumidor ICOM primario está habilitado |
| `BACEN_ICOM_CONSUMER_ENABLED` | Habilita el consumidor entrante principal. | `false` | No |
| `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED` | Habilita el consumidor entrante secundario. | `false` | No |
| `BACEN_ICOM_LONGPOLL_TIMEOUT_MS` | Tiempo de espera del long-poll (milisegundos). | `90000` | No |
Con `BACEN_ICOM_CONSUMER_ENABLED=true`, el arranque también requiere un backend de persistencia configurado, `BACEN_SPI_INTERNAL_CALLBACK_SECRET` y `BACEN_CALLBACK_MTLS_HEADER_SECRET`. Con `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED=true`, también requiere `BACEN_SPI_SECONDARY_ENDPOINT`.
## Cliente DICT (`BACEN_DICT_*`)
Cliente para el directorio de claves Pix (DICT) de BACEN, incluido el endpoint antifraude (NP).
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------------- | -------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------ |
| `BACEN_DICT_ENDPOINT` | URL del endpoint DICT. | `http://localhost:9900` | Sí (DICT en vivo) |
| `BACEN_DICT_PARTICIPANT_ISPB` | ISPB del participante para la superficie DICT. | — | Sí (DICT en vivo) |
| `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS` | Lista de permitidos de hosts que el cliente DICT puede alcanzar. | — | No |
| `BACEN_DICT_TIMEOUT_SEC` | Tiempo de espera de la petición DICT (segundos). | `10` | No |
| `BACEN_DICT_NP_ENDPOINT` | URL del endpoint antifraude (NP). | — | No |
| `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Lista de permitidos para el endpoint NP. | — | No |
| `BACEN_DICT_SIGNER_KIND` | Backend de custodia de firma DICT: `file`, `pkcs11` o `kmip`. | `file` | No |
| `BACEN_DICT_SIGNING_CERT_FILE` | Ruta al certificado de firma DICT. | — | Para la ruta de custodia DICT seleccionada |
| `BACEN_DICT_SIGNING_KEY_FILE` | Ruta a la clave privada de firma DICT (backend de archivo). Sensible. | — | Si `file` |
| `BACEN_DICT_VERIFY_CERT_FILE` | Certificado usado para verificar las respuestas DICT. | — | No |
| `BACEN_DICT_PKCS11_MODULE_PATH` | Ruta al módulo PKCS#11. | — | Si `pkcs11` |
| `BACEN_DICT_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si `pkcs11` |
| `BACEN_DICT_PKCS11_PIN_FILE` | Ruta al archivo del PIN del token. Sensible. | — | Si `pkcs11` |
| `BACEN_DICT_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si `pkcs11` |
| `BACEN_DICT_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si `kmip` |
| `BACEN_DICT_KMIP_VHSM` | Identificador del HSM virtual. | — | Si `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER` | Usuario cripto de KMIP. | — | Si `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER_TOKEN` | Token del usuario cripto de KMIP. Sensible. | — | Si `kmip` |
| `BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si `kmip` |
| `BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si `kmip` |
| `BACEN_DICT_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP. | `false` | No |
| `BACEN_DICT_INTENT_ENCRYPTION_KEY` | Clave AES-256 para cifrar las intenciones de reclamo DICT almacenadas. Sensible. | — | En producción |
## Firma JOSE de BR Code (`BACEN_BRCODE_JOSE_*`)
Firma los payloads dinámicos de BR Code (JWS).
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------------------------- | -------------------------------------------------------------------------- | ----------------- | ----------------------------------------------- |
| `BACEN_BRCODE_JOSE_SIGNER_KIND` | Backend de custodia de firma JOSE: `file`, `pkcs11` o `kmip`. | — | No |
| `BACEN_BRCODE_JOSE_SIGNING_CERT_FILE` | Ruta al certificado de firma JOSE. | — | Si JOSE de BR Code está habilitado |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE` | Ruta a la clave privada de firma JOSE (backend de archivo). Sensible. | — | Si JOSE de BR Code está habilitado con `file` |
| `BACEN_BRCODE_JOSE_KID` | Valor del encabezado identificador de clave JWS (`kid`). | — | Si JOSE de BR Code está habilitado |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH` | Ruta al módulo PKCS#11. | — | Si JOSE de BR Code está habilitado con `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si JOSE de BR Code está habilitado con `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE` | Ruta al archivo del PIN del token. Sensible. | — | Si JOSE de BR Code está habilitado con `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si JOSE de BR Code está habilitado con `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_VHSM` | Identificador del HSM virtual. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER` | Usuario cripto de KMIP. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN` | Token del usuario cripto de KMIP. Sensible. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si JOSE de BR Code está habilitado con `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP. | `false` | No |
## Cifrado y hashing de PII
Cada variable de abajo contiene material sensible de clave o pepper. Protege los datos personales en reposo mediante cifrado e indexado ciego. Nunca guardes en el repositorio ni registres en logs un valor. Inyéctalo en el momento del despliegue mediante tu gestor de secretos. Una rotación de pepper o de clave requiere una reindexación o un recifrado planificado.
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------------- |
| `DICT_KEY_PII_ENCRYPTION_KEY` | Clave AES para la PII del titular de la clave DICT. Sensible. | — | Runtime DICT protegido |
| `DICT_KEY_BLIND_INDEX_PEPPER` | Pepper para el indexado ciego de la PII de las claves DICT. Sensible. | — | Runtime DICT protegido |
| `DICT_AUDIT_HASH_PEPPER` | Pepper para el hashing de los registros de auditoría DICT. Sensible. | — | Runtime protegido |
| `AUDIT_HASH_PEPPER` | Pepper heredado de hash de auditoría. Sensible. | — | Runtime protegido |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY` | Clave AES para la PII de las partes responsables. Sensible. | — | Runtime SPI protegido |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | Clave AES-256 para la PII de las operaciones. Sensible. El servicio SPI se niega a iniciar si falta o no tiene un formato válido. | — | Sí — servicio SPI en todos los entornos |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper para el indexado ciego de la PII de las operaciones. Sensible. Debe tener al menos 32 caracteres; el servicio SPI se niega a iniciar si falta o es más corto. | — | Sí — servicio SPI en todos los entornos |
| `BRCODE_PII_ENCRYPTION_KEY` | Clave AES para la PII de BR Code. Sensible. | — | Runtime BR Code protegido |
| `BRCODE_PII_BLIND_INDEX_PEPPER` | Pepper para el indexado ciego de la PII de BR Code. Sensible. | — | Runtime BR Code protegido |
## 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. | `brspi` | No |
| `POSTGRES_PASSWORD` | Contraseña de la base de datos. Sensible. Usa un secreto explícito en producción. | Contraseña de desarrollo en código | No |
| `POSTGRES_DB` | Nombre de la base de datos. | `brspi` | No |
| `POSTGRES_SSLMODE` | Modo TLS de libpq. Para conexiones remotas de producción, usa `verify-full` con una CA de confianza; `require` cifra el canal pero no verifica la identidad del servidor. | `disable` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Máximo de conexiones abiertas. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Máximo de conexiones inactivas. | `5` | No |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Vida máxima de la conexión (minutos). | `30` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Tiempo máximo de inactividad de la conexión (minutos). | `5` | No |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Tiempo de espera de conexión (segundos). | `10` | No |
| `POSTGRES_REPLICA_HOST` | Host de réplica de lectura opcional. Los demás campos de réplica recurren a la primaria. | — | 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 y puerto de Redis. | `localhost:6379` | No |
| `REDIS_MASTER_NAME` | Nombre del master de Sentinel (si se usa Sentinel). | — | No |
| `REDIS_PASSWORD` | Contraseña de Redis. Sensible. | — | No |
| `REDIS_DB` | Número de base de datos de Redis. | `0` | No |
| `REDIS_PROTOCOL` | Versión del protocolo de Redis (2 o 3). | `3` | No |
| `REDIS_TLS` | Habilita el TLS hacia Redis. | `false` | No |
| `REDIS_CA_CERT` | Certificado CA para el TLS de Redis. | — | No |
| `REDIS_POOL_SIZE` | Tamaño del pool de conexiones. | `10` | No |
| `REDIS_MIN_IDLE_CONNS` | Mínimo de conexiones inactivas. | `2` | No |
| `REDIS_READ_TIMEOUT_MS` | Tiempo de espera de lectura (milisegundos). | `3000` | No |
| `REDIS_WRITE_TIMEOUT_MS` | Tiempo de espera de escritura (milisegundos). | `3000` | No |
| `REDIS_DIAL_TIMEOUT_MS` | Tiempo de espera de conexión (milisegundos). | `5000` | No |
## Outbox y streaming
Lerian SPI publica eventos a través de un outbox transaccional y de un productor de lib-streaming, y consume eventos de liquidación para BR Code. El streaming no tiene un interruptor de habilitación: `STREAMING_BROKERS` es obligatorio al iniciar, incluso cuando `OUTBOX_ENABLED=false`. Configura los ajustes compartidos `STREAMING_CLOUDEVENTS_SOURCE`, `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS` y `STREAMING_EVENT_POLICIES` como se describe en [Streaming y outbox](/es/reference/byoc-configuration#streaming-y-outbox).
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------- |
| `OUTBOX_ENABLED` | Habilita el despachador del outbox transaccional. | `true` | No |
| `OUTBOX_DISPATCH_INTERVAL_MS` | Intervalo entre ciclos de despacho (milisegundos). | `2000` | No |
| `OUTBOX_BATCH_SIZE` | Filas drenadas por ciclo de despacho. | `50` | No |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Intentos de despacho antes de aparcar un evento. | `10` | No |
| `OUTBOX_PROCESSING_TIMEOUT_MS` | Tiempo de espera de procesamiento por lote (milisegundos). | `600000` | No |
| `OUTBOX_RETRY_WINDOW_MS` | Ventana de reintento antes de recuperar una fila atascada (milisegundos). | `300000` | No |
| `BRCODE_SETTLEMENT_CONSUMER_ENABLED` | Habilita el consumidor de liquidación de BR Code. Requiere `STREAMING_BROKERS`. | `false` | No |
| `BRCODE_SETTLEMENT_CONSUMER_TOPIC` | Topic que lee el consumidor de liquidación de BR Code. | `br-spi.spi.payment` | No |
| `BRCODE_SETTLEMENT_CONSUMER_GROUP` | Grupo de consumidores para la liquidación de BR Code. | `br-spi-brcode-settlement-consumer` | No |
| `BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID` | Client ID que el consumidor de liquidación presenta al broker. | — | No |
| `SPI_PARTICIPANT_CONSUMER_ENABLED` | Habilita el consumidor de solicitudes de participante de Core a SPI. Requiere `STREAMING_BROKERS`, transporte BACEN y persistencia cuando está habilitado. | `false` | No |
| `SPI_PARTICIPANT_CONSUMER_TOPIC` | Topic que transporta las solicitudes de participante de Core. | `br-spi.core.participant` | No |
| `SPI_PARTICIPANT_CONSUMER_GROUP` | Grupo de consumidores durable para solicitudes de participante. | `br-spi-participant-request-consumer` | No |
| `SPI_PARTICIPANT_CONSUMER_CLIENT_ID` | Client ID que el consumidor de solicitudes de participante presenta al broker. Recurre al client ID compartido de streaming. | Client ID compartido | No |
## Programadores
Trabajos en segundo plano, cada uno controlado de forma independiente. Todos desactivados por defecto.
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------------------------------------- | ----------------------------------------------------------- | ----------------- | --------- |
| `SCHEDULER_ENABLED` | Interruptor maestro del subsistema de programación. | `false` | No |
| `SCHEDULER_MED_DEADLINE_ENABLED` | Ejecuta el trabajo de plazo del MED (devolución especial). | `false` | No |
| `SCHEDULER_QUOTA_RESET_ENABLED` | Ejecuta el trabajo de reinicio de la cuota saliente. | `false` | No |
| `SCHEDULER_CLAIM_DEADLINE_ENABLED` | Ejecuta el trabajo de plazo de reclamos DICT. | `false` | No |
| `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Ejecuta la reconciliación DICT incremental. | `false` | No |
| `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED` | Ejecuta la reconciliación DICT completa. | `false` | No |
| `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED` | Ejecuta el trabajo de retención de auditoría DICT. | `false` | No |
| `SCHEDULER_INBOUND_DISCOVERY_ENABLED` | Ejecuta el trabajo de descubrimiento de mensajes entrantes. | `false` | No |
| `SCHEDULER_APPROVAL_EXPIRY_ENABLED` | Ejecuta el barrido de expiración de aprobaciones. | `false` | No |
| `SCHEDULER_PORTABILITY_DEADLINE_ENABLED` | Ejecuta el trabajo de plazo de portabilidad. | `false` | No |
## Limitación de tasa, idempotencia y conectividad
| Variable | Descripción | Valor por defecto | Requerida |
| ------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------- |
| `RATE_LIMIT_ENABLED` | Habilita la limitación de tasa de peticiones. | `true` | No |
| `RATE_LIMIT_MAX` | Máximo de peticiones por ventana. | `100` | No |
| `RATE_LIMIT_EXPIRY_SEC` | Ventana de limitación de tasa (segundos). | `60` | No |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | Cuánto tiempo (segundos) se conserva una clave de idempotencia. | `86400` | No |
| `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | Clave AES-256 para cifrar las respuestas de idempotencia almacenadas. Sensible. | — | Runtime SPI, DICT o Core protegido |
| `INFRA_CONNECT_TIMEOUT_SEC` | Tiempo de espera de conexión para las dependencias de infraestructura al arrancar (segundos). | `30` | No |
## Systemplane y configuración en tiempo de ejecución
| Variable | Descripción | Valor por defecto | Requerida |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `SYSTEMPLANE_ENABLED` | Habilita la API de administración de configuración en tiempo de ejecución de systemplane, montada en `/v1/system` en el puerto principal. Cuando es `false`, el servicio funciona en modo solo-entorno, sin plano de administración. **SPI lo activa por defecto**, a diferencia de la mayoría de los servicios de Lerian, donde systemplane está desactivado por defecto. | `true` | No |
Consulta [Systemplane](/es/reference/systemplane/overview) para la API, los espacios de nombres y los permisos requeridos.
## Observabilidad
| Variable | Descripción | Valor por defecto | Requerida |
| -------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------- | -------------------------------- |
| `ENABLE_TELEMETRY` | Habilita el tracing y las métricas de OpenTelemetry. | `false` | No |
| `TELEMETRY_REQUIRED` | Falla el arranque si la telemetría no puede inicializarse. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del colector OTLP. | `localhost:4317` | Si la telemetría está habilitada |
| `OTEL_RESOURCE_SERVICE_NAME` | Nombre del servicio adjunto a la telemetría exportada. | Predeterminado del servicio | No |
| `OTEL_RESOURCE_SERVICE_VERSION` | Etiqueta de versión del servicio. | `1.0.0` | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Etiqueta del entorno de despliegue. | `development` | No |
| `OTEL_LIBRARY_NAME` | Nombre de la biblioteca de instrumentación. | Predeterminado 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 |
## Documentación
| Variable | Descripción | Valor por defecto | Requerida |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------- | --------- |
| `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 |
## Salud y readiness
Lerian SPI expone `GET /health` (liveness), `GET /readyz` (readiness) y `GET /version` en el puerto HTTP principal. `/metrics` se ejecuta en su propio listener cuando está habilitado. Consulta [Salud y readiness](/es/reference/health-and-readiness) para el contrato de las sondas.