> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/es/reference/byoc-configuration) 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.