Variables de entorno

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

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 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 para conocer el contrato de las verificaciones.

​Tiempo de ejecución y servidor

​Autenticación

​Callback de BACEN (entrante desde SPI)

​Transporte de liquidación de SPI (BACEN_SPI_*)

​TLS mutuo con BACEN

​Firma de mensajes y certificados

​Validación de certificados (OCSP/CRL)

​Resolutor de payload

​Canal entrante (BACEN_ICOM_*)

​Cliente DICT (BACEN_DICT_*)

​Firma JOSE de BR Code (BACEN_BRCODE_JOSE_*)

​Cifrado y hashing de PII

​PostgreSQL

​Redis

​Outbox y streaming

​Programadores

​Descubrimiento e inventario de DICT

​Rate limiting, idempotencia y conectividad

​Systemplane y configuración en tiempo de ejecución

​Observabilidad

​Documentación

​Salud y readiness

Tiempo de ejecución y servidor

Autenticación

Callback de BACEN (entrante desde SPI)

Transporte de liquidación de SPI (`BACEN_SPI_*`)

TLS mutuo con BACEN

Firma de mensajes y certificados

Validación de certificados (OCSP/CRL)

Resolutor de payload

Canal entrante (`BACEN_ICOM_*`)

Cliente DICT (`BACEN_DICT_*`)

Firma JOSE de BR Code (`BACEN_BRCODE_JOSE_*`)

Cifrado y hashing de PII

PostgreSQL

Redis

Outbox y streaming

Programadores

Descubrimiento e inventario de DICT

Rate limiting, idempotencia y conectividad

Systemplane y configuración en tiempo de ejecución

Observabilidad

Documentación

Salud y readiness