Variables de entorno

Lerian SPI es la integración de mensajería nativa de Lerian para Pix. Llega al sistema de pagos instantáneos de BACEN (SPI) y al directorio de claves DICT a través de la RSFN. Incluye cuatro binarios en tiempo de ejecución (spi, dict, brcode y core), por lo que su conjunto de variables es amplio. El servicio lee todas las variables al iniciar. 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.	—	En un entorno protegido o si BR Code JOSE está habilitado
`ACCESS_CONTROL_ALLOW_ORIGIN`	Orígenes CORS permitidos. Un entorno protegido rechaza un comodín.	`http://localhost:3000`	No
`ACCESS_CONTROL_ALLOW_METHODS`	Métodos CORS permitidos.	`GET,POST,PUT,PATCH,DELETE,OPTIONS`	No
`ACCESS_CONTROL_ALLOW_HEADERS`	Encabezados de solicitud CORS permitidos.	(conjunto estándar)	No
`TRUSTED_PROXIES`	IPs 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

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.	—	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_ARQ_ALLOWED_ENDPOINT_HOSTS`	Lista de hosts permitidos para el endpoint ARQ.	—	No
`BACEN_SPI_TIMEOUT_SEC`	Timeout de la solicitud (segundos).	`30`	No
`BACEN_SPI_INITIATION_TIMEOUT_MS`	Timeout de inicio de pago (milisegundos).	`150`	No
`BACEN_SPI_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

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_FILE`	Clave privada del cliente. Sensible.	—	En vivo
`BACEN_TLS_CA_FILE`	Paquete de CA usado para verificar el certificado del servidor de BACEN.	—	En vivo

Firma de mensajes y certificados

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

Variable	Descripción	Predeterminado	Obligatorio
`BACEN_SPI_SIGNER_KIND`	Backend de custodia de firma: `file`, `pkcs11` o `kmip`. 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.	`14`	No
`BACEN_SPI_PKCS11_MODULE_PATH`	Ruta de la biblioteca del módulo PKCS#11.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_TOKEN_LABEL`	Etiqueta del token PKCS#11.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_PIN_FILE`	Ruta a un archivo que contiene el PIN del token. Sensible.	—	Si `pkcs11`
`BACEN_SPI_PKCS11_KEY_LABEL`	Etiqueta de la clave de firma en el token.	—	Si `pkcs11`
`BACEN_SPI_KMIP_BASE_URL`	URL base del servicio KMIP.	—	Si `kmip`
`BACEN_SPI_KMIP_VHSM`	Identificador del HSM virtual.	—	Si `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER_TOKEN`	Token de usuario cripto de KMIP. Sensible.	—	Si `kmip`
`BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si `kmip`
`BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si `kmip`
`BACEN_SPI_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP.	`false`	No

Validación de certificados (OCSP/CRL)

Variable	Descripción	Predeterminado	Obligatorio
`BACEN_SPI_OCSP_MODE`	Modo de verificación de revocación de certificados: `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

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.

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`.	—	No
`BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS`	Lista de hosts permitidos para el endpoint NP.	—	No
`BACEN_DICT_SIGNER_KIND`	Backend de custodia de firma de DICT: `file`, `pkcs11` o `kmip`.	`file`	No
`BACEN_DICT_SIGNING_CERT_FILE`	Ruta al certificado de firma de DICT.	—	Para la ruta de custodia de DICT seleccionada
`BACEN_DICT_SIGNING_KEY_FILE`	Ruta a la clave privada de firma de DICT (backend de archivo). Sensible.	—	Si `file`
`BACEN_DICT_VERIFY_CERT_FILE`	Certificado usado para verificar las respuestas de DICT.	—	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.	—	Si `kmip`
`BACEN_DICT_KMIP_VHSM`	Identificador del HSM virtual.	—	Si `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER_TOKEN`	Token de usuario cripto de KMIP. Sensible.	—	Si `kmip`
`BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si `kmip`
`BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si `kmip`
`BACEN_DICT_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP.	`false`	No
`BACEN_DICT_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. Sus umbrales tienen valores predeterminados.	`true`	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.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_VHSM`	Identificador del HSM virtual.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`	Usuario cripto de KMIP.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`	Token de usuario cripto de KMIP. Sensible.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID`	UID de la clave privada de firma.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`	UID de la clave pública de firma.	—	Si BR Code JOSE está habilitado con `kmip`
`BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX`	Antepone el prefijo ASN.1 DigestInfo antes de la llamada de firma de KMIP.	`false`	No

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`	Ruta a la lista de BACEN de certificados de sitio de QR autorizados. Un archivo vacío o ilegible detiene el arranque.	—	Si la resolución está habilitada

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 informa el servicio como no listo mientras el bucket no responde.

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

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

​Tiempo de ejecución y servidor

​Autenticación

​Callback de BACEN (entrante desde SPI)

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

​TLS mutuo con BACEN

​Firma de mensajes y certificados

​Validación de certificados (OCSP/CRL)

​Resolutor de payload

​Canal entrante (BACEN_ICOM_*)

​Cliente DICT (BACEN_DICT_*)

​Firma JOSE de BR Code (BACEN_BRCODE_JOSE_*)

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

​Cifrado y hashing de PII

​PostgreSQL

​Redis

​Archivo regulatorio (REGULATORY_ARCHIVE_*)

​Outbox y streaming

​Programadores

​Descubrimiento e inventario de DICT

​Rate limiting, idempotencia y conectividad

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

​Observabilidad

​Documentación

​Salud y readiness

Tiempo de ejecución y servidor

Autenticación

Callback de BACEN (entrante desde SPI)

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

TLS mutuo con BACEN

Firma de mensajes y certificados

Validación de certificados (OCSP/CRL)

Resolutor de payload

Canal entrante (`BACEN_ICOM_*`)

Cliente DICT (`BACEN_DICT_*`)

Firma JOSE de BR Code (`BACEN_BRCODE_JOSE_*`)

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

Cifrado y hashing de PII

PostgreSQL

Redis

Archivo regulatorio (`REGULATORY_ARCHIVE_*`)

Outbox y streaming

Programadores

Descubrimiento e inventario de DICT

Rate limiting, idempotencia y conectividad

Systemplane y configuración en tiempo de ejecución

Observabilidad

Documentación

Salud y readiness