Variables de entorno

Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Alcanza el sistema de pagos instantáneos (SPI) de BACEN y el directorio de claves DICT a través de la RSFN. Se entrega como cuatro binarios de runtime —spi, dict, brcode y core—, por lo que su conjunto de variables es amplio. El servicio lee cada variable al arrancar. Cuando systemplane está activo —el valor por defecto— puede sobrescribir un subconjunto en tiempo de ejecución sin reiniciar. El resto de las variables requieren un reinicio para cambiar. Para los ajustes que se comportan igual en todos los servicios Go de Lerian —postura de despliegue, almacenes de datos, multi-tenancy, telemetría, streaming— consulta la referencia de configuración BYOC. En las tablas siguientes, Requerida marca una variable que debes definir —de forma global o bajo la condición indicada—. — significa que no hay valor por defecto.

La mayoría de las variables orientadas a BACEN llevan un prefijo de superficie: BACEN_SPI_* para el transporte de liquidación SPI, BACEN_DICT_* para el cliente DICT, BACEN_BRCODE_JOSE_* para la firma JOSE de BR Code y BACEN_ICOM_* para el canal entrante de long-poll.

Runtime y servidor

Variable	Descripción	Valor por defecto	Requerida
`ENV_NAME`	Etiqueta del entorno de runtime. Si no está definida, se resuelve como `development`; un `none` explícito no es válido. `production` activa controles de seguridad más estrictos.	`development`	No
`LOG_LEVEL`	Verbosidad de los logs (`debug`, `info`, `warn`, `error`).	`info`	No
`SERVER_ADDRESS`	Dirección de escucha HTTP principal (`host:port` o `:port`). Liveness, readiness y systemplane se enlazan a este puerto.	`:8080`	No
`HTTP_BODY_LIMIT_BYTES`	Tamaño máximo del cuerpo de la petición en bytes.	`1048576`	No
`PUBLIC_BASE_URL`	URL base del servicio accesible desde el exterior, usada para construir URLs de callback absolutas y enlaces de payload de BR Code.	—	En producción o si JOSE de BR Code está habilitado
`ACCESS_CONTROL_ALLOW_ORIGIN`	Orígenes CORS permitidos.	`http://localhost:3000`	No
`ACCESS_CONTROL_ALLOW_METHODS`	Métodos CORS permitidos.	`GET,POST,PUT,PATCH,DELETE,OPTIONS`	No
`ACCESS_CONTROL_ALLOW_HEADERS`	Encabezados de petición CORS permitidos.	(conjunto estándar)	No
`TRUSTED_PROXIES`	IPs/CIDR de proxy de confianza, separados por comas, autorizados a establecer la IP real del cliente.	—	No
`SERVER_TLS_CERT_FILE`	Ruta al certificado TLS del servidor. Se define junto con el archivo de clave.	—	No
`SERVER_TLS_KEY_FILE`	Ruta a la clave privada TLS del servidor. Sensible.	—	No
`SERVER_TLS_CLIENT_CA_FILE`	Archivo CA para verificar los certificados de cliente (TLS mutuo).	—	No
`TLS_TERMINATED_UPSTREAM`	Defínela como `true` cuando el TLS lo termina un balanceador de carga o un proxy inverso.	`false`	No

Autenticación

Lerian SPI autoriza las rutas protegidas —incluida la API de administración de systemplane— a través de Access Manager.

Variable	Descripción	Valor por defecto	Requerida
`AUTH_ENABLED`	Exige autenticación de Access Manager en las rutas protegidas.	`false`	En producción
`PLUGIN_AUTH_ADDRESS`	Dirección del servicio Access Manager.	—	Si está habilitada
`AUTH_TRUST_UPSTREAM_METADATA`	Confía en los metadatos de identidad reenviados por un proxy upstream. Déjala en `false` salvo que el proxy sea de confianza.	`false`	No

Callback de BACEN (entrante desde SPI)

Variable	Descripción	Valor por defecto	Requerida
`BACEN_CALLBACK_TRUSTED_PROXY_CIDRS`	CIDR de confianza como origen de los callbacks de BACEN.	—	No
`BACEN_CALLBACK_MTLS_HEADER_SECRET`	Secreto compartido que prueba que el upstream terminó el TLS mutuo del callback. Sensible.	—	Si el consumidor ICOM primario está habilitado

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

Conexión al endpoint de liquidación SPI de BACEN a través de la RSFN, con un endpoint secundario opcional y el endpoint de archivo (ARQ).

Variable	Descripción	Valor por defecto	Requerida
`BACEN_SPI_ENDPOINT`	URL del endpoint SPI principal.	`http://localhost:9900`	Sí (SPI en vivo)
`BACEN_SPI_SECONDARY_ENDPOINT`	URL del endpoint SPI secundario para failover.	—	Si el consumidor ICOM secundario está habilitado
`BACEN_ARQ_ENDPOINT`	URL del endpoint ARQ (archivo/lote).	—	No
`BACEN_SPI_PARTICIPANT_ISPB`	El ISPB del participante para la superficie SPI.	—	Sí (SPI en vivo)
`BACEN_SPI_ALLOWED_ENDPOINT_HOSTS`	Lista de permitidos de hosts que el cliente SPI puede alcanzar (protección SSRF).	—	No
`BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS`	Lista de permitidos para el endpoint secundario.	—	No
`BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS`	Lista de permitidos para el endpoint ARQ.	—	No
`BACEN_SPI_TIMEOUT_SEC`	Tiempo de espera de la petición (segundos).	`30`	No
`BACEN_SPI_INITIATION_TIMEOUT_MS`	Tiempo de espera de la iniciación de pago (milisegundos).	`150`	No
`BACEN_SPI_INBOUND_CALLBACK_TIMEOUT_MS`	Tiempo de espera del procesamiento del callback entrante (milisegundos).	`250`	No
`BACEN_SPI_RETRY_ATTEMPTS`	Intentos de reintento ante un fallo de transporte.	`3`	No
`BACEN_SPI_RETRY_INITIAL_BACKOFF_MS`	Backoff inicial de reintento (milisegundos).	`500`	No
`BACEN_SPI_RETRY_MAX_BACKOFF_MS`	Backoff máximo de reintento (milisegundos).	`5000`	No
`BACEN_SPI_OUTBOUND_QUOTA_ENABLED`	Habilita la cuota de tasa saliente del lado cliente.	`false`	No
`BACEN_SPI_OUTBOUND_QUOTA_LIMIT`	Cuota saliente sostenida (peticiones).	—	Si la cuota está habilitada
`BACEN_SPI_OUTBOUND_QUOTA_BURST`	Margen de ráfaga por encima de la cuota.	—	Si la cuota está habilitada
`BACEN_SPI_CATALOGUE_VERSION`	Versión del catálogo de mensajes SPI de BACEN.	`5.12.1`	No
`BACEN_SPI_XSD_DIR`	Directorio de los esquemas XSD de BACEN incluidos para el catálogo.	Ruta incluida	No
`BACEN_SPI_CATALOGUE_ROOT`	Raíz de sobrescritura para el catálogo de mensajes.	—	No
`BACEN_SPI_INTERNAL_CALLBACK_SECRET`	Secreto compartido para la vía de callback interna. Mínimo 32 caracteres cuando se define. Sensible.	—	En producción o si el consumidor ICOM primario está habilitado

TLS mutuo hacia BACEN

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

Variable	Descripción	Valor por defecto	Requerida
`BACEN_TLS_CERT_FILE`	Certificado de cliente presentado a BACEN.	—	Sí (en vivo)
`BACEN_TLS_KEY_FILE`	Clave privada del cliente. Sensible.	—	Sí (en vivo)
`BACEN_TLS_CA_FILE`	Paquete de CA usado para verificar el certificado de servidor de BACEN.	—	Sí (en vivo)

Firma de mensajes y certificados

Lerian SPI firma digitalmente sus mensajes salientes. Elige un backend de custodia con BACEN_SPI_SIGNER_KIND.

Variable	Descripción	Valor por defecto	Requerida
`BACEN_SPI_SIGNER_KIND`	Backend de custodia de firma: `file`, `pkcs11` o `kmip`. Usa un backend de hardware en producción.	`file`	No
`BACEN_SPI_SIGNER_COMMON_NAME`	Nombre común esperado del certificado de firma.	—	No
`BACEN_SPI_SIGNING_CERT_FILE`	Ruta al certificado vinculado a la clave de firma. Se requiere para `pkcs11` o `kmip`; con `file`, recurre a `BACEN_TLS_CERT_FILE` cuando no se define.	`BACEN_TLS_CERT_FILE` (`file`)	Si `pkcs11` o `kmip`
`BACEN_SPI_INBOUND_SIGNER_COMMON_NAME`	Nombre común esperado del firmante en los mensajes entrantes.	—	No
`CERT_READINESS_MIN_DAYS`	Días mínimos hasta la expiración antes de que la comprobación de readiness del certificado informe `degraded`.	`14`	No
`BACEN_SPI_PKCS11_MODULE_PATH`	Ruta a la biblioteca del módulo PKCS#11.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_TOKEN_LABEL`	Etiqueta del token PKCS#11.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_PIN_FILE`	Ruta a un archivo que contiene el PIN del token. Sensible.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_KEY_LABEL`	Etiqueta de la clave de firma en el token.	—	Si `pkcs11`
`BACEN_SPI_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si `kmip`
`BACEN_SPI_KMIP_VHSM`	Identificador del HSM virtual.	—	Si `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER_TOKEN`	Token del usuario cripto de KMIP. Sensible.	—	Si `kmip`
`BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si `kmip`
`BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si `kmip`
`BACEN_SPI_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP.	`false`	No

Validación de certificados (OCSP/CRL)

Variable	Descripción	Valor por defecto	Requerida
`BACEN_SPI_OCSP_MODE`	Modo de comprobación de revocación de certificados (p. ej. `soft_fail`).	`soft_fail`	No
`BACEN_SPI_OCSP_TIMEOUT_MS`	Tiempo de espera de la petición OCSP (milisegundos).	`3000`	No
`BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC`	Tope del TTL de la respuesta OCSP en caché (segundos).	`3600`	No
`BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC`	TTL de la caché de CRL (segundos).	`3600`	No

Resolutor de payloads

Estas variables controlan cómo el servicio almacena y referencia los payloads SPI grandes.

Variable	Descripción	Valor por defecto	Requerida
`BACEN_SPI_PAYLOAD_RESOLVER_KIND`	Backend de almacenamiento de payloads: `in_memory` o `postgres`. Los entornos de tipo producción rechazan `in_memory` — usa un backend durable.	`in_memory`	No
`BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES`	Máximo de bytes retenidos por el resolutor en memoria.	`134217728`	No
`BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC`	TTL de retención de los payloads resueltos (segundos).	`86400`	No
`BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY`	Clave AES-256 para cifrar los payloads almacenados. Sensible.	—	Si el tipo es `postgres`

Canal entrante (`BACEN_ICOM_*`)

Canal de long-poll para los mensajes que BACEN devuelve al participante.

Variable	Descripción	Valor por defecto	Requerida
`BACEN_ICOM_BASE_URL`	URL base del canal entrante.	—	Si el consumidor ICOM primario está habilitado
`BACEN_ICOM_ISPB`	ISPB del participante para el canal entrante.	—	Si el consumidor ICOM primario está habilitado
`BACEN_ICOM_CONSUMER_ENABLED`	Habilita el consumidor entrante principal.	`false`	No
`BACEN_ICOM_SECONDARY_CONSUMER_ENABLED`	Habilita el consumidor entrante secundario.	`false`	No
`BACEN_ICOM_LONGPOLL_TIMEOUT_MS`	Tiempo de espera del long-poll (milisegundos).	`90000`	No

Con BACEN_ICOM_CONSUMER_ENABLED=true, el arranque también requiere un backend de persistencia configurado, BACEN_SPI_INTERNAL_CALLBACK_SECRET y BACEN_CALLBACK_MTLS_HEADER_SECRET. Con BACEN_ICOM_SECONDARY_CONSUMER_ENABLED=true, también requiere BACEN_SPI_SECONDARY_ENDPOINT.

Cliente DICT (`BACEN_DICT_*`)

Cliente para el directorio de claves Pix (DICT) de BACEN, incluido el endpoint antifraude (NP).

Variable	Descripción	Valor por defecto	Requerida
`BACEN_DICT_ENDPOINT`	URL del endpoint DICT.	`http://localhost:9900`	Sí (DICT en vivo)
`BACEN_DICT_PARTICIPANT_ISPB`	ISPB del participante para la superficie DICT.	—	Sí (DICT en vivo)
`BACEN_DICT_ALLOWED_ENDPOINT_HOSTS`	Lista de permitidos de hosts que el cliente DICT puede alcanzar.	—	No
`BACEN_DICT_TIMEOUT_SEC`	Tiempo de espera de la petición DICT (segundos).	`10`	No
`BACEN_DICT_NP_ENDPOINT`	URL del endpoint antifraude (NP).	—	No
`BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS`	Lista de permitidos para el endpoint NP.	—	No
`BACEN_DICT_SIGNER_KIND`	Backend de custodia de firma DICT: `file`, `pkcs11` o `kmip`.	`file`	No
`BACEN_DICT_SIGNING_CERT_FILE`	Ruta al certificado de firma DICT.	—	Para la ruta de custodia DICT seleccionada
`BACEN_DICT_SIGNING_KEY_FILE`	Ruta a la clave privada de firma DICT (backend de archivo). Sensible.	—	Si `file`
`BACEN_DICT_VERIFY_CERT_FILE`	Certificado usado para verificar las respuestas DICT.	—	No
`BACEN_DICT_PKCS11_MODULE_PATH`	Ruta al módulo PKCS#11.	—	Si `pkcs11`
`BACEN_DICT_PKCS11_TOKEN_LABEL`	Etiqueta del token PKCS#11.	—	Si `pkcs11`
`BACEN_DICT_PKCS11_PIN_FILE`	Ruta al archivo del PIN del token. Sensible.	—	Si `pkcs11`
`BACEN_DICT_PKCS11_KEY_LABEL`	Etiqueta de la clave de firma en el token.	—	Si `pkcs11`
`BACEN_DICT_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si `kmip`
`BACEN_DICT_KMIP_VHSM`	Identificador del HSM virtual.	—	Si `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER_TOKEN`	Token del usuario cripto de KMIP. Sensible.	—	Si `kmip`
`BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si `kmip`
`BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si `kmip`
`BACEN_DICT_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP.	`false`	No
`BACEN_DICT_INTENT_ENCRYPTION_KEY`	Clave AES-256 para cifrar las intenciones de reclamo DICT almacenadas. Sensible.	—	En producción

Firma JOSE de BR Code (`BACEN_BRCODE_JOSE_*`)

Firma los payloads dinámicos de BR Code (JWS).

Variable	Descripción	Valor por defecto	Requerida
`BACEN_BRCODE_JOSE_SIGNER_KIND`	Backend de custodia de firma JOSE: `file`, `pkcs11` o `kmip`.	—	No
`BACEN_BRCODE_JOSE_SIGNING_CERT_FILE`	Ruta al certificado de firma JOSE.	—	Si JOSE de BR Code está habilitado
`BACEN_BRCODE_JOSE_SIGNING_KEY_FILE`	Ruta a la clave privada de firma JOSE (backend de archivo). Sensible.	—	Si JOSE de BR Code está habilitado con `file`
`BACEN_BRCODE_JOSE_KID`	Valor del encabezado identificador de clave JWS (`kid`).	—	Si JOSE de BR Code está habilitado
`BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH`	Ruta al módulo PKCS#11.	—	Si JOSE de BR Code está habilitado con `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL`	Etiqueta del token PKCS#11.	—	Si JOSE de BR Code está habilitado con `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_PIN_FILE`	Ruta al archivo del PIN del token. Sensible.	—	Si JOSE de BR Code está habilitado con `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL`	Etiqueta de la clave de firma en el token.	—	Si JOSE de BR Code está habilitado con `pkcs11`
`BACEN_BRCODE_JOSE_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_VHSM`	Identificador del HSM virtual.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`	Token del usuario cripto de KMIP. Sensible.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si JOSE de BR Code está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo DigestInfo de ASN.1 antes de la llamada de firma KMIP.	`false`	No

Cifrado y hashing de PII

Cada variable de abajo contiene material sensible de clave o pepper. Protege los datos personales en reposo mediante cifrado e indexado ciego. Nunca guardes en el repositorio ni registres en logs un valor. Inyéctalo en el momento del despliegue mediante tu gestor de secretos. Una rotación de pepper o de clave requiere una reindexación o un recifrado planificado.

Variable	Descripción	Valor por defecto	Requerida
`DICT_KEY_PII_ENCRYPTION_KEY`	Clave AES para la PII del titular de la clave DICT. Sensible.	—	Runtime DICT protegido
`DICT_KEY_BLIND_INDEX_PEPPER`	Pepper para el indexado ciego de la PII de las claves DICT. Sensible.	—	Runtime DICT protegido
`DICT_AUDIT_HASH_PEPPER`	Pepper para el hashing de los registros de auditoría DICT. Sensible.	—	Runtime protegido
`AUDIT_HASH_PEPPER`	Pepper heredado de hash de auditoría. Sensible.	—	Runtime protegido
`SPI_RESPONSIBLES_ENCRYPTION_KEY`	Clave AES para la PII de las partes responsables. Sensible.	—	Runtime SPI protegido
`SPI_OPERATIONS_PII_ENCRYPTION_KEY`	Clave AES-256 para la PII de las operaciones. Sensible. El servicio SPI se niega a iniciar si falta o no tiene un formato válido.	—	Sí — servicio SPI en todos los entornos
`SPI_OPERATIONS_BLIND_INDEX_PEPPER`	Pepper para el indexado ciego de la PII de las operaciones. Sensible. Debe tener al menos 32 caracteres; el servicio SPI se niega a iniciar si falta o es más corto.	—	Sí — servicio SPI en todos los entornos
`BRCODE_PII_ENCRYPTION_KEY`	Clave AES para la PII de BR Code. Sensible.	—	Runtime BR Code protegido
`BRCODE_PII_BLIND_INDEX_PEPPER`	Pepper para el indexado ciego de la PII de BR Code. Sensible.	—	Runtime BR Code protegido

PostgreSQL

Variable	Descripción	Valor por defecto	Requerida
`POSTGRES_HOST`	Host principal de PostgreSQL.	`localhost`	Sí
`POSTGRES_PORT`	Puerto principal de PostgreSQL.	`5432`	No
`POSTGRES_USER`	Usuario de la base de datos.	`brspi`	No
`POSTGRES_PASSWORD`	Contraseña de la base de datos. Sensible. Usa un secreto explícito en producción.	Contraseña de desarrollo en código	No
`POSTGRES_DB`	Nombre de la base de datos.	`brspi`	No
`POSTGRES_SSLMODE`	Modo TLS de libpq. Para conexiones remotas de producción, usa `verify-full` con una CA de confianza; `require` cifra el canal pero no verifica la identidad del servidor.	`disable`	No
`POSTGRES_MAX_OPEN_CONNS`	Máximo de conexiones abiertas.	`25`	No
`POSTGRES_MAX_IDLE_CONNS`	Máximo de conexiones inactivas.	`5`	No
`POSTGRES_CONN_MAX_LIFETIME_MINS`	Vida máxima de la conexión (minutos).	`30`	No
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	Tiempo máximo de inactividad de la conexión (minutos).	`5`	No
`POSTGRES_CONNECT_TIMEOUT_SEC`	Tiempo de espera de conexión (segundos).	`10`	No
`POSTGRES_REPLICA_HOST`	Host de réplica de lectura opcional. Los demás campos de réplica recurren a la primaria.	—	No
`POSTGRES_REPLICA_PORT`	Puerto de la réplica.	—	No
`POSTGRES_REPLICA_USER`	Usuario de la réplica.	—	No
`POSTGRES_REPLICA_PASSWORD`	Contraseña de la réplica. Sensible.	—	No
`POSTGRES_REPLICA_DB`	Nombre de la base de datos de la réplica.	—	No
`POSTGRES_REPLICA_SSLMODE`	Modo TLS de la réplica.	—	No

Redis

Variable	Descripción	Valor por defecto	Requerida
`REDIS_HOST`	Host y puerto de Redis.	`localhost:6379`	No
`REDIS_MASTER_NAME`	Nombre del master de Sentinel (si se usa Sentinel).	—	No
`REDIS_PASSWORD`	Contraseña de Redis. Sensible.	—	No
`REDIS_DB`	Número de base de datos de Redis.	`0`	No
`REDIS_PROTOCOL`	Versión del protocolo de Redis (2 o 3).	`3`	No
`REDIS_TLS`	Habilita el TLS hacia Redis.	`false`	No
`REDIS_CA_CERT`	Certificado CA para el TLS de Redis.	—	No
`REDIS_POOL_SIZE`	Tamaño del pool de conexiones.	`10`	No
`REDIS_MIN_IDLE_CONNS`	Mínimo de conexiones inactivas.	`2`	No
`REDIS_READ_TIMEOUT_MS`	Tiempo de espera de lectura (milisegundos).	`3000`	No
`REDIS_WRITE_TIMEOUT_MS`	Tiempo de espera de escritura (milisegundos).	`3000`	No
`REDIS_DIAL_TIMEOUT_MS`	Tiempo de espera de conexión (milisegundos).	`5000`	No

Outbox y streaming

Lerian SPI publica eventos a través de un outbox transaccional y de un productor de lib-streaming, y consume eventos de liquidación para BR Code. El consumidor de liquidación de BR Code se ejecuta de forma incondicional. El streaming no tiene un interruptor de habilitación: STREAMING_BROKERS es obligatorio al iniciar, incluso cuando OUTBOX_ENABLED=false. Configura los ajustes compartidos STREAMING_CLOUDEVENTS_SOURCE, STREAMING_COMPRESSION, STREAMING_REQUIRED_ACKS y STREAMING_EVENT_POLICIES como se describe en Streaming y outbox.

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
`SPI_PARTICIPANT_CONSUMER_ENABLED`	Habilita el consumidor de solicitudes de participante de Core a SPI. Se suscribe al stream de aplicación del productor Core; el topic 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 durable para solicitudes de participante.	Valor predeterminado interno del servicio	No
`SPI_PARTICIPANT_CONSUMER_CLIENT_ID`	Client ID que el consumidor de solicitudes de participante presenta al broker. Recurre al client ID compartido de streaming.	Client ID compartido	No

Programadores

Trabajos en segundo plano, cada uno controlado de forma independiente. Los trabajos controlados por el programador que aparecen abajo están desactivados por defecto. Los trabajadores de descubrimiento e inventario de DICT tienen sus propios controles en la sección siguiente.

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

Descubrimiento e inventario de DICT

El descubrimiento de reclamos entrantes se ejecuta solo cuando tanto SCHEDULER_ENABLED como SCHEDULER_INBOUND_DISCOVERY_ENABLED son true. Los demás trabajadores de DICT a continuación se ejecutan independientemente de SCHEDULER_ENABLED, cada uno con su propio interruptor de habilitación explícito.

Variable	Descripción	Valor por defecto	Requerida
`SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES`	Umbral de obsolescencia 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 tras el cual el feed de eventos de recuperación de fondos registra un marcador bloqueado. 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 obsolescencia 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 obsolescencia de readiness para el descubrimiento de devoluciones. Debe ser mayor que cero.	`15`	No
`DICT_PERSON_WATCHLIST_ENABLED`	Habilita el sondeo de documentos de la lista de vigilancia de personas de DICT.	`true`	No
`DICT_PERSON_WATCHLIST_CADENCE_MINUTES`	Antigüedad mínima antes de volver a observar un documento vigilado. 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`	Fallos de observación consecutivos 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 del 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 obsolescencia de readiness para el inventario de marcadores de fraude. Debe ser mayor que cero.	`180`	No

Limitación de tasa, idempotencia y conectividad

Variable	Descripción	Valor por defecto	Requerida
`RATE_LIMIT_ENABLED`	Habilita la limitación de tasa de peticiones.	`true`	No
`RATE_LIMIT_MAX`	Máximo de peticiones por ventana.	`100`	No
`RATE_LIMIT_EXPIRY_SEC`	Ventana de limitación de tasa (segundos).	`60`	No
`IDEMPOTENCY_RETRY_WINDOW_SEC`	Cuánto tiempo (segundos) se conserva una clave de idempotencia.	`86400`	No
`IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY`	Clave AES-256 para cifrar las respuestas de idempotencia almacenadas. Sensible.	—	Runtime SPI, DICT o Core protegido
`INFRA_CONNECT_TIMEOUT_SEC`	Tiempo de espera de conexión para las dependencias de infraestructura al arrancar (segundos).	`30`	No

Systemplane y configuración en tiempo de ejecución

Variable	Descripción	Valor por defecto	Requerida
`SYSTEMPLANE_ENABLED`	Habilita la API de administración de configuración en tiempo de ejecución de systemplane, montada en `/v1/system` en el puerto principal. Cuando es `false`, el servicio funciona en modo solo-entorno, sin plano de administración. SPI lo activa por defecto, a diferencia de la mayoría de los servicios de Lerian, donde systemplane está desactivado por defecto.	`true`	No

Consulta Systemplane para la API, los espacios de nombres y los permisos requeridos.

Observabilidad

Variable	Descripción	Valor por defecto	Requerida
`ENABLE_TELEMETRY`	Habilita el tracing y las métricas de OpenTelemetry.	`false`	No
`TELEMETRY_REQUIRED`	Falla el arranque si la telemetría no puede inicializarse.	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint del colector OTLP.	`localhost:4317`	Si la telemetría está habilitada
`OTEL_RESOURCE_SERVICE_NAME`	Nombre del servicio adjunto a la telemetría exportada.	Predeterminado del servicio	No
`OTEL_RESOURCE_SERVICE_VERSION`	Etiqueta de versión del servicio.	`1.0.0`	No
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Etiqueta del entorno de despliegue.	`development`	No
`OTEL_LIBRARY_NAME`	Nombre de la biblioteca de instrumentación.	Predeterminado del servicio	No
`METRICS_PROMETHEUS_ENABLED`	Expone un endpoint de scrape de Prometheus dedicado.	`false`	No
`METRICS_PROMETHEUS_ADDRESS`	Dirección de escucha del endpoint de Prometheus. Se enlaza a loopback por defecto.	`127.0.0.1:9090`	No

Documentación

Variable	Descripción	Valor por defecto	Requerida
`SWAGGER_ENABLED`	Sirve la especificación OpenAPI y la interfaz de documentación de la API. Se fuerza a desactivarse en producción.	`false`	No

Salud y readiness

Lerian SPI expone GET /health (liveness), GET /readyz (readiness) y GET /version en el puerto HTTP principal. /metrics se ejecuta en su propio listener cuando está habilitado. Consulta Salud y readiness para el contrato de las sondas.

Resumen

Lerian SPI — mensajería nativa

JD — interfaz (Pix directo)

BTG — interfaz (Pix indirecto)

Variables de entorno

Runtime y servidor

Autenticación

Callback de BACEN (entrante desde SPI)

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

TLS mutuo hacia BACEN

Firma de mensajes y certificados

Validación de certificados (OCSP/CRL)

Resolutor de payloads

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

Limitación de tasa, idempotencia y conectividad

Systemplane y configuración en tiempo de ejecución

Observabilidad

Documentación

Salud y readiness

​Runtime y servidor

​Autenticación

​Callback de BACEN (entrante desde SPI)

​Transporte de liquidación SPI (BACEN_SPI_*)

​TLS mutuo hacia BACEN

​Firma de mensajes y certificados

​Validación de certificados (OCSP/CRL)

​Resolutor de payloads

​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

​Limitación de tasa, idempotencia y conectividad

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

​Observabilidad

​Documentación

​Salud y readiness

Runtime y servidor

Autenticación

Callback de BACEN (entrante desde SPI)

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

TLS mutuo hacia BACEN

Firma de mensajes y certificados

Validación de certificados (OCSP/CRL)

Resolutor de payloads

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

Limitación de tasa, idempotencia y conectividad

Systemplane y configuración en tiempo de ejecución

Observabilidad

Documentación

Salud y readiness