Variables de entorno

Variables de entorno para Lerian SPI: runtime, conectividad SPI/DICT del BACEN, firma de mensajes y certificados, cifrado de PII, persistencia y streaming.

Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Alcanza el sistema de pagos instantáneos (SPI) de BACEN y el directorio de claves DICT a través de la RSFN. Se entrega como cuatro binarios de runtime —spi, dict, brcode y core—, por lo que su conjunto de variables es amplio.

El servicio lee cada variable al arrancar. Cuando systemplane está activo —el valor por defecto— puede sobrescribir un subconjunto en tiempo de ejecución sin reiniciar. El resto de las variables requieren un reinicio para cambiar. Para los ajustes que se comportan igual en todos los servicios Go de Lerian —postura de despliegue, almacenes de datos, multi-tenancy, telemetría, streaming— consulta la referencia de configuración BYOC.

En las tablas siguientes, Requerida marca una variable que debes definir —de forma global o bajo la condición indicada—. — significa que no hay valor por defecto.

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

​

Runtime y servidor

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

​

Autenticación

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

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

​

Callback de BACEN (entrante desde SPI)

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

​

Transporte de liquidación SPI (BACEN_SPI_*)

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

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

​

TLS mutuo hacia BACEN

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

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

​

Firma de mensajes y certificados

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

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

​

Validación de certificados (OCSP/CRL)

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

​

Resolutor de payloads

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

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

​

Canal entrante (BACEN_ICOM_*)

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

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

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

​

Cliente DICT (BACEN_DICT_*)

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

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

​

Firma JOSE de BR Code (BACEN_BRCODE_JOSE_*)

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

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

​

Cifrado y hashing de PII

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

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

​

PostgreSQL

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

​

Redis

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

​

Outbox y streaming

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

Variable	Descripción	Valor por defecto	Requerida
OUTBOX_ENABLED	Habilita el despachador del outbox transaccional.	true	No
OUTBOX_DISPATCH_INTERVAL_MS	Intervalo entre ciclos de despacho (milisegundos).	2000	No
OUTBOX_BATCH_SIZE	Filas drenadas por ciclo de despacho.	50	No
OUTBOX_MAX_DISPATCH_ATTEMPTS	Intentos de despacho antes de aparcar un evento.	10	No
OUTBOX_PROCESSING_TIMEOUT_MS	Tiempo de espera de procesamiento por lote (milisegundos).	600000	No
OUTBOX_RETRY_WINDOW_MS	Ventana de reintento antes de recuperar una fila atascada (milisegundos).	300000	No
BRCODE_SETTLEMENT_CONSUMER_ENABLED	Habilita el consumidor de liquidación de BR Code. Requiere STREAMING_BROKERS.	false	No
BRCODE_SETTLEMENT_CONSUMER_TOPIC	Topic que lee el consumidor de liquidación de BR Code.	br-spi.spi.payment	No
BRCODE_SETTLEMENT_CONSUMER_GROUP	Grupo de consumidores para la liquidación de BR Code.	br-spi-brcode-settlement-consumer	No
BRCODE_SETTLEMENT_CONSUMER_CLIENT_ID	Client ID que el consumidor de liquidación presenta al broker.	—	No
SPI_PARTICIPANT_CONSUMER_ENABLED	Habilita el consumidor de solicitudes de participante de Core a SPI. Requiere STREAMING_BROKERS, transporte BACEN y persistencia cuando está habilitado.	false	No
SPI_PARTICIPANT_CONSUMER_TOPIC	Topic que transporta las solicitudes de participante de Core.	br-spi.core.participant	No
SPI_PARTICIPANT_CONSUMER_GROUP	Grupo de consumidores durable para solicitudes de participante.	br-spi-participant-request-consumer	No
SPI_PARTICIPANT_CONSUMER_CLIENT_ID	Client ID que el consumidor de solicitudes de participante presenta al broker. Recurre al client ID compartido de streaming.	Client ID compartido	No

​

Programadores

Trabajos en segundo plano, cada uno controlado de forma independiente. Todos desactivados por defecto.

Variable	Descripción	Valor por defecto	Requerida
SCHEDULER_ENABLED	Interruptor maestro del subsistema de programación.	false	No
SCHEDULER_MED_DEADLINE_ENABLED	Ejecuta el trabajo de plazo del MED (devolución especial).	false	No
SCHEDULER_QUOTA_RESET_ENABLED	Ejecuta el trabajo de reinicio de la cuota saliente.	false	No
SCHEDULER_CLAIM_DEADLINE_ENABLED	Ejecuta el trabajo de plazo de reclamos DICT.	false	No
SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED	Ejecuta la reconciliación DICT incremental.	false	No
SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED	Ejecuta la reconciliación DICT completa.	false	No
SCHEDULER_DICT_AUDIT_RETENTION_ENABLED	Ejecuta el trabajo de retención de auditoría DICT.	false	No
SCHEDULER_INBOUND_DISCOVERY_ENABLED	Ejecuta el trabajo de descubrimiento de mensajes entrantes.	false	No
SCHEDULER_APPROVAL_EXPIRY_ENABLED	Ejecuta el barrido de expiración de aprobaciones.	false	No
SCHEDULER_PORTABILITY_DEADLINE_ENABLED	Ejecuta el trabajo de plazo de portabilidad.	false	No

​

Limitación de tasa, idempotencia y conectividad

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

​

Systemplane y configuración en tiempo de ejecución

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

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