> ## 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 SPI: conectividad BACEN SPI/DICT, certificados de firma ISO 20022, cifrado de PII, persistencia y streaming. Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Llega al sistema de pagos instantáneos de BACEN (SPI) y al directorio de claves DICT a través de la RSFN. Incluye cuatro binarios en tiempo de ejecución (`spi`, `dict`, `brcode` y `core`), por lo que su conjunto de variables es amplio. El servicio lee todas las variables al iniciar. Cuando systemplane está activo (el valor predeterminado), puede anular un subconjunto en tiempo de ejecución sin reiniciar. El resto de las variables requieren un reinicio para cambiar. Para los parámetros que se comportan igual en todos los servicios de Lerian en Go (postura de despliegue, almacenes de datos, multi-tenancy, telemetría, streaming), consulta [Elementos esenciales de configuración de BYOC](/es/reference/byoc-configuration). En las tablas siguientes, **Obligatorio** marca una variable que debes configurar, de forma global o bajo la condición indicada. `—` significa que no tiene valor predeterminado. La mayoría de las variables orientadas a BACEN llevan un prefijo de superficie: `BACEN_SPI_*` para el transporte de liquidación de SPI, `BACEN_DICT_*` para el cliente DICT, `BACEN_BRCODE_JOSE_*` para la firma JOSE de BR Code, y `BACEN_ICOM_*` para el canal de long-poll entrante. ## Tiempo de ejecución y servidor | Variable | Descripción | Predeterminado | Obligatorio | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------- | | `ENV_NAME` | Etiqueta del entorno de ejecución. Cuando no se configura, se resuelve a `development`; un valor explícito `none` no es válido. Producción activa medidas de seguridad más estrictas. | `development` | No | | `LOG_LEVEL` | Nivel de detalle de los logs (`debug`, `info`, `warn`, `error`). | `info` | No | | `SERVER_ADDRESS` | Dirección principal de escucha HTTP (`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 solicitud en bytes. | `1048576` | No | | `PUBLIC_BASE_URL` | URL base del servicio accesible externamente, usada para construir URLs de callback absolutas y enlaces de payload de BR Code. | — | En producción o si BR Code JOSE 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 solicitud CORS permitidos. | (conjunto estándar) | No | | `TRUSTED_PROXIES` | IPs/CIDRs de proxy separados por comas, confiables para establecer la IP real del cliente. | — | No | | `SERVER_TLS_CERT_FILE` | Ruta al certificado TLS del servidor. Se configura junto con el archivo de la clave. | — | No | | `SERVER_TLS_KEY_FILE` | Ruta a la clave privada TLS del servidor. Sensible. | — | No | | `SERVER_TLS_CLIENT_CA_FILE` | Archivo de CA para verificar certificados de cliente (TLS mutuo). | — | No | | `TLS_TERMINATED_UPSTREAM` | Configura `true` cuando el TLS se termina en un balanceador de carga o 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 | Predeterminado | Obligatorio | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------ | | `AUTH_ENABLED` | Requiere autenticación de Access Manager en las rutas protegidas. | `false` | En producción | | `PLUGIN_AUTH_ADDRESS` | Dirección del servicio Access Manager. | — | Si está habilitado | | `AUTH_TRUST_UPSTREAM_METADATA` | Confía en los metadatos de identidad reenviados por un proxy upstream. Deja `false` a menos que el proxy sea confiable. | `false` | No | ## Callback de BACEN (entrante desde SPI) | Variable | Descripción | Predeterminado | Obligatorio | | ------------------------------------ | --------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------- | | `BACEN_CALLBACK_TRUSTED_PROXY_CIDRS` | CIDRs confiables como origen de los callbacks de BACEN. | — | No | | `BACEN_CALLBACK_MTLS_HEADER_SECRET` | Secreto compartido que demuestra que el upstream terminó el TLS mutuo del callback. Sensible. | — | Si el consumidor primario de ICOM está habilitado | ## Transporte de liquidación de 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 | Predeterminado | Obligatorio | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------- | | `BACEN_SPI_ENDPOINT` | URL del endpoint principal de SPI. | `http://localhost:9900` | Sí (SPI en vivo) | | `BACEN_SPI_SECONDARY_ENDPOINT` | URL del endpoint secundario de SPI para conmutación por error. | — | Si el consumidor secundario de ICOM está habilitado | | `BACEN_ARQ_ENDPOINT` | URL del endpoint ARQ (archivo/lote). | — | No | | `BACEN_SPI_PARTICIPANT_ISPB` | El ISPB del participante para la superficie de SPI. | — | Sí (SPI en vivo) | | `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos que el cliente SPI puede alcanzar (protección contra SSRF). | — | No | | `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para el endpoint secundario. | — | No | | `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para el endpoint ARQ. | — | No | | `BACEN_SPI_TIMEOUT_SEC` | Timeout de la solicitud (segundos). | `30` | No | | `BACEN_SPI_INITIATION_TIMEOUT_MS` | Timeout de inicio de pago (milisegundos). | `150` | No | | `BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS` | Timeout de procesamiento del callback entrante (milisegundos). | `250` | No | | `BACEN_SPI_RETRY_ATTEMPTS` | Intentos de reintento ante fallas 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 del cliente. | `false` | No | | `BACEN_SPI_OUTBOUND_QUOTA_LIMIT` | Cuota sostenida de salida (solicitudes). | — | 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 alternativa para el catálogo de mensajes. | — | No | | `BACEN_SPI_INTERNAL_CALLBACK_SECRET` | Secreto compartido para la ruta de callback interna. Al menos 32 caracteres cuando se configura. Sensible. | — | En producción o si el consumidor primario de ICOM está habilitado | ### TLS mutuo con BACEN Los archivos `BACEN_TLS_*` respaldan el canal TLS mutuo con BACEN. Los clientes de SPI y DICT los comparten. | Variable | Descripción | Predeterminado | Obligatorio | | --------------------- | ------------------------------------------------------------------------ | -------------- | ------------ | | `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 del 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 | Predeterminado | Obligatorio | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------- | | `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. Obligatorio para `pkcs11` o `kmip`; para `file`, recae en `BACEN_TLS_CERT_FILE` cuando no se configura. | `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` | Mínimo de días para el vencimiento antes de que la verificación de readiness del certificado reporte degradado. | `14` | No | | `BACEN_SPI_PKCS11_MODULE_PATH` | Ruta de 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 de 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 ASN.1 DigestInfo antes de la llamada de firma de KMIP. | `false` | No | ### Validación de certificados (OCSP/CRL) | Variable | Descripción | Predeterminado | Obligatorio | | ---------------------------------- | ------------------------------------------------------------------------------ | -------------- | ----------- | | `BACEN_SPI_OCSP_MODE` | Modo de verificación de revocación de certificados (por ejemplo, `soft_fail`). | `soft_fail` | No | | `BACEN_SPI_OCSP_TIMEOUT_MS` | Timeout de la solicitud OCSP (milisegundos). | `3000` | No | | `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Límite 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 payload Estas variables controlan cómo el servicio almacena y referencia payloads grandes de SPI. | Variable | Descripción | Predeterminado | Obligatorio | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------ | | `BACEN_SPI_PAYLOAD_RESOLVER_KIND` | Backend de almacenamiento del payload: `in_memory` o `postgres`. Los entornos similares a producción rechazan `in_memory`; usa un backend duradero. | `in_memory` | No | | `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Bytes máximos retenidos por el resolutor en memoria. | `134217728` | No | | `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC` | TTL de retención para 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 envía de vuelta al participante. | Variable | Descripción | Predeterminado | Obligatorio | | --------------------------------------- | --------------------------------------------- | -------------- | ------------------------------------------------- | | `BACEN_ICOM_BASE_URL` | URL base del canal entrante. | — | Si el consumidor primario de ICOM está habilitado | | `BACEN_ICOM_ISPB` | ISPB del participante para el canal entrante. | — | Si el consumidor primario de ICOM está habilitado | | `BACEN_ICOM_CONSUMER_ENABLED` | Habilita el consumidor entrante primario. | `false` | No | | `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED` | Habilita el consumidor entrante secundario. | `false` | No | | `BACEN_ICOM_LONGPOLL_TIMEOUT_MS` | Timeout del long-poll (milisegundos). | `90000` | No | Con `BACEN_ICOM_CONSUMER_ENABLED=true`, el inicio 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`, requiere además `BACEN_SPI_SECONDARY_ENDPOINT`. ## Cliente DICT (`BACEN_DICT_*`) Cliente para el directorio de claves Pix de BACEN (DICT), incluido el endpoint antifraude (NP). | Variable | Descripción | Predeterminado | Obligatorio | | -------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------- | | `BACEN_DICT_ENDPOINT` | URL del endpoint de DICT. | `http://localhost:9900` | Sí (DICT en vivo) | | `BACEN_DICT_PARTICIPANT_ISPB` | ISPB del participante para la superficie de DICT. | — | Sí (DICT en vivo) | | `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos que el cliente DICT puede alcanzar. | — | No | | `BACEN_DICT_TIMEOUT_SEC` | Timeout de la solicitud DICT (segundos). | `10` | No | | `BACEN_DICT_NP_ENDPOINT` | URL del endpoint antifraude (NP). | — | No | | `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Lista de hosts permitidos para el endpoint NP. | — | No | | `BACEN_DICT_SIGNER_KIND` | Backend de custodia de firma de DICT: `file`, `pkcs11` o `kmip`. | `file` | No | | `BACEN_DICT_SIGNING_CERT_FILE` | Ruta al certificado de firma de DICT. | — | Para la ruta de custodia de DICT seleccionada | | `BACEN_DICT_SIGNING_KEY_FILE` | Ruta a la clave privada de firma de DICT (backend de archivo). Sensible. | — | Si `file` | | `BACEN_DICT_VERIFY_CERT_FILE` | Certificado usado para verificar las respuestas de DICT. | — | No | | `BACEN_DICT_PKCS11_MODULE_PATH` | Ruta del 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 de 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 ASN.1 DigestInfo antes de la llamada de firma de KMIP. | `false` | No | | `BACEN_DICT_INTENT_ENCRYPTION_KEY` | Clave AES-256 para cifrar las intenciones de reclamo de DICT almacenadas. Sensible. | — | En producción | ## Firma JOSE de BR Code (`BACEN_BRCODE_JOSE_*`) Firma payloads dinámicos de BR Code (JWS). | Variable | Descripción | Predeterminado | Obligatorio | | --------------------------------------------- | -------------------------------------------------------------------------- | -------------- | -------------------------------------------- | | `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 BR Code JOSE está habilitado | | `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE` | Ruta a la clave privada de firma JOSE (backend de archivo). Sensible. | — | Si BR Code JOSE está habilitado con `file` | | `BACEN_BRCODE_JOSE_KID` | Valor del encabezado identificador de clave JWS (`kid`). | — | Si BR Code JOSE está habilitado | | `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH` | Ruta del módulo PKCS#11. | — | Si BR Code JOSE está habilitado con `pkcs11` | | `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL` | Etiqueta del token PKCS#11. | — | Si BR Code JOSE está habilitado con `pkcs11` | | `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE` | Ruta al archivo del PIN del token. Sensible. | — | Si BR Code JOSE está habilitado con `pkcs11` | | `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL` | Etiqueta de la clave de firma en el token. | — | Si BR Code JOSE está habilitado con `pkcs11` | | `BACEN_BRCODE_JOSE_KMIP_BASE_URL` | URL base del servicio KMIP. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_VHSM` | Identificador del HSM virtual. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER` | Usuario cripto de KMIP. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN` | Token de usuario cripto de KMIP. Sensible. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID` | UID de la clave pública de firma. | — | Si BR Code JOSE está habilitado con `kmip` | | `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX` | Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP. | `false` | No | ## Cifrado y hashing de PII Cada variable a continuación contiene material sensible de clave o pepper. Protege los datos personales en reposo mediante cifrado e indexación ciega. Nunca confirmes ni registres un valor en logs. Inyéctalo en el momento del despliegue a través de tu gestor de secretos. Una rotación de pepper o clave requiere un reindexado o recifrado planificado. | Variable | Descripción | Predeterminado | Obligatorio | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------- | | `DICT_KEY_PII_ENCRYPTION_KEY` | Clave AES para la PII del titular de la clave DICT. Sensible. | — | Runtime protegido de DICT | | `DICT_KEY_BLIND_INDEX_PEPPER` | Pepper para la indexación ciega de la PII de la clave DICT. Sensible. | — | Runtime protegido de DICT | | `DICT_AUDIT_HASH_PEPPER` | Pepper para el hashing de registros de auditoría de DICT. Sensible. | — | Runtime protegido | | `AUDIT_HASH_PEPPER` | Pepper de hash de auditoría heredado. Sensible. | — | Runtime protegido | | `SPI_RESPONSIBLES_ENCRYPTION_KEY` | Clave AES para la PII de la parte responsable. Sensible. | — | Runtime protegido de SPI | | `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | Clave AES-256 para la PII de la operación. Sensible. El servicio SPI se niega a iniciar si falta o está malformada. | — | Sí: el servicio SPI en todos los entornos | | `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper para la indexación ciega de la PII de la operación. Sensible. Debe contener al menos 32 caracteres; el servicio SPI se niega a iniciar si falta o es más corto. | — | Sí: el servicio SPI en todos los entornos | | `BRCODE_PII_ENCRYPTION_KEY` | Clave AES para la PII de BR Code. Sensible. | — | Runtime protegido de BR Code | | `BRCODE_PII_BLIND_INDEX_PEPPER` | Pepper para la indexación ciega de la PII de BR Code. Sensible. | — | Runtime protegido de BR Code | ## PostgreSQL | Variable | Descripción | Predeterminado | Obligatorio | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- | | `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 incluida en el código | No | | `POSTGRES_DB` | Nombre de la base de datos. | `brspi` | No | | `POSTGRES_SSLMODE` | Modo TLS de libpq. Para conexiones de producción remotas, usa `verify-full` con una CA confiable; `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` | Timeout de conexión (segundos). | `10` | No | | `POSTGRES_REPLICA_HOST` | Host opcional de réplica de lectura. Los demás campos de réplica recaen en el principal. | — | 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 | Predeterminado | Obligatorio | | ------------------------ | ---------------------------------------------------- | ---------------- | ----------- | | `REDIS_HOST` | Host y puerto de Redis. | `localhost:6379` | No | | `REDIS_MASTER_NAME` | Nombre del maestro 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 TLS hacia Redis. | `false` | No | | `REDIS_CA_CERT` | Certificado de 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` | Timeout de lectura (milisegundos). | `3000` | No | | `REDIS_WRITE_TIMEOUT_MS` | Timeout de escritura (milisegundos). | `3000` | No | | `REDIS_DIAL_TIMEOUT_MS` | Timeout para establecer la conexión (milisegundos). | `5000` | No |

Outbox y streaming

Lerian SPI publica eventos mediante un outbox transaccional y un productor de lib-streaming, y consume eventos de liquidación para BR Code. El consumidor de liquidación de BR Code se ejecuta de forma incondicional. Streaming no tiene interruptor de activació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-and-outbox). | Variable | Descripción | Predeterminado | Obligatorio | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------- | | `OUTBOX_ENABLED` | Habilita el despachador transaccional del outbox. | `true` | No | | `OUTBOX_DISPATCH_INTERVAL_MS` | Intervalo entre ciclos de despacho (milisegundos). | `2000` | No | | `OUTBOX_BATCH_SIZE` | Filas procesadas por ciclo de despacho. | `50` | No | | `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Intentos de despacho antes de que un evento se estacione. | `10` | No | | `OUTBOX_PROCESSING_TIMEOUT_MS` | Timeout de procesamiento por lote (milisegundos). | `600000` | No | | `OUTBOX_RETRY_WINDOW_MS` | Ventana de reintento antes de recuperar una fila atascada (milisegundos). | `300000` | No | | `SPI_PARTICIPANT_CONSUMER_ENABLED` | Habilita el consumidor de solicitudes de participante de Core a SPI. Se suscribe al stream de aplicación del productor de Core; el tema se deriva y no es configurable. Requiere `STREAMING_BROKERS`, transporte BACEN y persistencia cuando está habilitado. | `false` | No | | `SPI_PARTICIPANT_CONSUMER_GROUP` | Grupo de consumidores duradero para las solicitudes de participante. | Predeterminado interno del servicio | No | | `SPI_PARTICIPANT_CONSUMER_CLIENT_ID` | ID de cliente presentado al broker por el consumidor de solicitudes de participante. Recae en el ID de cliente compartido de streaming. | ID de cliente compartido | No | ## Programadores Trabajos en segundo plano, cada uno con su propio interruptor. Los trabajos controlados por el programador que se indican a continuación están desactivados por defecto. Los workers de descubrimiento e inventario de DICT tienen sus propios controles en la siguiente sección. | Variable | Descripción | Predeterminado | Obligatorio | | --------------------------------------------------- | ----------------------------------------------------------- | -------------- | ----------- | | `SCHEDULER_ENABLED` | Interruptor maestro para el subsistema del programador. | `false` | No | | `SCHEDULER_MED_DEADLINE_ENABLED` | Ejecuta el trabajo de plazo de MED (devolución especial). | `false` | No | | `SCHEDULER_QUOTA_RESET_ENABLED` | Ejecuta el trabajo de reinicio de la cuota de salida. | `false` | No | | `SCHEDULER_CLAIM_DEADLINE_ENABLED` | Ejecuta el trabajo de plazo de reclamo de DICT. | `false` | No | | `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Ejecuta la conciliación incremental de DICT. | `false` | No | | `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED` | Ejecuta la conciliación completa de DICT. | `false` | No | | `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED` | Ejecuta el trabajo de retención de auditoría de 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 | ## Descubrimiento e inventario de DICT El descubrimiento de reclamos entrantes se ejecuta solo cuando `SCHEDULER_ENABLED` y `SCHEDULER_INBOUND_DISCOVERY_ENABLED` son ambos `true`. Los demás workers de DICT que aparecen a continuación se ejecutan de forma independiente a `SCHEDULER_ENABLED`, cada uno con su propio interruptor explícito. | Variable | Descripción | Predeterminado | Obligatorio | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------- | | `SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES` | Umbral de antigüedad de readiness para los feeds de descubrimiento de reclamos entrantes. Debe ser mayor que cero. | `30` | No | | `DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS` | Umbral de brecha después del cual el feed de eventos de recuperación de fondos registra un marcador de bloqueo. Debe ser mayor que cero. | `168` | No | | `DICT_INFRACTION_DISCOVERY_ENABLED` | Habilita el recorrido de descubrimiento de infracciones de DICT. | `true` | No | | `DICT_INFRACTION_DISCOVERY_MAX_STALENESS_MINUTES` | Umbral de antigüedad de readiness para el descubrimiento de infracciones. Debe ser mayor que cero. | `15` | No | | `DICT_REFUND_DISCOVERY_ENABLED` | Habilita los recorridos de descubrimiento de devoluciones de DICT. | `true` | No | | `DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES` | Umbral de antigüedad de readiness para el descubrimiento de devoluciones. Debe ser mayor que cero. | `15` | No | | `DICT_PERSON_WATCHLIST_ENABLED` | Habilita el sondeo de documentos en la lista de vigilancia de personas de DICT. | `true` | No | | `DICT_PERSON_WATCHLIST_CADENCE_MINUTES` | Antigüedad mínima antes de que un documento vigilado se observe de nuevo. Debe ser mayor que cero. | `60` | No | | `DICT_PERSON_WATCHLIST_BATCH_LIMIT` | Máximo de documentos vigilados observados en un ciclo de sondeo. Debe ser mayor que cero. | `100` | No | | `DICT_PERSON_WATCHLIST_MAX_DOCUMENTS_PER_PARTICIPANT` | Máximo de documentos vigilados activos por participante. Debe ser mayor que cero. | `500` | No | | `DICT_PERSON_WATCHLIST_MAX_OBSERVATION_AGE_MINUTES` | Umbral de readiness para la observación más antigua de un documento vigilado. Debe ser mayor que cero. | `360` | No | | `DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES` | Observaciones fallidas consecutivas antes de poner en cuarentena un documento vigilado. Debe ser mayor que cero. | `6` | No | | `DICT_FRAUD_MARKER_INVENTORY_ENABLED` | Habilita el barrido de inventario de marcadores de fraude de DICT. | `true` | No | | `DICT_FRAUD_MARKER_INVENTORY_SWEEP_MINUTES` | Intervalo entre barridos de inventario de marcadores de fraude. Debe ser mayor que cero. | `60` | No | | `DICT_FRAUD_MARKER_INVENTORY_MAX_DOCUMENTS_PER_SWEEP` | Máximo de documentos conciliados en un barrido de inventario. Debe ser mayor que cero. | `200` | No | | `DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES` | Umbral de antigüedad de readiness para el inventario de marcadores de fraude. Debe ser mayor que cero. | `180` | No | ## Rate limiting, idempotencia y conectividad | Variable | Descripción | Predeterminado | Obligatorio | | ------------------------------------- | ----------------------------------------------------------------------------------- | -------------- | ------------------------------------- | | `RATE_LIMIT_ENABLED` | Habilita el rate limiting de solicitudes. | `true` | No | | `RATE_LIMIT_MAX` | Máximo de solicitudes por ventana. | `100` | No | | `RATE_LIMIT_EXPIRY_SEC` | Ventana de rate limit (segundos). | `60` | No | | `IDEMPOTENCY_RETRY_WINDOW_SEC` | Cuánto tiempo (segundos) se retiene una clave de idempotencia. | `86400` | No | | `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | Clave AES-256 para cifrar las respuestas de idempotencia almacenadas. Sensible. | — | Runtime protegido de SPI, DICT o Core | | `INFRA_CONNECT_TIMEOUT_SEC` | Timeout de conexión para las dependencias de infraestructura al iniciar (segundos). | `30` | No | ## Systemplane y configuración en tiempo de ejecución | Variable | Descripción | Predeterminado | Obligatorio | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------- | | `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 se ejecuta en modo solo variables de entorno, sin plano de administración. **SPI lo tiene habilitado 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/platform/systemplane/overview) para conocer la API, los espacios de nombres y los permisos requeridos. ## Observabilidad | Variable | Descripción | Predeterminado | Obligatorio | | -------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------- | -------------------------------- | | `ENABLE_TELEMETRY` | Habilita el tracing y las métricas de OpenTelemetry. | `false` | No | | `TELEMETRY_REQUIRED` | Falla el inicio si la telemetría no puede inicializarse. | `false` | No | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Endpoint del recolector 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 | Predeterminado | Obligatorio | | ----------------- | ----------------------------------------------------------------------------------------------------------------- | -------------- | ----------- | | `SWAGGER_ENABLED` | Sirve la especificación de OpenAPI y la interfaz de documentación de la API. Forzado a desactivado 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 conocer el contrato de las verificaciones.