> ## 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, bases de datos, integraciones, conectividad y eventos.
Pix Lerian está formado por los dominios SPI, DICT y COB y por el adaptador de conectividad. El equipo de DevOps configura su comportamiento con variables de entorno en el momento del despliegue. Esta página cubre las variables **específicas de esta interfaz**. Para los parámetros compartidos de servidor, telemetría, autenticación, streaming y descubrimiento de servicios, consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita marca una variable que debes definir en el contexto descrito. `—` significa que no hay valor predeterminado. `🔒` marca un **secreto**. Inyéctalo en el momento del despliegue desde tu almacén de secretos y nunca lo incluyas en un commit.
## Cómo funcionan juntos `values.yaml` y Systemplane
Para el despliegue inicial, los clientes entregan la configuración a través del `values.yaml` del Helm chart que acompaña al release. Después de la inicialización, las claves de runtime se gestionan mediante Systemplane.
El chart convierte los valores en variables de entorno del pod:
| Tipo | Ubicación en `values.yaml` | Comportamiento |
| --------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Configuración de despliegue | `.configmap.` | Helm renderiza la configuración y el Deployment inyecta las claves como variables de entorno. |
| Secreto | Configuración del Secret del componente | Inyecta el valor en el momento del despliegue desde el almacén de secretos y nunca lo incluyas en un commit. |
| Semilla de runtime | `spiSystemplane`, `dictSystemplane` o `cobSystemplane` | Define la variable en el bloque de Systemplane que es dueño del dominio. El componente usa el valor para inicializar la configuración de runtime. |
Cada dominio tiene un componente de Systemplane dedicado. El flujo es:
Helm crea el ConfigMap de cada componente y referencia su Secret. El Deployment carga ambos con `envFrom` cuando el pod arranca.
El componente de Systemplane lee las variables de entorno mapeadas y aplica una semilla solo mientras el valor almacenado siga siendo igual al predeterminado registrado. Una anulación administrativa existente no se sobrescribe.
Las APIs de dominio y los workers leen el almacén de Systemplane. La definición de cada clave determina si admite actualizaciones en runtime o exige un reinicio.
Para las variables de bootstrap, actualiza `values.yaml`, ejecuta el upgrade y haz el rollout del componente. Después de la inicialización, cambia las claves de runtime mediante Systemplane. Cambiar solo `values.yaml` no reemplaza una anulación almacenada.
* **Variables de entorno de bootstrap directas:** `APPLICATION_NAME`, `SERVER_ADDRESS`, `DATABASE_URL`, `SYSTEMPLANE_POSTGRES_DSN`, `SYSTEMPLANE_SECRET_MASTER_KEY`, `VALKEY_URL`, `LICENSE_KEY`, `ORGANIZATION_IDS`, `SWAGGER_ENABLED`, `RABBITMQ_ENABLED`, `RABBITMQ_URI` y `STREAMING_*`.
* **También se usan como semillas de Systemplane:** `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC`, `PLUGIN_AUTH_*`, `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*`, `COB_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` y `VSYNC_*`.
Define las semillas en el bloque de Systemplane que es dueño del dominio, no en el bloque de la API ni en el del worker. Las claves sensibles siguen marcadas con `🔒` en las tablas siguientes.
| Bloque del chart | Semillas específicas del dominio |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `spiSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `MIDAZ_*`, `CRM_*`, `DICT_*` y `COB_*`. |
| `dictSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `CRM_*`, `SPI_*`, `KEY_CACHE_TTL_SEC` y `VSYNC_*`. |
| `cobSystemplane` | `ORGANIZATION_ID`, `ISPB`, `ADAPTER_BASE_URL`, `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET` y `DICT_ROUTING_MODE`. |
Los tres bloques también reciben las semillas compartidas `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC` y `PLUGIN_AUTH_*`.
Pix Lerian no expone descubrimiento de catálogo. Usa esta página como la referencia de claves admitidas y consulta [Systemplane](/es/reference/platform/systemplane/overview) para el modelo de autorización y de actualización en runtime.
## Servidor y modo de despliegue
Cada componente recibe `SERVER_ADDRESS` de `.configmap.SERVER_ADDRESS`. El valor debe coincidir con `.service.port` en el mismo `values.yaml`. Las sondas de liveness y readiness usan ese puerto. Consulta [Servidor](/es/reference/byoc-configuration#server) y [Salud y readiness](/es/reference/health-and-readiness).
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLICATION_NAME` | Definido por el chart | Identidad del componente que se usa para licenciamiento, logs y telemetría. No anules el valor que entrega el chart. |
| `SERVER_ADDRESS` | Definido por el chart | Dirección HTTP de escucha en formato `host:port`; debe coincidir con el `targetPort` del componente. |
| `DEPLOYMENT_MODE` | `byoc` | Modo de despliegue que se entrega a los clientes. Mantén el valor que define el chart. |
| `REQUEST_TIMEOUT_SEC` | `30` | Timeout predeterminado de las solicitudes HTTP, en segundos. |
| `PLUGIN_AUTH_ENABLED` | `false` | Exige autenticación de Access Manager en las rutas protegidas. Habilítalo en producción. |
| `PLUGIN_AUTH_URL` | **Obligatorio con autenticación o M2M** | URL base de Access Manager que se usa para la autenticación entrante y los clientes OAuth entre componentes. |
| `LICENSE_KEY` | 🔒 **Obligatorio en BYOC** | Clave de licencia de Pix Lerian. |
| `ORGANIZATION_IDS` | **Obligatorio cuando `LICENSE_KEY` está definida** | Ámbito de la licencia: `global` o una lista de organizaciones separadas por comas. Usa este nombre exacto; los binarios actuales no leen `LICENSE_ORGANIZATION_IDS`. |
| `SWAGGER_ENABLED` | Habilitado fuera de producción | Controla la especificación OpenAPI y la interfaz de exploración que sirve el componente. |
## Persistencia y configuración de runtime
SPI, DICT, COB y el adaptador mantienen almacenes separados. No reutilices la misma base de datos lógica entre dominios.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | 🔒 **Obligatorio para los componentes con persistencia** | DSN de PostgreSQL del componente que usan los servicios que persisten datos de negocio y los componentes de configuración. |
| `SYSTEMPLANE_POSTGRES_DSN` | 🔒 `DATABASE_URL` en SPI, DICT y COB | DSN dedicado para leer la configuración de runtime. Usa el valor que renderiza el chart del componente. |
| `SYSTEMPLANE_SECRET_MASTER_KEY` | 🔒 **Obligatorio en BYOC** | Clave AES-256-GCM de 32 bytes que se usa para cifrar los valores secretos en el almacén de configuración. |
| `VALKEY_URL` | 🔒 — | URL de Valkey/Redis que se usa para idempotencia, deduplicación y cache. Algunos flujos se degradan o fallan de forma segura cuando no está definida. |
| `KEY_CACHE_TTL_SEC` | `60` | TTL del cache de consultas de claves DICT, en segundos. |
Los valores de identidad, las URL y las credenciales que se declaran en los componentes de configuración se usan **solo como semillas de la primera inicialización**. Cuando una clave ya existe en el almacén de runtime, reiniciar el servicio no sobrescribe el valor. Haz los cambios posteriores mediante el plano de configuración autenticado.
## Identidad de la institución
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------ | ------------------------------------------ | ---------------------------------------------------------------- |
| `ORGANIZATION_ID` | **Obligatorio para BYOC** | UUID de la organización de Midaz que usan SPI, DICT y COB. |
| `ISPB` | **Obligatorio para BYOC** | Identificador de ocho dígitos de la institución participante. |
| `ADAPTER_BASE_URL` | **Obligatorio para los flujos conectados** | URL base del adaptador de conectividad que usan SPI, DICT y COB. |
## Midaz y CRM
SPI usa Midaz para la contabilidad. SPI y DICT usan CRM para validar cuentas y titulares en los flujos que necesitan esta información.
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| `MIDAZ_BASE_URL` | **Obligatorio para la contabilidad** | URL base que comparten las APIs de onboarding y de transacción de Midaz. |
| `MIDAZ_LEDGER_ID` | **Obligatorio para la contabilidad** | UUID del ledger que registra las operaciones de Pix. |
| `MIDAZ_CLIENT_ID` | **Obligatorio con autenticación** | Client ID de OAuth que usa SPI para llamar a Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 **Obligatorio con autenticación** | Client secret de OAuth que usa SPI para llamar a Midaz. |
| `CRM_BASE_URL` | **Obligatorio para los flujos de validación** | URL base de CRM. |
| `CRM_CLIENT_ID` | **Obligatorio con autenticación** | Client ID de OAuth que usan SPI y DICT para llamar a CRM. |
| `CRM_CLIENT_SECRET` | 🔒 **Obligatorio con autenticación** | Client secret de OAuth que usan SPI y DICT para llamar a CRM. |
## Integraciones entre dominios
Las URL siguientes apuntan a componentes desplegados de Pix Lerian. Configuran la comunicación entre SPI, DICT, COB y el adaptador sin cambiar el contrato que consume la aplicación cliente.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `DICT_BASE_URL` | **Obligatorio en los componentes que consultan DICT** | URL base del dominio DICT. La usan SPI, COB y el adaptador. |
| `DICT_CLIENT_ID` | **Obligatorio con autenticación** | Client ID de OAuth para las llamadas a DICT. |
| `DICT_CLIENT_SECRET` | 🔒 **Obligatorio con autenticación** | Client secret de OAuth para las llamadas a DICT. |
| `DICT_ROUTING_MODE` | `hub` | Nivel de descubrimiento de DICT: `hub` o `proxy`. La URL configurada debe apuntar al mismo nivel. |
| `COB_BASE_URL` | **Obligatorio en los componentes que consultan COB** | URL base del dominio COB. La usan SPI y el adaptador. |
| `COB_CLIENT_ID` | **Obligatorio con autenticación** | Client ID de OAuth para las llamadas a COB. |
| `COB_CLIENT_SECRET` | 🔒 **Obligatorio con autenticación** | Client secret de OAuth para las llamadas a COB. |
| `COB_ROUTING_MODE` | `hub` | Nivel de descubrimiento de COB: `hub` o `proxy`. La URL configurada debe apuntar al mismo nivel. |
| `SPI_BASE_URL` | **Obligatorio en los componentes que consultan SPI** | URL base del dominio SPI. La usan DICT y el adaptador. |
| `SPI_CLIENT_ID` | **Obligatorio con autenticación** | Client ID de OAuth para las llamadas a SPI. |
| `SPI_CLIENT_SECRET` | 🔒 **Obligatorio con autenticación** | Client secret de OAuth para las llamadas a SPI. |
## Conciliación de DICT (VSync)
El worker de VSync concilia la base de datos DICT persistida con la fuente regulatoria. El transporte de RabbitMQ está habilitado de forma predeterminada. Cuando está activo, necesita una URI válida.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `VSYNC_ENABLED` | `true` | Habilita el worker de conciliación. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Habilita la conciliación basada en archivos. |
| `RABBITMQ_ENABLED` | `true` | Habilita el transporte de RabbitMQ de VSync. |
| `RABBITMQ_URI` | 🔒 **Obligatorio cuando `RABBITMQ_ENABLED=true`** | URI de conexión de RabbitMQ. Usa `amqps://` en producción. |
| `VSYNC_CHUNK_CONSUMER_WORKERS` | `3` | Cantidad de consumidores de chunk en paralelo. |
| `VSYNC_JOBS_CONSUMER_WORKERS` | `3` | Cantidad de consumidores de jobs en paralelo. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Intervalo, en segundos, entre los barridos de jobs atascados. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Tiempo, en minutos, tras el cual un chunk se considera atascado. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Cantidad máxima de intentos de un job de conciliación. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Cantidad máxima de páginas que se procesan por ciclo de sincronización de eventos. |
| `VSYNC_GATE_TTL_SEC` | `3600` | TTL, en segundos, del bloqueo que protege las mutaciones durante la conciliación. |
## Streaming y observabilidad
La publicación de CloudEvents desde SPI, DICT y COB usa la familia `STREAMING_*` y permanece deshabilitada de forma predeterminada. Cuando `STREAMING_ENABLED=true`, `STREAMING_BROKERS` es obligatorio. Si defines `STREAMING_CLOUDEVENTS_SOURCE`, el único valor aceptado es `plugin-br-pix-lerian`. Consulta [Streaming y outbox](/es/reference/byoc-configuration#streaming-and-outbox) y [Observabilidad](/es/reference/byoc-configuration#observability) para el resto de los parámetros de broker, TLS, SASL y OpenTelemetry.
## Fuente de configuración de bootstrap
El `values.yaml` del Helm chart entregado es la fuente de bootstrap del despliegue. Mantenlo alineado con la versión del chart y conserva los nombres de los bloques de componente y de las variables. Inyecta los secretos desde el almacén de secretos y nunca guardes credenciales en texto plano en el repositorio. Después de sembrar los valores, usa Systemplane para cambiar las claves de runtime.
## Salud y readiness
Configura las sondas mediante `.livenessProbe.path` y `.readinessProbe.path` en `values.yaml`. Las rutas predeterminadas varían según el componente. No supongas rutas `/health` y `/readyz` sin prefijo.
La sonda de liveness verifica si el proceso está vivo. La sonda de readiness verifica si las dependencias y la configuración necesarias permiten que el componente reciba tráfico. No enrutes tráfico a un componente hasta que su sonda de readiness tenga éxito.