> ## 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 SPI: runtime, conectividad SPI/DICT de BACEN, firma de mensajes y certificados, cifrado de PII, persistencia, streaming y seguridad.

Lerian SPI es la integración de mensajería nativa de Lerian para Pix, que alcanza el sistema de pagos instantáneos (SPI) de BACEN y el directorio DICT a través de la RSFN. Es un único desplegable con tres superficies que cooperan —el núcleo de liquidación SPI, el cliente DICT y BR Code—, por lo que su conjunto de variables es amplio. Todas las variables se definen en el momento del despliegue y requieren reiniciar el servicio. 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 debe definirse (de forma global o bajo la condición indicada). `—` significa que no hay valor por defecto.

<Note>
  La mayoría de las variables orientadas a BACEN están agrupadas por superficie mediante espacios de nombres: `BACEN_SPI_*` para el transporte de liquidación SPI, `BACEN_DICT_*` para el cliente DICT, `BACEN_BRCODE_*` para la firma JOSE de BR Code y `BACEN_ICOM_*` para el canal entrante de long-poll.
</Note>

## Runtime y servidor

| Variable                       | Descripción                                                                                                    | Valor por defecto                   | Requerida |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------- |
| `ENV_NAME`                     | Etiqueta del entorno de runtime. `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`). 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.            | —                                   | No        |
| `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. Habilítala en producción.                                      | `false`           | No                 |
| `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. | —                 | No        |

## 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.                                    | —                       | No                          |
| `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. Sensible.                     | —                       | No                          |

### TLS mutuo hacia BACEN

Los archivos `BACEN_TLS_*` respaldan el canal de TLS mutuo hacia BACEN y los comparten los clientes SPI y DICT.

| 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

Los mensajes SPI se firman digitalmente. 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 de firma.                                                                                  | —                 | No          |
| `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

Controla cómo se almacenan y referencian los payloads SPI grandes.

| Variable                                         | Descripción                                                 | Valor por defecto | Requerida |
| ------------------------------------------------ | ----------------------------------------------------------- | ----------------- | --------- |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND`                | Backend de almacenamiento de payloads (p. ej. `in_memory`). | `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 para cifrar los payloads almacenados. Sensible.   | —                 | No        |

## 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.                   | —                 | No        |
| `BACEN_ICOM_ISPB`                       | ISPB del participante para el canal entrante.  | —                 | No        |
| `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        |

## 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.                                           | —                       | No                |
| `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 para cifrar las intenciones de reclamo DICT almacenadas. Sensible. | —                       | No                |

## 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.                                         | —                 | No          |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE`          | Ruta a la clave privada de firma JOSE (backend de archivo). Sensible.      | —                 | Si `file`   |
| `BACEN_BRCODE_JOSE_KID`                       | Valor del encabezado identificador de clave JWS (`kid`).                   | —                 | No          |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH`        | Ruta al módulo PKCS#11.                                                    | —                 | Si `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL`        | Etiqueta del token PKCS#11.                                                | —                 | Si `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE`           | Ruta al archivo del PIN del token. Sensible.                               | —                 | Si `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL`          | Etiqueta de la clave de firma en el token.                                 | —                 | Si `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL`             | URL base del servicio KMIP.                                                | —                 | Si `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_VHSM`                 | Identificador del HSM virtual.                                             | —                 | Si `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`          | Usuario cripto de KMIP.                                                    | —                 | Si `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`    | Token del usuario cripto de KMIP. Sensible.                                | —                 | Si `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID de la clave privada de firma.                                          | —                 | Si `kmip`   |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`  | UID de la clave pública de firma.                                          | —                 | Si `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

<Warning>
  Cada variable de abajo es material sensible de clave o pepper para cifrar e indexar de forma ciega los datos personales en reposo. Nunca guardes en el repositorio ni registres en logs un valor; inyéctalo en el momento del despliegue mediante tu gestor de secretos. Rotar un pepper o una clave requiere una reindexación/recifrado planificado.
</Warning>

| Variable                            | Descripción                                                           | Valor por defecto | Requerida |
| ----------------------------------- | --------------------------------------------------------------------- | ----------------- | --------- |
| `DICT_KEY_PII_ENCRYPTION_KEY`       | Clave AES para la PII del titular de la clave DICT. Sensible.         | —                 | No        |
| `DICT_KEY_BLIND_INDEX_PEPPER`       | Pepper para el indexado ciego de la PII de las claves DICT. Sensible. | —                 | No        |
| `DICT_AUDIT_HASH_PEPPER`            | Pepper para el hashing de los registros de auditoría DICT. Sensible.  | —                 | No        |
| `AUDIT_HASH_PEPPER`                 | Pepper heredado de hash de auditoría. Sensible.                       | —                 | No        |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY`   | Clave AES para la PII de las partes responsables. Sensible.           | —                 | No        |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | Clave AES para la PII de las operaciones. Sensible.                   | —                 | No        |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper para el indexado ciego de la PII de las operaciones. Sensible. | —                 | No        |
| `BRCODE_PII_ENCRYPTION_KEY`         | Clave AES para la PII de BR Code. Sensible.                           | —                 | No        |
| `BRCODE_PII_BLIND_INDEX_PEPPER`     | Pepper para el indexado ciego de la PII de BR Code. Sensible.         | —                 | No        |

## 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.                                                | —                 | En producción |
| `POSTGRES_DB`                      | Nombre de la base de datos.                                                              | —                 | Sí            |
| `POSTGRES_SSLMODE`                 | Modo TLS de libpq. Usa `require` o más estricto en producción.                           | `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. Las variables de streaming (`STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_CLOUDEVENTS_SOURCE`, `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS`, `STREAMING_EVENT_POLICIES`) siguen el backbone compartido; consulta [Streaming y outbox](/es/reference/byoc-configuration#streaming-y-outbox). `STREAMING_BROKERS` es requerida siempre que `STREAMING_ENABLED=true`.

| 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_TOPIC`     | Topic que lee el consumidor de liquidación de BR Code. Se define por despliegue. | —                 | No        |
| `BRCODE_SETTLEMENT_CONSUMER_GROUP`     | Grupo de consumidores para la liquidación de BR Code.                            | —                 | No        |
| `BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID` | Client ID que el consumidor de liquidación presenta al broker.                   | —                 | 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        |
| `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 adjuntado a la telemetría exportada.                           | Valor por defecto del servicio | No                               |
| `OTEL_RESOURCE_SERVICE_VERSION`        | Etiqueta de versión del servicio.                                                  | Por release                    | No                               |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Etiqueta del entorno de despliegue.                                                | `development`                  | No                               |
| `OTEL_LIBRARY_NAME`                    | Nombre de la biblioteca de instrumentación.                                        | 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                               |

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