Variables de entorno

Variables de entorno en tiempo de despliegue para Lerian SPI: conectividad BACEN SPI/DICT, certificados de firma ISO 20022, cifrado de PII, persistencia y streaming.

Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Llega al sistema de pagos instantáneos de BACEN (SPI) y al directorio de claves DICT a través de la RSFN. Incluye cuatro binarios en tiempo de ejecución (spi, dict, brcode y core), por lo que su conjunto de variables es amplio.

El servicio lee todas las variables al iniciar. Un valor que no se puede leer en su tipo, como yes en un interruptor, detiene el inicio. 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, telemetría), consulta Elementos esenciales de configuración de BYOC.

En las tablas siguientes, Obligatorio marca una variable que debes configurar, siempre (Sí) o bajo la condición indicada. — significa que no tiene valor predeterminado. Las condiciones usan tres términos:

• En vivo: el endpoint de BACEN usa https. Un entorno local también acepta un endpoint http.
• Entorno local: ENV_NAME es development, local o test.
• Entorno protegido: ENV_NAME es production, prod, staging, stage, pre-prod, preprod, pre-production o preproduction.

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 como development. Un none explícito no es válido.	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 desde el exterior. Construye los enlaces de payload de BR Code y la URL del conjunto de claves JWS. La clave brcode.server/public_base_url de systemplane la anula en tiempo de ejecución.	—	En un entorno protegido o si BR Code JOSE está habilitado
ACCESS_CONTROL_ALLOW_ORIGIN	Orígenes CORS permitidos, separados por coma. Cada entrada es un origen exacto scheme://host[:port], escrito como lo envía el navegador: host en minúsculas, sin puerto por defecto, sin ruta y sin barra final. Un comodín, incluido *.domain, detiene el arranque en cualquier entorno. Un entorno protegido acepta solo orígenes https, así que rechaza el valor por defecto.	http://localhost:3000	En un entorno protegido
TRUSTED_PROXIES	IPs o CIDRs de proxy, separados por comas, de confianza para establecer la IP real del cliente. Se rechazan los comodines.	—	En un entorno protegido con TLS_TERMINATED_UPSTREAM=true
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). Requiere los archivos de certificado y de clave.	—	No
TLS_TERMINATED_UPSTREAM	Configura true cuando el TLS se termina en un balanceador de carga o proxy inverso.	false	No

Un entorno protegido exige los archivos de certificado y de clave del servidor, o TLS_TERMINATED_UPSTREAM=true.

​

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	Exige autenticación de Access Manager en las rutas protegidas. Configura true o false. Un valor en blanco detiene el inicio. false inicia solo cuando ENV_NAME es development, develop, dev, local o test, y nunca con DEPLOYMENT_MODE=saas.	—	Sí
PLUGIN_AUTH_ADDRESS	Dirección del servicio Access Manager. Un entorno protegido exige https://.	—	Si AUTH_ENABLED=true o en un entorno protegido
AUTH_REQUIRED	Con true, las rutas protegidas responden 503 cuando la autenticación está desactivada.	false	No
AUTH_TIMEOUT	Límite de tiempo de la verificación de una solicitud en Access Manager, con los reintentos incluidos. Escríbelo con unidad, como 30s.	30s	No
AUTH_CACHE_TTL	Tiempo que el riel guarda cada decisión de Access Manager. Escríbelo con unidad, como 30s. Un cambio de permisos puede tardar ese tiempo en aplicarse. Sin valor, el riel no guarda decisiones.	—	No
AUTH_BREAKER_ENABLED	Activa un circuit breaker para las llamadas a Access Manager. Tras 5 llamadas seguidas con falla, detiene las llamadas durante 30 segundos. Mientras tanto, el riel rechaza toda solicitud sin aprobación en caché. Define true o false.	false	No
AUTH_RETRY_MAX	Máximo de reintentos de una llamada a Access Manager que falla sin decisión. 0 desactiva los reintentos.	0	No
AUTH_JWT_VERIFY_CERT	Una o más claves públicas RSA en PEM o certificados X.509, separados por saltos de línea. Con una clave cargada, el riel verifica la firma RS256 y la expiración de cada token bearer, y responde 401 cuando la verificación falla. Tiene precedencia sobre AUTH_JWT_VERIFY_CERT_PATH.	—	No
AUTH_JWT_VERIFY_CERT_PATH	Ruta de un archivo con el mismo contenido. El riel lo lee solo cuando AUTH_JWT_VERIFY_CERT está vacía.	—	No

​

Declaración de permisos

Cada binario puede publicar su declaración de permisos en Access Manager al iniciar. Estas variables son independientes de AUTH_ENABLED.

Variable	Descripción	Predeterminado	Obligatoria
IDP_DECLARATION_ENABLED	Define true para publicar la declaración de permisos al iniciar. Define true o false.	false	No
IDP_HOST	URL http o https absoluta del servicio Identity de Access Manager.	—	Si la declaración está activada
IDP_M2M_CLIENT_ID	ID de cliente con el que el binario publica.	—	Si la declaración está activada
IDP_M2M_CLIENT_SECRET	Secreto de cliente con el que el binario publica. Sensible.	—	Si la declaración está activada
PLUGIN_AUTH_ENABLED	Activa la solicitud de token que la publicación necesita. Debe ser true cuando la declaración está activada. Define true o false.	false	Si la declaración está activada

Con IDP_DECLARATION_ENABLED=true, el binario no inicia cuando una de las tres variables obligatorias está vacía, cuando IDP_HOST no es válido o cuando PLUGIN_AUTH_ENABLED no es true. La publicación también necesita la dirección de Access Manager, definida en PLUGIN_AUTH_ADDRESS. Cuando Access Manager rechaza la publicación o no responde, el binario sigue iniciando.

​

Licencia

Todo binario (spi, dict, brcode y core) necesita una licencia para arrancar. Una licencia cubre los cuatro binarios y es global: el riel no lee lista de organizaciones.

Variable	Descripción	Predeterminado	Obligatorio
LICENSE_KEY	Clave de licencia. El riel la valida en el servicio de licencias de Lerian, license.lerian.io, en todo entorno.	—	Sí
LICENSE_FILE_PATH	Ruta de un archivo de licencia. Cuando está definida, el riel usa el archivo e ignora LICENSE_KEY, y un archivo que el riel rechaza detiene el inicio. Déjala vacía y define LICENSE_KEY.	—	No

Un binario detiene el arranque cuando ninguna de las dos variables está configurada, sea cual sea el valor de ENV_NAME. La verificación de licencia cubre toda ruta, salvo /health, /readyz, /version, /metrics, así que cubre también las rutas de payload y de conjunto de claves del BR Code. Cuando la licencia se rechaza, al arrancar o en una verificación posterior en segundo plano, el binario se detiene. Un pod con LICENSE_KEY necesita HTTPS de salida hacia license.lerian.io.

​

Callback de BACEN (entrante desde SPI)

Variable	Descripción	Predeterminado	Obligatorio
BACEN_CALLBACK_TRUSTED_PROXY_CIDRS	CIDRs de confianza como origen de los callbacks de BACEN. Configúralos junto con el secreto de header.	—	Con el secreto de header
BACEN_CALLBACK_MTLS_HEADER_SECRET	Secreto compartido que prueba que el upstream terminó el TLS mutuo del callback. Al menos 32 caracteres. Sensible.	—	Si un consumidor ICOM está habilitado

Fuera de un entorno local, el riel necesita exactamente un modo de TLS mutuo de callback. En el modo directo, configura SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE y SERVER_TLS_CLIENT_CA_FILE. En el modo proxy, configura TLS_TERMINATED_UPSTREAM=true, los CIDRs de confianza y el secreto de header.

​

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 el canal secundario de mensajería y el endpoint de transferencia de archivos (ARQ).

Variable	Descripción	Predeterminado	Obligatorio
BACEN_SPI_ENDPOINT	URL del endpoint principal de SPI.	http://localhost:9900	Fuera de un entorno local
BACEN_SPI_SECONDARY_ENDPOINT	URL del canal secundario de mensajería. El riel envía pain.013, pain.014, camt.025 y trck.002 por este canal. Cuando no se configura, esos envíos fallan.	—	Si el consumidor ICOM secundario está habilitado
BACEN_ARQ_ENDPOINT	URL del endpoint de transferencia de archivos de BACEN. El riel obtiene de él archivos grandes de extracto. El binario spi también descarga de él la lista de certificados de QR de BACEN.	—	En el binario spi, con la resolución del lado del pagador habilitada y la confianza de prueba apagada, salvo que BACEN_ARQ_ENABLED sea false
BACEN_ARQ_ENABLED	false apaga el cliente de transferencia de archivos, tanto la obtención de archivos de extracto como la descarga de la lista de certificados de QR, incluso con BACEN_ARQ_ENDPOINT configurada. Cualquier otro valor deja la decisión al endpoint. Con false, el binario spi nunca actualiza la lista, y brcode conserva la última lista almacenada.	—	No
BACEN_SPI_PARTICIPANT_ISPB	El ISPB de 8 caracteres (dígitos o letras mayúsculas) del participante para la superficie de SPI.	—	En vivo o si un consumidor ICOM está habilitado
BACEN_SPI_ALLOWED_ENDPOINT_HOSTS	Lista de hosts permitidos a los que puede llegar el cliente de SPI (protección contra SSRF). Debe incluir el host del endpoint.	—	Fuera de un entorno local
BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS	Lista de hosts permitidos para el endpoint secundario.	—	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_RETRY_ATTEMPTS	Máximo de intentos por solicitud de transporte, incluido el primero.	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. Debe ser true fuera de un entorno local.	false	Fuera de un entorno local
BACEN_SPI_OUTBOUND_QUOTA_LIMIT	Cuota saliente sostenida (solicitudes por segundo). Debe ser positiva.	—	Si la cuota está habilitada
BACEN_SPI_OUTBOUND_QUOTA_BURST	Margen de ráfaga por encima de la cuota. Debe ser positivo.	—	Si la cuota está habilitada
BACEN_SPI_CATALOGUE_VERSION	Versión del catálogo de mensajes SPI de BACEN.	5.13.2	No
BACEN_SPI_XSD_DIR	Directorio de los esquemas XSD de BACEN que validan los mensajes. Un valor que defines se usa tal como está, así que debe contener los esquemas de BACEN_SPI_CATALOGUE_VERSION.	El paquete de la versión del catálogo	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 un entorno protegido o si un consumidor ICOM está habilitado
BACEN_SPI_ANSWER_SWEEP_INTERVAL	Con qué frecuencia el riel reenvía las respuestas que un mensaje recibido aún espera (duración Go). Debe ser mayor que cero.	2s	No
BACEN_SPI_ANSWER_BATCH	Número máximo de respuestas pendientes que reclama una pasada de reenvío. Debe ser mayor que cero.	50	No
BACEN_SPI_ANSWER_SWEEP_CONCURRENCY	Número de workers que reclaman y envían respuestas al mismo tiempo en una pasada de reenvío. Debe ser mayor que cero.	8	No

​

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.	—	En vivo
BACEN_TLS_KEY_KIND	Dónde se guarda la clave privada del cliente: file o kmip.	file	No
BACEN_TLS_KEY_FILE	Clave privada del cliente. Sensible. Debe estar vacía cuando el tipo de clave es kmip.	—	En vivo y con el tipo de clave file
BACEN_TLS_KMIP_PRIVATE_KEY_UID	UID de la clave privada del cliente en el HSM.	—	Si kmip
BACEN_TLS_KMIP_PUBLIC_KEY_UID	UID de la clave pública del cliente en el HSM.	—	Si kmip
BACEN_TLS_CA_FILE	Paquete de CA usado para verificar el certificado del servidor de BACEN.	—	En vivo

Con BACEN_TLS_KEY_KIND=kmip, la clave privada del cliente se queda en tu HSM. El binario la abre mediante la conexión KMIP de su propio firmante: define BACEN_SPI_SIGNER_KIND=kmip en spi o BACEN_DICT_SIGNER_KIND=kmip en dict. El inicio se rechaza a menos que los dos UID estén definidos y el UID de la clave privada sea distinto del UID de la clave privada de firma. Si el binario no puede abrir la clave en el HSM, no queda listo. Un BACEN_TLS_CERT_FILE renovado debe contener el certificado de la misma clave del HSM: el binario rechaza un certificado de otra clave y mantiene el certificado cargado.

​

Firma de mensajes y certificados

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

Con el backend kmip, un UID incorrecto de la clave privada de firma o un ajuste incorrecto de DigestInfo detiene el inicio. Lo mismo vale para los backends KMIP de DICT y de BR Code JOSE.

Variable	Descripción	Predeterminado	Obligatorio
BACEN_SPI_SIGNER_KIND	Backend de custodia de firma: file, pkcs11 o kmip. Un entorno protegido rechaza file.	file	En un entorno protegido
BACEN_SPI_SIGNER_COMMON_NAME	Common name esperado del certificado de firma.	—	Fuera de un entorno local
BACEN_SPI_SIGNING_CERT_FILE	Ruta al certificado vinculado a la clave de firma.	—	En vivo, o si pkcs11 o kmip
BACEN_SPI_SIGNING_KEY_FILE	Ruta a la clave privada de firma (backend de archivo). Sensible.	—	En vivo con file
BACEN_SPI_VERIFY_CERT_FILE	Paquete de certificados usado para verificar la firma de BACEN en los mensajes entrantes.	—	En vivo
BACEN_SPI_INBOUND_SIGNER_COMMON_NAME	Common name esperado del firmante en los mensajes entrantes.	—	Fuera de un entorno local
CERT_READINESS_MIN_DAYS	Mínimo de días para el vencimiento de un certificado. Un certificado válido con menos días restantes mantiene activa su verificación de readiness y registra una advertencia. Un certificado vencido indica falla en su verificación, y /readyz sigue listo.	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. Con DEPLOYMENT_MODE=saas, debe usar https.	—	Si kmip
BACEN_SPI_KMIP_CA_FILE	Paquete PEM de la CA privada del HSM. El riel confía en él además de las raíces del sistema.	—	No
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: soft_fail, hard_fail o disabled. Un entorno protegido rechaza disabled.	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 de payloads: in_memory o postgres. Un entorno protegido rechaza in_memory.	in_memory	En un entorno protegido
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. Debe ser igual a BACEN_SPI_PARTICIPANT_ISPB.	—	Si un consumidor 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
BACEN_ICOM_FORWARD_FAILURE_ALARM_THRESHOLD	Cuántos reenvíos seguidos pueden terminar sin resultado final antes de que el consumidor de entrada registre una advertencia y añada un motivo a su verificación de readiness. La verificación no pasa a down. El mismo número de rechazos seguidos para un mensaje de entrada aparca ese mensaje, y el flujo sigue.	5	No

Cada consumidor requiere un backend de persistencia configurado, BACEN_ICOM_ISPB, BACEN_SPI_INTERNAL_CALLBACK_SECRET y BACEN_CALLBACK_MTLS_HEADER_SECRET. El consumidor principal también requiere BACEN_ICOM_BASE_URL. El consumidor secundario también requiere BACEN_SPI_SECONDARY_ENDPOINT.

Un consumidor habilitado requiere el modo proxy de callback: TLS_TERMINATED_UPSTREAM=true, ningún SERVER_TLS_CLIENT_CA_FILE y BACEN_CALLBACK_TRUSTED_PROXY_CIDRS con la dirección desde la que reenvía el consumidor. Con el SERVER_ADDRESS predeterminado, esa dirección es 127.0.0.1.

​

Cliente DICT (BACEN_DICT_*)

Cliente para el directorio de claves Pix de BACEN (DICT), incluido el endpoint NP para verificaciones de existencia de claves por lote. El cliente no lee HTTP_PROXY ni HTTPS_PROXY.

Variable	Descripción	Predeterminado	Obligatorio
BACEN_DICT_ENDPOINT	URL del endpoint de DICT.	http://localhost:9900	Fuera de un entorno local
BACEN_DICT_PARTICIPANT_ISPB	ISPB del participante para la superficie de DICT.	—	Fuera de un entorno local
BACEN_DICT_ALLOWED_ENDPOINT_HOSTS	Lista de hosts permitidos a los que puede llegar el cliente de DICT. Debe incluir el host del endpoint.	—	Fuera de un entorno local
BACEN_DICT_TIMEOUT_SEC	Timeout de la solicitud DICT (segundos).	10	No
BACEN_DICT_CID_SET_FILE_MAX_BYTES	Archivo más grande del conjunto de CIDs, en bytes, que el riel descarga. El riel rechaza un archivo que declara un tamaño mayor.	8589934592	No
BACEN_DICT_CID_SET_FILE_IDLE_TIMEOUT_SEC	Timeout de cada lectura de la descarga de un archivo del conjunto de CIDs (segundos).	60	No
BACEN_DICT_NP_ENDPOINT	URL del endpoint NP para verificaciones de existencia de claves por lote. Cuando no se configura, la verificación por lote responde 501. Con DEPLOYMENT_MODE=saas, debe usar https.	—	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. Cualquier otro valor detiene el arranque. Un entorno protegido rechaza file en el binario dict.	file	En un entorno protegido
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.	—	En vivo
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. Con DEPLOYMENT_MODE=saas, debe usar https.	—	Si kmip
BACEN_DICT_KMIP_CA_FILE	Paquete PEM de la CA privada del HSM. El riel confía en él además de las raíces del sistema.	—	No
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_OUTBOUND_QUOTA_ENABLED	Habilita la cuota de solicitudes a DICT del lado del cliente. false inicia solo en un entorno local.	true	No
BACEN_DICT_ENTRIES_READ_CATEGORY	La categoría de lectura de entradas DICT del participante, una letra de A a H.	—	Para el binario dict mientras la cuota está habilitada
BACEN_DICT_SPONSORED_ENTRIES_READ_CATEGORIES	Categorías de lectura de entradas de participantes patrocinados, como pares ispb:letter. Un participante sin par usa H.	—	No
BACEN_DICT_QUERY_MONITOR_ENABLED	Habilita el monitor de consultas de DICT. false inicia solo en un entorno local.	true	No
BACEN_DICT_QUERY_MONITOR_INTERVAL_SEC	Con qué frecuencia el monitor evalúa la ventana (segundos). Debe ser mayor que cero.	300	No
BACEN_DICT_QUERY_MONITOR_WINDOW_HOURS	Duración de la ventana móvil que mide el monitor (horas). Debe ser mayor que cero y como máximo 168.	24	No
BACEN_DICT_QUERY_MONITOR_PARTICIPANT_NOT_FOUND_BPS	Proporción de consultas del participante que no encuentran clave, en puntos base, por encima de la cual el monitor señala la ventana. Debe ser mayor que cero.	700	No
BACEN_DICT_QUERY_MONITOR_PARTICIPANT_MIN_QUERIES	Consultas por debajo de las cuales el monitor no juzga los indicadores del participante. Debe ser mayor que cero.	100	No
BACEN_DICT_QUERY_MONITOR_PAYER_NOT_FOUND_BPS	Proporción de consultas de un pagador que no encuentran clave, en puntos base, por encima de la cual el monitor lista al pagador. Debe ser mayor que cero.	2000	No
BACEN_DICT_QUERY_MONITOR_PAYER_MIN_QUERIES	Consultas por debajo de las cuales el monitor no juzga a un pagador. Debe ser mayor que cero.	100	No
BACEN_DICT_QUERY_MONITOR_ORDER_RATIO_BPS	Razón entre consultas y órdenes de pago, en puntos base, a partir de la cual el monitor señala la ventana. Debe ser mayor que cero.	20000	No

​

Firma JOSE de BR Code (BACEN_BRCODE_JOSE_*)

Firma payloads dinámicos de BR Code (JWS). Cuando BACEN_BRCODE_JOSE_SIGNER_KIND no está configurada, JOSE queda deshabilitado y los endpoints públicos de payload se niegan a servir. Con JOSE habilitado, enruta las rutas de payload (/api/v1/brcode/payload/*) y la ruta del conjunto de claves (/api/v1/brcode/.well-known/jwks.json) bajo PUBLIC_BASE_URL al binario brcode, sin ningún autorizador delante. El PSP del pagador llama a estas rutas sin credencial.

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. Con DEPLOYMENT_MODE=saas, debe usar https.	—	Si BR Code JOSE está habilitado con kmip
BACEN_BRCODE_JOSE_KMIP_CA_FILE	Paquete PEM de la CA privada del HSM. El riel confía en él además de las raíces del sistema.	—	No
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

​

Resolución de QR de BR Code (BACEN_BRCODE_QR_PAYER_*)

Controla la resolución de un QR dinámico del lado del pagador. Cuando la resolución está desactivada, su operación responde 503.

Variable	Descripción	Predeterminado	Obligatorio
BACEN_BRCODE_QR_PAYER_ENABLED	Habilita la resolución de códigos QR dinámicos del lado del pagador.	false	No
BACEN_BRCODE_QR_PAYER_CERT_LIST_FILE	Solo en la confianza de prueba: ruta al zip que contiene la lista de certificados con el certificado del sitio de QR simulado. Un archivo vacío o ilegible detiene el arranque. Fuera de la confianza de prueba, brcode lee la lista de la base de datos e ignora esta variable.	—	Si la confianza de prueba está activa
BACEN_BRCODE_QR_PAYER_TEST_TRUST	Solo desarrollo: relaja las verificaciones del sitio del QR (CA raíz adicionales de BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE, un sitio en red privada, sin política EV, revocación en soft-fail). El arranque se detiene a menos que ENV_NAME sea development, develop, dev, local o test, y con DEPLOYMENT_MODE=saas.	false	No
BACEN_BRCODE_QR_PAYER_TEST_TRUST_ROOT_CA_FILE	Archivo PEM de las CA raíz de la confianza de prueba.	—	Si la confianza de prueba está activa

Con BACEN_ARQ_ENDPOINT configurada y BACEN_ARQ_ENABLED distinta de false, el binario spi revisa la lista de certificados cada hora. Cuando la lista almacenada tiene 24 horas, descarga la lista de BACEN por los archivos BACEN_TLS_*, la valida y la almacena en la base de datos. Una descarga fallida o inválida conserva la última lista. El ENV_NAME del binario spi selecciona la lista: production descarga la lista de producción, y cualquier otro valor descarga la lista de homologación. El binario brcode lee la lista almacenada cada minuto y no necesita para ello los archivos BACEN_TLS_* ni BACEN_ARQ_ENDPOINT, así que brcode y spi deben usar la misma base PostgreSQL. Hasta que se almacene la primera lista, la resolución responde 503. El binario spi detiene el arranque cuando BACEN_BRCODE_QR_PAYER_ENABLED es true en su propio entorno, la confianza de prueba está apagada, BACEN_ARQ_ENDPOINT está vacía y BACEN_ARQ_ENABLED es distinta de false.

​

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.

Cada clave tiene 32 bytes, en formato bruto o base64. Cada pepper tiene al menos 32 caracteres.

Variable	Descripción	Predeterminado	Obligatorio
DICT_KEY_PII_ENCRYPTION_KEY	Clave AES para la PII del titular de la clave DICT. Sensible.	—	Binario dict en un entorno protegido
DICT_KEY_BLIND_INDEX_PEPPER	Pepper para la indexación ciega de la PII de claves DICT. Sensible.	—	Binario dict en un entorno protegido
DICT_AUDIT_HASH_PEPPER	Pepper para el hash de registros de auditoría de DICT. Sensible.	—	En un entorno protegido, o para el binario dict fuera de un entorno local
AUDIT_HASH_PEPPER	Pepper de hash de auditoría de respaldo, que se lee solo cuando DICT_AUDIT_HASH_PEPPER no está configurado. Sensible.	—	No
SPI_RESPONSIBLES_ENCRYPTION_KEY	Clave AES para la PII de responsables. Sensible.	—	Binario spi en un entorno protegido
SPI_OPERATIONS_PII_ENCRYPTION_KEY	Clave AES-256 para la PII de la operación. Sensible.	—	Sí, para el binario spi
SPI_OPERATIONS_BLIND_INDEX_PEPPER	Pepper para la indexación ciega de la PII de la operación. Sensible.	—	Sí, para el binario spi
BRCODE_PII_ENCRYPTION_KEY	Clave AES para la PII de BR Code. Sensible.	—	Binario brcode en un entorno protegido
BRCODE_PII_BLIND_INDEX_PEPPER	Pepper para la indexación ciega de la PII de BR Code. Sensible.	—	Binario brcode en un entorno protegido

​

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 un entorno protegido.	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. Un entorno protegido rechaza disable. Usa verify-full con una CA de confianza para conexiones remotas. require cifra el canal, pero no verifica la identidad del servidor.	disable	En un entorno protegido
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 la réplica de lectura. El servicio usa la réplica solo cuando su host y su puerto están configurados.	—	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. Cuando no se configura, la réplica usa el modo del primario.	—	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 TLS de Redis.	—	Si REDIS_TLS=true
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

​

Archivo regulatorio (REGULATORY_ARCHIVE_*)

Los binarios spi y dict mantienen el archivo regulatorio en un almacenamiento compatible con S3. Los binarios brcode y core no usan estas variables.

Variable	Descripción	Predeterminado	Obligatorio
REGULATORY_ARCHIVE_BUCKET	Bucket que guarda el archivo.	—	Fuera de un entorno de desarrollo
REGULATORY_ARCHIVE_ENDPOINT	URL base de la API S3. Cuando no se configura, el riel usa el endpoint regional de AWS. Con DEPLOYMENT_MODE=saas, debe usar https.	—	No
REGULATORY_ARCHIVE_REGION	Región del almacenamiento.	—	Si el bucket está configurado
REGULATORY_ARCHIVE_ACCESS_KEY	Clave de acceso. Configúrala junto con la clave secreta. Sin las dos, el riel usa las fuentes de credenciales predeterminadas de AWS.	—	No
REGULATORY_ARCHIVE_SECRET_KEY	Clave secreta. Sensible.	—	No
REGULATORY_ARCHIVE_USE_PATH_STYLE	Usa el direccionamiento de bucket con estilo de ruta.	false	No
REGULATORY_ARCHIVE_SSE_ALGORITHM	Cifrado del lado del servidor: AES256, aws:kms o none. none inicia solo en un entorno de desarrollo.	—	Si el bucket está configurado
REGULATORY_ARCHIVE_SSE_KMS_KEY_ID	ID de la clave KMS para el cifrado aws:kms.	—	Si el cifrado es aws:kms
REGULATORY_ARCHIVE_OBJECT_LOCK_MODE	Modo de Object Lock: COMPLIANCE, GOVERNANCE o none. none inicia solo en un entorno de desarrollo.	—	Si el bucket está configurado

Aquí, un entorno de desarrollo es aquel en el que ENV_NAME es development, develop, dev, local o test, y DEPLOYMENT_MODE no es saas. Estas reglas leen ENV_NAME tal como está configurado, así que un ENV_NAME sin configurar no es un entorno de desarrollo. Una variable obligatoria ausente detiene el inicio. En un entorno de desarrollo sin bucket, el riel no archiva nada. Con el archivo activo, /readyz en spi y dict indica falla en la verificación del archivo mientras el bucket no responde, y sigue listo.

​

Outbox y streaming

Lerian SPI publica eventos mediante un outbox transaccional y un productor de 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. Cada binario requiere su propio valor fijo de STREAMING_CLOUDEVENTS_SOURCE, y cualquier otro valor detiene el inicio: br-spi para spi, br-spi-dict para dict, br-spi-brcode para brcode y br-spi-core para core.

Una entrada de STREAMING_EVENT_POLICIES que desactiva un evento de Lerian SPI detiene el inicio. Solo los dos eventos spi_tracking y tres eventos dict_med_operations (inconsistent_projection, feed_blocked y feed_record_abandoned) se pueden desactivar.

Variable	Descripción	Predeterminado	Obligatorio
OUTBOX_ENABLED	Habilita el despachador transaccional del outbox. Debe ser true para los binarios spi, dict y brcode en un entorno protegido.	true	No
OUTBOX_DISPATCH_INTERVAL_MS	Intervalo entre ciclos de despacho (milisegundos).	100	No
OUTBOX_BATCH_SIZE	Filas procesadas por ciclo de despacho.	50	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
CORE_PARTICIPANT_CONSUMER_ENABLED	Habilita el consumidor de Core que aplica las confirmaciones de participantes que llegan del binario SPI. Configura true o false. Cualquier otro valor detiene el inicio.	false	No
CORE_SETTLEMENT_COMPLETION_CONSUMER_ENABLED	Habilita el consumidor de Core que mueve una liquidación de PENDING a SETTLED. Configura true o false. Cualquier otro valor detiene el inicio.	false	No
CORE_SETTLEMENT_TERMINATION_CONSUMER_ENABLED	Habilita el consumidor de Core que aplica devoluciones y fallos a las liquidaciones. Configura true o false. Cualquier otro valor detiene el inicio.	false	No
BRCODE_SPI_FACT_CONSUMER_GROUP	Grupo de consumidores del binario brcode para los eventos que publica el binario spi.	br-spi-brcode-spi-fact-consumer	No
BRCODE_SPI_FACT_CONSUMER_CLIENT_ID	Client ID de ese consumidor.	El client ID del streaming	No
SPI_SOLICREC_DISPATCH_CONSUMER_GROUP	Grupo de consumidores del binario spi para los eventos que publica el binario brcode para enviar una solicitud.	br-spi-solicrec-dispatch-consumer	No
SPI_SOLICREC_DISPATCH_CONSUMER_CLIENT_ID	Client ID de ese consumidor.	El client ID del streaming	No

​

Programadores

Trabajos en segundo plano, cada uno con su propio interruptor. Los dos trabajos de DICT con valor predeterminado true tienen deberes regulatorios, así que el binario dict inicia su programador para ellos, a menos que SCHEDULER_ENABLED=false. El binario spi hace lo mismo para los trabajos de veredicto de las programaciones y de plazo de portabilidad. Los trabajos con valor predeterminado false también requieren SCHEDULER_ENABLED=true. 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. Un false explícito detiene todos los trabajos siguientes.	false	No
SCHEDULER_CLAIM_DEADLINE_ENABLED	Ejecuta el trabajo de plazos de reclamo de DICT.	true	No
SCHEDULER_INBOUND_DISCOVERY_ENABLED	Ejecuta los recorridos de descubrimiento de reclamos de DICT, del lado donante y del reclamante.	true	No
SCHEDULER_INBOUND_DISCOVERY_INTERVAL	Intervalo entre los ciclos de los recorridos de descubrimiento de reclamos. Debe ser mayor que cero y como máximo un minuto.	15s	No
SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES	Umbral de antigüedad de readiness para los recorridos de descubrimiento de reclamos. Debe ser mayor que cero.	15	No
SCHEDULER_QUOTA_RESET_ENABLED	Ejecuta el reinicio diario de la cuota de participantes en Core, a la medianoche hora de Brasilia.	false	No
SCHEDULER_DICT_AUDIT_RETENTION_ENABLED	Ejecuta la purga de retención de los logs de auditoría de DICT.	false	No
SCHEDULER_APPROVAL_EXPIRY_ENABLED	Cada 5 minutos, mueve las solicitudes de aprobación vencidas a EXPIRED.	false	No
SCHEDULER_PORTABILITY_DEADLINE_ENABLED	Cada 5 minutos, marca las operaciones de portabilidad cuyo plazo de 24 horas pasó. También devuelve al operador una operación de portabilidad cuyo reda.031 esperó 30 minutos la respuesta de BACEN. Nunca las confirma.	true	No
SCHEDULER_SCHEDULE_VERDICT_RECONCILER_ENABLED	Cada 5 minutos, publica el evento de veredicto faltante de una operación de programación de Pix Automático cerrada entre 15 minutos y 24 horas antes. No se ejecuta cuando OUTBOX_ENABLED=false.	true	No

​

Descubrimiento e inventario de DICT

Los workers siguientes se ejecutan de forma independiente a SCHEDULER_ENABLED, cada uno con su propio interruptor.

Variable	Descripción	Predeterminado	Obligatorio
DICT_FUNDS_RECOVERY_EVENTS_ENABLED	Habilita el feed de eventos de recuperación de fondos de DICT.	true	No
DICT_FUNDS_RECOVERY_EVENTS_MAX_STALENESS_MINUTES	Umbral de antigüedad de readiness para el feed de eventos de recuperación de fondos.	15	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 límite de tasa de solicitudes. Se fuerza a activado en un entorno protegido.	true	No
RATE_LIMIT_MAX	Máximo de solicitudes por ventana.	100	No
RATE_LIMIT_EXPIRY_SEC	Ventana de rate limit (segundos).	60	No
RATE_LIMIT_BACEN_QUOTA_MAX	Máximo de solicitudes por dirección de cliente y ruta por minuto en las rutas que gastan una cuota de DICT de BACEN. Se desactiva siempre que la limitación de solicitudes está desactivada.	3000	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.	—	Sí
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.	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_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 OpenAPI y la UI de documentación de la API. Se fuerza a desactivado en un entorno protegido.	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.

La respuesta de /readyz incluye una verificación license. Con LICENSE_KEY, la verificación siempre está activa y no llama al servicio de licencias, así que una licencia inválida no lleva /readyz a 503. Una licencia que el riel rechaza detiene el binario, al iniciar o en una verificación posterior en segundo plano.

Las verificaciones de certificados, la de custodia del firmante y la del archivo regulatorio informan su estado real en el cuerpo de /readyz. Cuando una indica falla, /readyz sigue listo.