Variables de entorno

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

Pix Lerian está formado por SPI, DICT Hub, COB Hub, sus workers y el adaptador de conectividad. Esta página enumera las entradas de despliegue que lee la versión v1.0.0. Los archivos .env.example exactos de cada componente siguen siendo la fuente de verdad para los valores predeterminados; usa las tablas para entender qué valores son compartidos y cuáles pertenecen a un solo componente.

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. SYSTEMPLANE_SECRET_MASTER_KEY y VALKEY_URL no forman parte del contrato v1.0.0.

​

Modelo de configuración

Cada componente carga valores de bootstrap desde su entorno. SPI, DICT Hub, COB Hub 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 conectividad lee su configuración de enrutamiento de Systemplane y no mantiene una base de datos de negocio.

Usa los ejemplos específicos de cada componente incluidos en la versión para SPI, DICT Hub, DICT VSync y COB Hub. Configura cada componente por separado; sus puertos, almacenes y dependencias obligatorias difieren.

Pix Lerian v1.0.0 está disponible para integración y pruebas con el adaptador de proveedor mock. La integración de mensajería nativa de SPI sigue en desarrollo y no está disponible en esta versión. No configures el adaptador mock como un riel de producción.

​

Identidad y despliegue compartidos

Variable	Componentes	Contrato
APPLICATION_NAME	Todos	Identidad del componente que se usa en logs, telemetría y licencias. 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 y de las sondas del componente.
DEPLOYMENT_MODE	Componentes de API y workers	local, saas o byoc. El valor predeterminado es local cuando falta el valor en la ruta single-tenant. El arranque multi-tenant valida el valor explícitamente.
REQUEST_TIMEOUT_SEC	Componentes HTTP	Tiempo de espera por solicitud, en segundos. El valor predeterminado es 30.
LICENSE_KEY	Componentes con licencia	Opcional en local; obligatorio en modos de despliegue no locales. Inyéctalo como secreto.
ORGANIZATION_IDS	Componentes con licencia	Ámbito de la licencia, como global o una lista de organizaciones separadas por comas.
SWAGGER_ENABLED	Componentes de API	Booleano estricto. Cuando no está definido, la superficie OpenAPI y Scalar de runtime está habilitada fuera de producción y deshabilitada en producción.

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 aplicación también requiere una configuración OAuth real del proveedor en modos de despliegue no locales. El modo local es el único que puede usar el token de proveedor no-op para desarrollo.

​

Persistencia y Valkey

Variable	Componentes	Contrato
DATABASE_URL	SPI, DICT Hub, COB Hub y VSync single-tenant	DSN de PostgreSQL para el almacén de negocio del componente. Es obligatorio donde el componente persiste datos de negocio.
SYSTEMPLANE_POSTGRES_DSN	Consumidores de Systemplane	DSN de PostgreSQL para el almacén de configuración de runtime. En los componentes de API 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.
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 Valkey no está configurado; algunas mutaciones de SPI y DICT 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 v1.0.0 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	Fallback de organización single-tenant. Los despliegues multi-tenant resuelven la organización por tenant.
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. Para la integración local, apúntala al servicio adapter-provider-mock.
MIDAZ_BASE_URL	SPI	URL base de Midaz para las operaciones de onboarding y transacciones.
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.

Son configuraciones entre servicios. No ponen a disposición el conector nativo de SPI; esa integración no forma parte de la superficie disponible de la versión v1.0.0.

​

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	3600	TTL del lease del bloqueo de mutaciones, en segundos.
VSYNC_STUCK_JOB_SWEEP_TICK_SEC	120	Intervalo entre los análisis de trabajos atascados, en segundos.
RABBITMQ_URI	—	URI de RabbitMQ para la cola de conciliación de archivos en modo single-tenant. 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 y VSYNC_FILE_RECON_ENABLED 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.

​

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.

OpenTelemetry usa variables OTEL_*. Consulta Configuración de BYOC para los parámetros compartidos de telemetría y transporte del broker.

​

Despliegue multi-tenant

Cuando MULTI_TENANT_ENABLED=true, configura MULTI_TENANT_URL y MULTI_TENANT_SERVICE_API_KEY. No definas un ORGANIZATION_ID estático en el modo multi-tenant de COB. Las credenciales de servicio y los valores de enrutamiento específicos del tenant se resuelven desde el almacén de configuración de runtime; los valores de entorno sirven como fallbacks de primer arranque o single-tenant cuando el componente los define.

​

Salud y readiness

Las rutas de las sondas y los prefijos de ruta pertenecen a la configuración de despliegue del componente. No supongas que todos los componentes exponen /health o /readyz sin prefijo; usa las rutas del chart de la versión y de la configuración de bootstrap del componente.