> ## 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á compuesto por los dominios SPI, DICT y COB y por el adaptador de conectividad. El equipo de DevOps configura su comportamiento mediante 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 service discovery, consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration).
En las tablas siguientes, la columna **Valor por defecto / Requerida** muestra el valor predeterminado. Un calificador en negrita identifica una variable que debes definir en el contexto descrito. `—` significa que no hay valor predeterminado. `🔒` identifica un **secreto**: inyéctalo durante el despliegue desde tu almacén de secretos y nunca lo incluyas en un commit.
## Cómo se relacionan `values.yaml` y Systemplane
Para el despliegue inicial, el cliente proporciona la configuración mediante el `values.yaml` del Helm chart entregado con el release. Después de la inicialización, las claves de runtime se administran mediante Systemplane.
El chart transforma los values 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 de Secret del componente | Inyecta el valor durante el despliegue desde el secret store y nunca lo incluyas en un commit. |
| Seed de runtime | `spiSystemplane`, `dictSystemplane` o `cobSystemplane` | Define la variable en el bloque Systemplane que pertenece al dominio. El componente usa el valor para inicializar la configuración de runtime. |
Cada dominio tiene un componente dedicado de Systemplane. El flujo es:
Helm crea el ConfigMap y referencia el Secret de cada componente. El Deployment carga ambos con `envFrom` cuando se inicia el pod.
El componente Systemplane lee las variables de entorno mapeadas y aplica un seed solo mientras el valor almacenado coincide con el valor predeterminado registrado. No sobrescribe un override administrativo existente.
Las APIs y los workers del dominio leen el store de Systemplane. La definición de cada clave determina si admite actualizaciones en runtime o si requiere un reinicio.
Para variables de bootstrap, actualiza `values.yaml`, ejecuta el upgrade y realiza el rollout del componente. Después de la inicialización, modifica las claves de runtime mediante Systemplane; cambiar solo `values.yaml` no reemplaza un override almacenado.
* **Variables de entorno directas de bootstrap:** `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 usadas como seeds 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 los seeds en el bloque de Systemplane que pertenece al dominio, no en el bloque de la API o del worker. Las claves sensibles siguen marcadas con `🔒` en las tablas siguientes.
| Bloque del chart | Seeds específicos 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 los seeds compartidos `DEPLOYMENT_MODE`, `REQUEST_TIMEOUT_SEC` y `PLUGIN_AUTH_*`.
Pix Lerian no expone el descubrimiento del catálogo. Usa esta página como referencia de las claves admitidas y consulta [Systemplane](/es/reference/systemplane/overview) para conocer el modelo de autorización y actualización de runtime.
## Servidor y modo de despliegue
Cada componente recibe `SERVER_ADDRESS` desde `.configmap.SERVER_ADDRESS`; el valor debe coincidir con `.service.port` en el mismo `values.yaml`. Las probes de liveness y readiness usan ese puerto. Consulta [Servidor](/es/reference/byoc-configuration#servidor) y [Salud y disponibilidad](/es/reference/health-and-readiness).
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLICATION_NAME` | Definida por el chart | Identidad del componente usada para licenciamiento, logs y telemetría. No sobrescribas el valor proporcionado por el chart. |
| `SERVER_ADDRESS` | Definida 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 entregado al cliente. Mantén el valor definido por 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. Actívala en producción. |
| `PLUGIN_AUTH_URL` | **Obligatoria con autenticación o M2M** | URL base de Access Manager usada para autenticación de entrada y clientes OAuth entre componentes. |
| `LICENSE_KEY` | 🔒 **Obligatoria en BYOC** | Clave de licencia de Pix Lerian. |
| `ORGANIZATION_IDS` | **Obligatoria cuando `LICENSE_KEY` está definida** | Alcance de la licencia: `global` o lista de organizaciones separadas por comas. Usa exactamente este nombre; los binarios actuales no leen `LICENSE_ORGANIZATION_IDS`. |
| `SWAGGER_ENABLED` | Activado fuera de producción | Controla la especificación OpenAPI y la interfaz de exploración expuestas por el componente. |
## Persistencia y configuración de runtime
SPI, DICT, COB y el adaptador mantienen stores separados. No reutilices la misma base de datos lógica entre dominios.
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | 🔒 **Obligatoria para componentes con persistencia** | DSN PostgreSQL del componente usada por servicios que persisten datos de negocio y por 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 renderizado por el chart del componente. |
| `SYSTEMPLANE_SECRET_MASTER_KEY` | 🔒 **Obligatoria en BYOC** | Clave AES-256-GCM de 32 bytes usada para cifrar valores secretos en el store de configuración. |
| `VALKEY_URL` | 🔒 — | URL de Valkey/Redis usada para idempotencia, deduplicación y caché. Algunos flujos degradan o fallan de forma segura cuando no está definida. |
| `KEY_CACHE_TTL_SEC` | `60` | TTL, en segundos, de la caché de consultas de llaves en DICT. |
Los valores de identidad, URLs y credenciales declarados en los componentes de configuración se usan como **seeds solo en la primera inicialización**. Después de que una clave existe en el store de runtime, reiniciar el servicio no sobrescribe el valor. Realiza los cambios posteriores mediante el plano autenticado de configuración.
## Identidad de la institución
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------ | ------------------------------------------ | ----------------------------------------------------------------- |
| `ORGANIZATION_ID` | **Obligatoria para BYOC** | UUID de la organización Midaz usada por SPI, DICT y COB. |
| `ISPB` | **Obligatoria para BYOC** | Identificador de ocho dígitos de la institución participante. |
| `ADAPTER_BASE_URL` | **Obligatoria para los flujos conectados** | URL base del adaptador de conectividad usada por SPI, DICT y COB. |
## Midaz y CRM
SPI usa Midaz para la contabilización. SPI y DICT usan CRM para validar cuentas y titulares en los flujos que requieren esa información.
| Variable | Valor por defecto / Requerida | Descripción |
| --------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| `MIDAZ_BASE_URL` | **Obligatoria para contabilización** | URL base compartida por las APIs de onboarding y transacciones de Midaz. |
| `MIDAZ_LEDGER_ID` | **Obligatoria para contabilización** | UUID del ledger que registra las operaciones Pix. |
| `MIDAZ_CLIENT_ID` | **Obligatoria con autenticación** | OAuth client ID usado por SPI para llamar a Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 **Obligatoria con autenticación** | OAuth client secret usado por SPI para llamar a Midaz. |
| `CRM_BASE_URL` | **Obligatoria en flujos de validación** | URL base de CRM. |
| `CRM_CLIENT_ID` | **Obligatoria con autenticación** | OAuth client ID usado por SPI y DICT para llamar a CRM. |
| `CRM_CLIENT_SECRET` | 🔒 **Obligatoria con autenticación** | OAuth client secret usado por SPI y DICT para llamar a CRM. |
## Integraciones entre dominios
Las URLs siguientes apuntan a los componentes desplegados de Pix Lerian. Configuran la comunicación entre SPI, DICT, COB y el adaptador sin cambiar el contrato consumido por la aplicación cliente.
| Variable | Valor por defecto / Requerida | Descripción |
| -------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `DICT_BASE_URL` | **Obligatoria en componentes que consultan DICT** | URL base del dominio DICT. La usan SPI, COB y el adaptador. |
| `DICT_CLIENT_ID` | **Obligatoria con autenticación** | OAuth client ID para llamadas a DICT. |
| `DICT_CLIENT_SECRET` | 🔒 **Obligatoria con autenticación** | OAuth client secret para llamadas a DICT. |
| `DICT_ROUTING_MODE` | `hub` | Tier de descubrimiento de DICT: `hub` o `proxy`. La URL configurada debe apuntar al mismo tier. |
| `COB_BASE_URL` | **Obligatoria en componentes que consultan COB** | URL base del dominio COB. La usan SPI y el adaptador. |
| `COB_CLIENT_ID` | **Obligatoria con autenticación** | OAuth client ID para llamadas a COB. |
| `COB_CLIENT_SECRET` | 🔒 **Obligatoria con autenticación** | OAuth client secret para llamadas a COB. |
| `COB_ROUTING_MODE` | `hub` | Tier de descubrimiento de COB: `hub` o `proxy`. La URL configurada debe apuntar al mismo tier. |
| `SPI_BASE_URL` | **Obligatoria en componentes que consultan SPI** | URL base del dominio SPI. La usan DICT y el adaptador. |
| `SPI_CLIENT_ID` | **Obligatoria con autenticación** | OAuth client ID para llamadas a SPI. |
| `SPI_CLIENT_SECRET` | 🔒 **Obligatoria con autenticación** | OAuth client secret para llamadas a SPI. |
## Reconciliación de DICT (VSync)
El worker VSync reconcilia la base persistida de DICT con la fuente regulatoria. El transporte RabbitMQ está habilitado de forma predeterminada; cuando está activo, exige una URI válida.
| Variable | Valor por defecto / Requerida | Descripción |
| ------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------- |
| `VSYNC_ENABLED` | `true` | Activa el worker de reconciliación. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Activa la reconciliación basada en archivos. |
| `RABBITMQ_ENABLED` | `true` | Activa el transporte RabbitMQ de VSync. |
| `RABBITMQ_URI` | 🔒 **Obligatoria cuando `RABBITMQ_ENABLED=true`** | URI de conexión con RabbitMQ. Usa `amqps://` en producción. |
| `VSYNC_CHUNK_CONSUMER_WORKERS` | `3` | Número de consumers paralelos de chunks. |
| `VSYNC_JOBS_CONSUMER_WORKERS` | `3` | Número de consumers paralelos de jobs. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Intervalo, en segundos, entre búsquedas de jobs bloqueados. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Tiempo, en minutos, para considerar bloqueado un chunk. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Número máximo de intentos de un job de reconciliación. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Máximo de páginas procesadas por ciclo de sincronización de eventos. |
| `VSYNC_GATE_TTL_SEC` | `3600` | TTL, en segundos, del bloqueo que protege mutaciones durante la reconciliación. |
## Streaming y observabilidad
La publicación de CloudEvents de SPI, DICT y COB usa la familia `STREAMING_*` y permanece desactivada de forma predeterminada. Cuando `STREAMING_ENABLED=true`, `STREAMING_BROKERS` es obligatoria. Si defines `STREAMING_CLOUDEVENTS_SOURCE`, el único valor aceptado es `plugin-br-pix-lerian`. Consulta [Streaming y outbox](/es/reference/byoc-configuration#streaming-y-outbox) y [Observabilidad](/es/reference/byoc-configuration#observabilidad) para los demás 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 y de las variables. Inyecta secretos desde el secret store y nunca almacenes credenciales en texto plano en el repositorio. Después del seed, usa Systemplane para cambiar las claves de runtime.
## Salud y readiness
Configura las probes mediante `.livenessProbe.path` y `.readinessProbe.path` en `values.yaml`. Los paths predeterminados varían por componente; no asumas `/health` y `/readyz` sin prefijo.
La liveness probe verifica si el proceso está activo. La readiness probe verifica si las dependencias y configuraciones obligatorias permiten que el componente reciba tráfico. No dirijas tráfico a un componente hasta que su readiness probe responda correctamente.