> ## 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
> Configura el riel Pix Directo vía JD: endpoints de OAuth de JD y de JDPI, alojamiento de QR codes dinámicos con JWS, vínculo con el ledger de Midaz y ajustes de notificaciones.
Pix Directo, vía JD conecta tu ledger directamente al arreglo Pix a través del gateway de DICT y SPI de JD. DevOps define su comportamiento con variables de entorno en el momento del despliegue. Para cambiar una variable, reinicia el servicio. Esta página cubre las variables **propias de este riel**. Para los controles de almacén de datos, multi-tenancy, streaming, telemetría y autenticación que comparte cada servicio Go de Lerian, consulta [Fundamentos de configuración BYOC](/es/reference/byoc-configuration).
Estas variables describen un **despliegue single-tenant**. En la oferta gestionada multi-tenant (SaaS), los valores específicos de cliente que aparecen aquí — credenciales de JD, el vínculo con el ledger de Midaz, la conexión con el CRM, el host público de QR — los resuelve la plataforma de forma automática por tenant, nunca desde el entorno de un despliegue.
En las tablas siguientes, la columna **Predeterminado / Obligatorio** muestra el valor predeterminado. Un calificador en negrita (por ejemplo **Obligatorio**) marca las variables que debes definir. `—` 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. Esta página lista solo nombres de variables y comportamiento. No imprime ningún valor secreto.
## Servidor y puerto
El servicio escucha en la dirección de `SERVER_ADDRESS` (predeterminado `:8080`). Las sondas de liveness, readiness y version se enlazan a este mismo puerto. Consulta [Servidor](/es/reference/byoc-configuration#server) para los controles compartidos del servidor y [Puertos de red predeterminados](/es/reference/default-network-ports).
## Integración con JD
Credenciales y endpoints de la API de JD protegida con OAuth y de su superficie Pix (JDPI).
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| `JD_BASE_URL` | **Obligatorio** | URL base de la API de JD. |
| `JD_CLIENT_ID` | **Obligatorio** | Client ID de OAuth para la API de JD. |
| `JD_SECRET` | 🔒 **Obligatorio** | Client secret de OAuth para la API de JD. |
| `JD_GRANT_TYPE` | `client_credentials` | Tipo de grant de OAuth que se usa contra JD. |
| `JD_USE_SERVICE_SEGMENTS` | `false` | Enruta las llamadas por los segmentos de servicio de JD cuando es `true`. |
| `JDPI_MAX_RETRIES` | `2` | Intentos de reintento en una llamada fallida a JDPI. |
| `JDPI_RETRY_BASE_DELAY_MS` | `100` | Retraso base de backoff en milisegundos entre reintentos de JDPI. |
**Tu propio ISPB no es una variable de entorno.** Viene de la clave de systemplane `tenancy/jd_integration_binding`, campo `ispb`, y no hay fallback de entorno.
Mientras esa clave esté vacía, el riel arranca, responde a su sonda de salud y rechaza **todos** los pagos en **todas** las rutas de dinero con `409 PIX-0092`. Una batería de punta a punta juntó 86 rechazos por ese único valor sin aprovisionar. Escribir la clave sana un despliegue en ejecución en su solicitud siguiente, sin reinicio. El paso a paso está en [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup).
## Alojamiento de QR codes dinámicos
El riel aloja los payloads de QR dinámico firmados (JWS) y el conjunto de JWK que se usa para verificarlos, y sirve esos documentos bajo el host de `QRCODE_PUBLIC_BASE_URL`. Las formas de las rutas públicas, el formato de host sin esquema y el presupuesto de 77 caracteres de URL de payload de BACEN que estas rutas consumen son el contrato de la [sección de referencia de QR codes](/es/reference/interfaces/pix-jd/create-dynamic-qr-code); las variables siguientes definen las piezas que este despliegue controla.
| Variable | Predeterminado / Obligatorio | Descripción |
| -------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `QRCODE_PUBLIC_BASE_URL` | **Obligatorio** | Host sin esquema (FQDN) donde el plugin sirve los payloads de QR dinámico y el conjunto de JWK. |
| `QRCODE_PAYLOAD_PATH` | `v1/qrcodes/payload` | Segmento de ruta donde el plugin expone los payloads de QR firmados. |
| `QRCODE_JWK_PATH` | `v1/qrcodes/jwks` | Segmento de ruta donde el plugin expone el conjunto de JWK. |
| `QRCODE_JWS_CONTENT_TYPE` | `application/jose` | `Content-Type` que se devuelve para el payload firmado. |
| `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json` | `Content-Type` que se devuelve para el conjunto de JWK. |
## Vínculo con el ledger de Midaz
Contra qué organización, ledger, activo y cuenta externa de Midaz registra este riel los movimientos Pix, además de los endpoints del servicio de ledger y las credenciales machine-to-machine.
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `MIDAZ_ORGANIZATION_ID` | **Obligatorio** | UUID de la organización de Midaz dueña del ledger de Pix. |
| `MIDAZ_LEDGER_ID` | **Obligatorio** | UUID del ledger de Midaz para los asientos de Pix. |
| `MIDAZ_ASSET_ID` | **Obligatorio** (single-tenant) | **Código** del activo que se registra en las operaciones de Pix, por ejemplo `BRL`. Sin valor predeterminado. |
| `MIDAZ_EXTERNAL_ID` | **Obligatorio** (single-tenant) | **Alias** de la cuenta externa de compensación, por ejemplo `@external/BRL`. Sin valor predeterminado. |
| `MIDAZ_URL_ONBOARDING` | **Obligatorio** | URL del servicio de onboarding de Midaz. |
| `MIDAZ_URL_TRANSACTION` | **Obligatorio** | URL del servicio de transacción de Midaz. |
| `MIDAZ_CLIENT_ID` | — | Client ID de OAuth para M2M con Midaz. |
| `MIDAZ_CLIENT_SECRET` | 🔒 — | Client secret de OAuth para M2M con Midaz. |
| `MIDAZ_TIMEOUT` | `30000` | Timeout de las solicitudes a Midaz en milisegundos. |
No hay una dirección de Access Manager aparte para Midaz. El riel acuña su token saliente de Midaz contra el mismo Access Manager con el que valida los bearers entrantes, `PLUGIN_AUTH_HOST`. Consulta [Fundamentos de configuración BYOC](/es/reference/byoc-configuration).
`MIDAZ_ASSET_ID` y `MIDAZ_EXTERNAL_ID` no llevan **ningún valor predeterminado**, y los dos nombres mienten sobre su forma: el primero espera un código de activo (`BRL`) y el segundo un alias de cuenta (`@external/BRL`), a pesar del `_ID`. Un UUID en cualquiera de las dos responde `PIX-4011` sin nombrar ninguna cuenta, y dejar cualquiera de las dos sin definir rechaza todos los asientos con `409 PIX-0106`, nombrando las dos mitades.
Las claves de systemplane `tenant_policy/midaz.asset_id` y `tenant_policy/midaz.external_id` aceptan una escritura y responden `204`, pero nada las lee — las dos variables de arriba son la única fuente. Consulta [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup).
## Rutas contables
El riel registra cada flujo Pix en un par de rutas de operación de Midaz — una pata de crédito, una pata de débito, a lo largo de diez perfiles. **Esos veinte identificadores de ruta no son variables de entorno.** Viven en las claves de systemplane `tenant_policy/routing..operation_credit_route` y `tenant_policy/routing..operation_debit_route`, sin fallback de entorno.
Las variables `TRANSACTION_ROUTE_*` y `OPERATION_ROUTE_*` se eliminaron. Un valor remanente gana una advertencia de arranque y nunca se carga. Una pata de ruta ausente rechaza su propia ruta de dinero con `409 PIX-0105` mientras todos los demás flujos siguen funcionando, así que un único flujo que "no funciona" apunta primero aquí.
Los perfiles, los nombres exactos de las claves y cómo escribirlas están en [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup).
## Jobs y límites
| Variable | Predeterminado / Obligatorio | Descripción |
| ---------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------- |
| `JOBS_CRON` | `*/10 * * * * *` | Expresión cron del job de conciliación/mantenimiento. |
| `JOBS_CRON_TRANSACTIONS` | `*/10 * * * * *` | Expresión cron del job de procesamiento de transacciones. |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC` | `80` | Antigüedad en segundos tras la cual un cash-out pendiente se marca como atascado. |
| `MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE` | `100` · `3` | Límites superiores del tamaño de página de las listas y del rango de fechas. |
La ventana diaria en la que se contabilizan los límites de transacción **no** es una variable de entorno. Vive en las claves de systemplane `tenant_policy/transaction_limits.daily_period_init` y `tenant_policy/transaction_limits.daily_period_end`, en los dos modos de despliegue; ambas toman una hora de reloj de 0 a 23. Las variables retiradas `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` y `TRANSACTION_LIMIT_DAILY_PERIOD_END` se ignoran.
## Notificaciones
Notificaciones opcionales al cliente final para los eventos de Pix. Deja los bloques de proveedor sin definir para deshabilitar ese canal.
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------ |
| `SENDGRID_API_KEY` | 🔒 — | Clave de API de SendGrid para las notificaciones por email. |
| `SENDGRID_FROM_EMAIL` | — | Dirección del remitente de las notificaciones por email. |
| `SENDGRID_FROM_TEMPLATE` | — | ID de plantilla de SendGrid que se usa para el cuerpo del mensaje. |
| `TWILIO_ACCOUNT_SID` | 🔒 — | SID de cuenta de Twilio para las notificaciones por SMS. |
| `TWILIO_AUTH_TOKEN` | 🔒 — | Token de autenticación de Twilio para las notificaciones por SMS. |
| `TWILIO_PHONE_NUMBER` | — | Número de teléfono del remitente de las notificaciones por SMS. |
## CRM
| Variable | Predeterminado / Obligatorio | Descripción |
| ------------------- | ---------------------------- | ----------------------------------------------------------- |
| `CRM_URL` | — | URL del servicio de CRM para las consultas de contrapartes. |
| `CRM_CLIENT_ID` | — | Client ID de OAuth para M2M con el CRM. |
| `CRM_CLIENT_SECRET` | 🔒 — | Client secret de OAuth para M2M con el CRM. |
## Participantes indirectos
Solo es relevante si este despliegue liquida Pix por cuenta de otras instituciones.
| Variable | Predeterminado / Obligatorio | Descripción |
| ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `INDIRECTS_DELIVERY_ENCRYPTION_KEY` | 🔒 **Obligatorio** para alojar participantes indirectos | Clave AES-256 que cifra en reposo el secreto de entrega de cada participante indirecto. Exactamente 64 caracteres hexadecimales (32 bytes), de `openssl rand -hex 32`. Sin valor predeterminado. |
Sin esta clave, **todos** los registros de participante indirecto se rechazan con `409 PIX-0107` — y se rechazan antes de cualquier escritura, así que nunca se guarda un secreto en texto plano. Un valor ausente, en blanco o malformado producen el mismo rechazo: no hay valor predeterminado ni degradación a guardar el secreto en claro. El `409` significa "aprovisiónala", no "vuelve a intentar": su hermano reintentable es `503 PIX-0123`, que es lo que responde una clave que no se pudo **leer**.
El riel arranca sin ella. El arranque registra una advertencia y el proceso levanta sano, así que el síntoma llega en el primer registro, no en el despliegue. Se lee en el arranque, así que un cambio necesita un reinicio.
Consulta [Alojar participantes indirectos](/es/interfaces/pix-jd/hosting-indirect-participants) para el onboarding que desbloquea esta clave.
## Configuración de runtime (systemplane)
Este riel monta la API de administración de systemplane en su puerto principal, controlada por `SYSTEMPLANE_ENABLED`.
| Variable | Predeterminado / Obligatorio | Descripción |
| --------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| `SYSTEMPLANE_ENABLED` | `false` | Habilita la API de administración de configuración de runtime de systemplane. |
Cuando está habilitada, el servicio expone un plano autenticado para leer y escribir la configuración de runtime. Consulta [Systemplane](/es/reference/platform/systemplane/overview) para la API, los namespaces y los permisos necesarios.
Varios valores que este riel necesita son alcanzables **solo** a través de ese plano, en los dos modos de despliegue, y un despliegue que los deja sin definir arranca sano y rechaza dinero:
| Clave de systemplane | Qué lleva | Sin definir |
| ---------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| `tenancy/jd_integration_binding` | tu propio ISPB, en el campo `ispb` de una **cadena** JSON | `409 PIX-0092` en todas las rutas de dinero |
| `tenant_policy/routing..operation_{credit,debit}_route` | las veinte patas de ruta contable | `409 PIX-0105` en los flujos que usan el perfil ausente |
| `tenant_policy/transaction_limits.daily_period_{init,end}` | la ventana diaria de límites | la contabilización de límites no tiene ventana |
| `plugin-br-pix-jd.indirects/enabled` | si este tenant aloja participantes indirectos | la resolución de indirectos queda apagada |
Con `SYSTEMPLANE_ENABLED=false` el grupo de rutas `/system` no se monta en absoluto, así que todas las escrituras de configuración responden `404`, y una ruta de dinero que no puede leer su configuración responde el `503 PIX-0051` reintentable en lugar de un rechazo por aprovisionamiento. El permiso del lado de escritura es `systemplane:write`; sin él las escrituras responden `403`.
[Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup) recorre cada una de estas claves, con el cuerpo exacto que toma cada escritura y cómo confirmar que quedó aplicada.
## Salud y readiness
El riel expone `GET /health` (liveness) y `GET /readyz` (readiness) en el puerto principal, además de `/metrics` y `/version`. Consulta [Salud y readiness](/es/reference/health-and-readiness) para la forma de la respuesta y el comportamiento de arranque/drenaje.