Variables de entorno

Variables de entorno para desplegar y operar Pix Lerian: identidad, persistencia, integraciones, conectividad y eventos.

Los componentes de Pix Lerian incluyen SPI, DICT Hub, COB Hub, la API de Pix Automático, sus workers y el adaptador de conectividad. Esta página enumera las entradas de despliegue que lee Pix Lerian. Usa las tablas para ver qué valores comparten los componentes y cuáles pertenecen a un solo componente.

Para instalar o actualizar Pix Lerian, consulta el README del chart de Pix Lerian.

Los valores que se muestran aquí son placeholders. Inyecta las credenciales y el material de licencia desde tu almacén de secretos. Nunca hagas commit de secretos reales.

​

Modelo de configuración

Cada componente carga valores de bootstrap desde su entorno. SPI, DICT Hub, COB Hub, la API de Pix Automático y el worker DICT VSync también consumen la configuración de runtime de su almacén de Systemplane después de la inicialización. El adaptador de proveedor mock lee su configuración solo desde el entorno y mantiene su estado en memoria.

Configura cada componente por separado. Sus puertos, almacenes y dependencias obligatorias difieren.

​

Identidad y despliegue compartidos

Variable	Componentes	Contrato
APPLICATION_NAME	Todos	Identidad del componente que se usa en logs, telemetría. Conserva el valor que entrega la configuración de la versión.
SERVER_ADDRESS	Todos los componentes HTTP	Dirección de escucha en formato host:port. El puerto debe coincidir con la configuración del servicio del componente.
HEALTH_PORT	Todos los componentes HTTP	Puerto del listener de salud, de 1 a 65535. Sirve /health, /readyz y /metrics. Cuando no está definido, el componente no inicia un listener de salud. Apunta las sondas a este puerto.
DEPLOYMENT_MODE	Componentes de API y workers	local, saas o byoc. El valor predeterminado es local cuando falta el valor.
REQUEST_TIMEOUT_SEC	Componentes HTTP	Tiempo de espera por solicitud, en segundos. El valor predeterminado es 30.
LICENSE_KEY	Componentes con licencia	Obligatorio en todo modo de despliegue, local incluido. La clave vale para todo el despliegue: consulta License Manager. Inyéctala como secreto.
ENV_NAME	Todos	Nombre del entorno. Cuando está en blanco, el componente lee ENV, luego GO_ENV, y si no corre como production.
SWAGGER_ENABLED	Componentes de API	Booleano estricto. Cuando no está definido, la superficie OpenAPI y Scalar de runtime está activada en local y development y desactivada en cualquier otro entorno.

PLUGIN_AUTH_ENABLED controla la autenticación de las rutas entrantes. PLUGIN_AUTH_HOST es la dirección base de Access Manager que usa la integración de autenticación compartida y los flujos de credenciales de cliente OAuth. Debe ser solo una dirección base, sin una ruta OAuth, query, fragmento ni credenciales integradas. Usa https:// fuera del desarrollo local.

El adaptador de proveedor mock requiere SPI_BASE_URL, PROVIDER_CLIENT_ID y PROVIDER_CLIENT_SECRET al arrancar. MOCK_TEST_ENDPOINTS_ENABLED=true activa rutas de prueba que pueden falsificar callbacks del proveedor. El adaptador mock no tiene autorización de rutas: mantén el mock inaccesible para llamadores no confiables, sea cual sea el valor de este switch. No configures el adaptador mock como un riel de producción.

​

Persistencia y Valkey

Variable	Componentes	Contrato
DATABASE_URL	SPI, DICT Hub, COB Hub, API de Pix Automático y VSync	DSN de PostgreSQL para el almacén de negocio del componente. Es obligatorio donde el componente persiste datos de negocio.
DATABASE_READ_REPLICA	SPI, DICT Hub, COB Hub y API de Pix Automático	DSN opcional de PostgreSQL para una réplica de lectura. Solo las rutas de listado leen de ella, así que una escritura reciente puede faltar en un listado por un momento. El componente abre la conexión en el primer uso, así que arranca aunque la réplica no sea accesible. El modo multi-tenant la ignora.
SYSTEMPLANE_POSTGRES_DSN	Consumidores de Systemplane	DSN de PostgreSQL para el almacén de configuración de runtime. En SPI, DICT Hub, COB Hub y la API de Pix Automático vuelve a DATABASE_URL cuando no está definido.
REDIS_HOST, REDIS_PORT, REDIS_USER, REDIS_PASSWORD, REDIS_DB	Componentes de API y VSync	Configuración estructurada de la conexión a Valkey. No la sustituyas por la variable retirada VALKEY_URL.
REDIS_TLS, REDIS_PROTOCOL, REDIS_CA_CERT	Componentes de API y VSync	Seguridad del transporte de Valkey. Un certificado privado o autofirmado requiere REDIS_CA_CERT; no existe un interruptor para omitir la verificación. Una conexión a Valkey sin TLS detiene el componente al iniciar, a menos que ALLOW_INSECURE_REDIS o ALLOW_INSECURE_TLS esté activa.
ALLOW_INSECURE_REDIS, ALLOW_INSECURE_TLS	Componentes de API y VSync	true, 1, yes o on, en cualquier caso, activa cualquiera de las dos. ALLOW_INSECURE_REDIS permite que el cliente de Valkey se conecte sin TLS. ALLOW_INSECURE_TLS hace lo mismo para todo almacén de datos que el componente usa. El componente registra una advertencia mientras cualquiera esté activa. No definas ninguna en producción.
KEY_CACHE_TTL_SEC	DICT Hub	TTL de la caché de claves Pix, en segundos. El valor predeterminado es 60.

El comportamiento de Valkey varía según el componente. SPI, DICT Hub y COB Hub pueden degradar determinadas rutas de idempotencia o caché cuando no configuras Valkey. Algunas mutaciones de SPI, DICT y COB fallan de forma segura con PIX-0032 cuando no existe un respaldo duradero para repeticiones. DICT VSync trata Valkey como una dependencia obligatoria porque coordina el bloqueo de mutaciones entre pods. Un valor REDIS_* configurado pero mal formado hace fallar el arranque en lugar de seleccionar en silencio otro endpoint.

La implementación de Systemplane no usa SYSTEMPLANE_SECRET_MASTER_KEY. Protege el acceso a la base de datos de Systemplane, las copias de seguridad y el almacenamiento en disco mediante el entorno de despliegue.

​

Integraciones de la institución y de servicios

Variable	Componentes	Contrato
ORGANIZATION_ID	SPI, DICT Hub, COB Hub	Organización de Midaz que usan los componentes.
ISPB	SPI, DICT Hub, COB Hub	Identificador del participante. La API valida el header del participante o resuelve el valor desde la configuración del tenant.
ADAPTER_BASE_URL	SPI, DICT Hub, COB Hub, VSync	URL base del adaptador de conectividad, con el prefijo de ruta. Apúntala al adaptador de conectividad Lerian o, en las pruebas de integración, al adaptador de proveedor mock.
ADAPTER_CLIENT_ID, ADAPTER_CLIENT_SECRET	SPI, DICT Hub, COB Hub, VSync	Credenciales de cliente opcionales para las llamadas al adaptador de conectividad. Cuando ambas están vacías, esas llamadas no llevan el header Authorization.
MIDAZ_BASE_URL	SPI	URL base de Midaz para las operaciones de onboarding y transacciones. Midaz debe tener overrides.allowFeeSkip activado en el ledger, porque un Pix recibido nunca paga tarifa.
MIDAZ_LEDGER_ID	SPI	Identificador del ledger que se usa para las operaciones contables.
MIDAZ_CLIENT_ID, MIDAZ_CLIENT_SECRET	SPI	Credenciales del cliente OAuth para las llamadas a Midaz.
CRM_BASE_URL, CRM_CLIENT_ID, CRM_CLIENT_SECRET	SPI, DICT Hub, VSync	Integración con CRM que usan los flujos que validan cuentas, titulares o entradas huérfanas.
DICT_BASE_URL, DICT_CLIENT_ID, DICT_CLIENT_SECRET	SPI y COB Hub	Dirección y credenciales de DICT Hub o del proxy. DICT_ROUTING_MODE selecciona hub o proxy; mantén la URL coherente con esa elección.
COB_BASE_URL, COB_CLIENT_ID, COB_CLIENT_SECRET	SPI	Dirección y credenciales de COB Hub o del proxy. COB_ROUTING_MODE selecciona hub o proxy; mantén la URL coherente con esa elección.
SPI_BASE_URL, SPI_CLIENT_ID, SPI_CLIENT_SECRET	DICT Hub	Dirección y credenciales de SPI que se usan para las consultas de transferencias y las operaciones de bloqueo de saldo MED 2.0.
ANTIFRAUD_HOOK_ALLOW_PRIVATE_NETWORK	SPI	true permite que la verificación de fraude llame a una dirección http o a una dirección en una red privada. Úsalo solo en un entorno de prueba. El valor predeterminado es false.

​

Adaptador de conectividad Lerian

El adaptador de conectividad Lerian conecta Pix Lerian con Lerian SPI. Se ejecuta como dos componentes: la API del adaptador y su escritor de configuración. La API del adaptador sirve sus rutas bajo el prefijo /lerian.

El escritor de configuración copia sus variables en el almacén de configuración de runtime del adaptador al iniciar. No sobrescribe un valor almacenado que difiere del valor predeterminado. En modo single-tenant, la API del adaptador lee su enrutamiento y sus credenciales de ese almacén.

Variable	Componente	Contrato
SYSTEMPLANE_POSTGRES_DSN	API del adaptador	DSN de PostgreSQL del almacén de configuración de runtime. La API del adaptador no inicia sin él.
DATABASE_URL	Escritor de configuración	DSN de PostgreSQL donde el escritor guarda los valores. SYSTEMPLANE_POSTGRES_DSN lo reemplaza cuando está definido. El escritor no inicia sin uno de los dos.
BRSFN_SPI_BASE_URL, BRSFN_DICT_BASE_URL, BRSFN_BRCODE_BASE_URL	Escritor de configuración	Direcciones de las superficies spi, dict y brcode de Lerian SPI: solo esquema, host y puerto. Una superficie sin dirección rechaza sus llamadas. Ninguna superficie usa la dirección de otra.
BRSFN_SPI_CLIENT_ID, BRSFN_SPI_CLIENT_SECRET	Escritor de configuración	Credenciales de cliente OAuth de la superficie spi.
BRSFN_DICT_CLIENT_ID, BRSFN_DICT_CLIENT_SECRET	Escritor de configuración	Credenciales de cliente OAuth de la superficie dict.
BRSFN_COB_CLIENT_ID, BRSFN_COB_CLIENT_SECRET	Escritor de configuración	Credenciales de cliente OAuth de la superficie brcode.
PLUGIN_AUTH_HOST	Escritor de configuración	Dirección de Access Manager. El adaptador obtiene de ella el token de cada par de credenciales de cliente.
SPI_BASE_URL	Escritor de configuración	Dirección completa de SPI, con la ruta /spi, para los callbacks de pago. Sin ella, el adaptador no enruta ninguna solicitud.
DICT_BASE_URL, COB_BASE_URL, PIXAUTO_BASE_URL	Escritor de configuración	Direcciones completas de DICT Hub, COB Hub y la API de Pix Automático para sus callbacks. Incluye la ruta /pixauto en PIXAUTO_BASE_URL. Cuando una no está definida, solo fallan sus callbacks.
SPI_CLIENT_ID, SPI_CLIENT_SECRET, DICT_CLIENT_ID, DICT_CLIENT_SECRET, COB_CLIENT_ID, COB_CLIENT_SECRET, PIXAUTO_CLIENT_ID, PIXAUTO_CLIENT_SECRET	Escritor de configuración	Credenciales de cliente, un par para los callbacks de cada componente. Cuando el par del SPI, del COB o de Pix Automático está incompleto, el adaptador envía los callbacks a ese componente sin token. Sin el par completo del DICT, el adaptador rechaza cada evento que debe reenviar al DICT Hub.
DICT_CID_FILE_BASE_URL	Escritor de configuración	Dirección de la API del adaptador, con el prefijo /lerian, tal como DICT Hub la alcanza. Sin ella, el adaptador rechaza cada evento de archivo de DICT VSync.
WEBHOOK_INGRESS_ENABLED	API del adaptador	Activa las rutas que reciben eventos de Lerian SPI, como resultados de entrada de efectivo y de liquidación. El valor predeterminado es false. Cuando es true, la API del adaptador no inicia sin REDIS_HOST.
MULTI_TENANT_URL, MULTI_TENANT_SERVICE_API_KEY	Ambos	Obligatorios cuando MULTI_TENANT_ENABLED=true.
AWS_REGION	API del adaptador	Obligatorio cuando MULTI_TENANT_ENABLED=true, junto con ENV_NAME.

Cuando una superficie de Lerian SPI no tiene un par de credenciales completo o no hay PLUGIN_AUTH_HOST, el adaptador no llama a esa superficie. Cada ruta de eventos comprueba cada entrega con el secreto de firma de su suscripción de eventos. El adaptador lee esos secretos de su configuración de runtime, no del entorno. En modo single-tenant, cuando una suscripción tiene un nuevo secreto de firma, escribe ese secreto en la configuración de runtime mediante la API de administración del escritor de configuración. Una ruta sin secreto rechaza todas las entregas.

Excepto ALLOW_INSECURE_REDIS y ALLOW_INSECURE_TLS, cada variable booleana de esta página acepta solo los valores exactos en minúsculas true y false. Cualquier otro valor, como TRUE o 1, detiene el componente al arrancar.

​

DICT VSync

El worker DICT VSync concilia el estado de DICT y requiere su propia configuración de worker:

Variable	Predeterminado	Contrato
VSYNC_ENABLED	true	Habilita el planificador del worker.
VSYNC_FILE_RECON_ENABLED	true	Habilita la conciliación basada en archivos.
VSYNC_CHUNK_PROCESSING_DEADLINE_MIN	30	Plazo de procesamiento de un chunk, en minutos.
VSYNC_MAX_JOB_ATTEMPTS	3	Máximo de intentos para un trabajo de conciliación.
VSYNC_EVENTSYNC_MAX_PAGES	100	Máximo de páginas en la sincronización de eventos.
VSYNC_GATE_TTL_SEC	57600	TTL del lease del bloqueo de mutaciones, en segundos. Un valor por debajo del piso detiene el worker al iniciar. Con el intervalo predeterminado de análisis de trabajos atascados, el piso es 45540.
VSYNC_STUCK_JOB_SWEEP_TICK_SEC	120	Intervalo entre los análisis de trabajos atascados, en segundos.
VSYNC_CHUNK_SWEEP_TICK_SEC	300	Intervalo entre los análisis de chunks atascados, en segundos.
VSYNC_CADENCE_ENABLED	true	Activa la verificación de cada ámbito conocido con una cadencia fija.
VSYNC_CADENCE_INTERVAL_SEC	43200	Mayor tiempo, en segundos, que un ámbito pasa sin una verificación completada antes de que el worker inicie una nueva. El rango va de 300 a 43200.
RABBITMQ_URI	—	URI de RabbitMQ para la cola de conciliación de archivos. Usa amqps:// fuera del desarrollo local.
RABBITMQ_ENABLED	dependiente del componente	Habilita el publicador de trabajos de DICT Hub. El worker VSync requiere su configuración de cola.

VSYNC_ENABLED, VSYNC_FILE_RECON_ENABLED, VSYNC_CADENCE_ENABLED y VSYNC_CADENCE_INTERVAL_SEC pueden recargarse en caliente mediante la configuración de runtime del worker. Los valores de ajuste restantes se leen al arrancar y requieren un reinicio.

​

API de Pix Automático

La API de Pix Automático envía comandos de liquidación a SPI y lee estas variables:

Variable	Contrato
ORGANIZATION_ID	Organización en nombre de la cual actúa el componente en modo single-tenant. El componente lee primero su configuración de runtime y usa este valor solo cuando esa configuración no tiene ninguno. Con MULTI_TENANT_ENABLED=true, el componente no arranca si este valor está definido.
SPI_BASE_URL	Dirección de SPI para la liquidación de Pix Automático. Incluye el segmento de ruta /spi de SPI. Un valor mal formado impide que el componente arranque.
SPI_CLIENT_ID, SPI_CLIENT_SECRET	Credenciales de cliente para la llamada de liquidación. En modo multi-tenant, el componente resuelve las credenciales por tenant y no usa estos valores.
REGULATORY_DISPATCH_ENABLED	Activa el despachador que envía intenciones regulatorias al adaptador de proveedor. El valor predeterminado es false.
ADAPTER_BASE_URL	Dirección del adaptador de proveedor a la que envía el despachador. El componente lee REGULATORY_DISPATCH_BASE_URL solo cuando este valor está vacío. Cuando el despacho está activado y no hay ninguna dirección definida, el componente no arranca.
ADAPTER_CLIENT_ID, ADAPTER_CLIENT_SECRET	Credenciales de cliente del despachador. Cuando el despacho está activado, el componente no arranca si solo una de ellas está definida. Tampoco arranca si ambas están vacías y ENV_NAME no es local ni development.
CRM_BASE_URL, CRM_CLIENT_ID, CRM_CLIENT_SECRET	Dirección y credenciales del CRM que se usan para resolver la cuenta del pagador en los recorridos de QR code y en las solicitudes del recorrido 1 que no indican la cuenta. Cuando CRM_BASE_URL no está definido, toda resolución responde 503 (PIX-0814).

​

Streaming y observabilidad

El relay de notification-outbox está deshabilitado de forma predeterminada. Para habilitarlo, define STREAMING_ENABLED=true y proporciona STREAMING_BROKERS. La fuente de CloudEvents compartida, cuando está configurada, debe identificar el servicio Pix Lerian. El componente también valida la configuración TLS/SASL del broker de streaming y la STREAMING_DATASCHEMA_BASE_URL opcional.

Define ENABLE_TELEMETRY=true para activar OpenTelemetry. Las variables OTEL_* lo configuran. Consulta Configuración de BYOC para los parámetros compartidos de telemetría y transporte del broker.

​

Salud y readiness

Cada componente sirve /health, /readyz y /metrics en HEALTH_PORT. El listener principal también sirve /health, /version y /readyz bajo su prefijo de ruta.

/readyz responde 503 hasta que cada comprobación obligatoria haya pasado una vez: la configuración requerida y, donde el componente usa PostgreSQL en modo single-tenant, PostgreSQL. Después solo reporta su estado. No comprueba el adaptador ni Midaz.