> ## 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 de despliegue para el rail Pix Directo, vía JD: integración con JD, hosting de QR dinámico, vínculo con el ledger Midaz, rutas de transacción y notificaciones.

Pix Directo, vía JD conecta tu ledger directamente con el arreglo Pix a través del gateway DICT y SPI de JD. Su comportamiento se configura mediante variables de entorno que DevOps define en el momento del despliegue; cambiar una requiere reiniciar el servicio. Esta página cubre las variables **distintivas de este rail**; para los ajustes de almacén de datos, multi-tenancy, streaming, telemetría y autenticación compartidos por todos los servicios Go de Lerian, consulta la [referencia de configuración BYOC](/es/reference/byoc-configuration).

<Note>
  En las tablas siguientes, la columna **Valor por defecto / Requerida** muestra el valor por defecto; un calificador en negrita (por ejemplo **Requerida**) marca las variables que debes definir. `—` significa que no hay valor por defecto. `🔒` marca un **secreto**: inyéctalo en el momento del despliegue desde tu almacén de secretos y nunca lo guardes en el repositorio. Esta página solo enumera los nombres de las variables y su comportamiento; no imprime ningún valor secreto.
</Note>

## Servidor y puerto

El servicio escucha en la dirección de `SERVER_ADDRESS` (por defecto `:8080`). Las sondas de liveness, readiness y versión se enlazan a este mismo puerto. Consulta [Servidor](/es/reference/byoc-configuration#servidor) para los ajustes de servidor compartidos y [Puertos de red predeterminados](/es/reference/default-network-ports).

## Integración con JD

Credenciales y endpoints para la API asegurada por OAuth de JD y su superficie Pix (JDPI).

| Variable                   | Valor por defecto / Requerida | Descripción                                                                  |
| -------------------------- | ----------------------------- | ---------------------------------------------------------------------------- |
| `JD_BASE_URL`              | **Requerida**                 | URL base de la API de JD.                                                    |
| `JD_CLIENT_ID`             | **Requerida**                 | Client ID de OAuth para la API de JD.                                        |
| `JD_SECRET`                | 🔒 **Requerida**              | Client secret de OAuth para la API de JD.                                    |
| `JD_GRANT_TYPE`            | `client_credentials`          | Tipo de grant de OAuth usado contra JD.                                      |
| `JD_BANK_ID`               | **Requerida**                 | Tu identificador de institución en JD.                                       |
| `JD_USE_SERVICE_SEGMENTS`  | `false`                       | Enruta las llamadas a través de los service segments de JD cuando es `true`. |
| `JD_PIX_URL`               | **Requerida**                 | URL base de la API Pix (JDPI) de JD.                                         |
| `JD_PIX_CLIENT_ID`         | **Requerida**                 | Client ID de OAuth para la API Pix de JD.                                    |
| `JD_PIX_CLIENT_SECRET`     | 🔒 **Requerida**              | Client secret de OAuth para la API Pix de JD.                                |
| `JDPI_MAX_RETRIES`         | `2`                           | Intentos de reintento ante una llamada JDPI fallida.                         |
| `JDPI_RETRY_BASE_DELAY_MS` | `100`                         | Retardo de backoff base en milisegundos entre reintentos de JDPI.            |

## Hosting de código QR dinámico

El rail aloja payloads de QR dinámico firmados (JWS) y el conjunto de JWK usado para verificarlos. `QRCODE_PUBLIC_BASE_URL` es la base accesible desde el exterior bajo la cual se sirven esos documentos.

| Variable                   | Valor por defecto / Requerida | Descripción                                                                        |
| -------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| `QRCODE_PUBLIC_BASE_URL`   | **Requerida**                 | URL base pública donde se sirven los payloads de QR dinámico y el conjunto de JWK. |
| `QRCODE_PAYLOAD_PATH`      | **Requerida**                 | Segmento de ruta donde se exponen los payloads de QR firmados.                     |
| `QRCODE_JWK_PATH`          | **Requerida**                 | Segmento de ruta donde se expone el conjunto de JWK.                               |
| `QRCODE_JWS_CONTENT_TYPE`  | `application/jose`            | `Content-Type` devuelto para el payload firmado.                                   |
| `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json`    | `Content-Type` devuelto para el conjunto de JWK.                                   |

## Vínculo con el ledger Midaz

Qué organización, ledger, activo y cuenta externa de Midaz usa este rail para contabilizar los movimientos Pix, además de los endpoints del servicio del ledger y las credenciales máquina a máquina.

| Variable                | Valor por defecto / Requerida | Descripción                                               |
| ----------------------- | ----------------------------- | --------------------------------------------------------- |
| `MIDAZ_ORGANIZATION_ID` | **Requerida**                 | UUID de la organización Midaz propietaria del ledger Pix. |
| `MIDAZ_LEDGER_ID`       | **Requerida**                 | UUID del ledger Midaz para las contabilizaciones Pix.     |
| `MIDAZ_ASSET_ID`        | **Requerida**                 | Activo (moneda) contabilizado para las operaciones Pix.   |
| `MIDAZ_EXTERNAL_ID`     | **Requerida**                 | Cuenta externa usada como contraparte de liquidación Pix. |
| `MIDAZ_URL_ONBOARDING`  | **Requerida**                 | URL del servicio de onboarding de Midaz.                  |
| `MIDAZ_URL_TRANSACTION` | **Requerida**                 | URL del servicio de transacciones de Midaz.               |
| `MIDAZ_AUTH_ADDRESS`    | —                             | URL de Access Manager para los tokens M2M de Midaz.       |
| `MIDAZ_CLIENT_ID`       | —                             | Client ID de OAuth para M2M de Midaz.                     |
| `MIDAZ_CLIENT_SECRET`   | 🔒 —                          | Client secret de OAuth para M2M de Midaz.                 |
| `MIDAZ_TIMEOUT`         | `30000`                       | Tiempo de espera de la petición a Midaz en milisegundos.  |

## Rutas de transacción y operación

Los flujos Pix de cash-in, cash-out, reversa e intra-PSP se mapean a rutas de transacción y operación de Midaz con nombre. Define un valor por flujo para que el plugin contabilice cada evento Pix en la ruta correcta.

| Variable                                                                                             | Valor por defecto / Requerida | Descripción                                                                                                    |
| ---------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `TRANSACTION_ROUTE_CASHIN` · `TRANSACTION_ROUTE_CASHIN_QRCODE` · `TRANSACTION_ROUTE_CASHIN_REVERSAL` | **Requerida**                 | IDs de ruta de transacción para la familia de cash-in (estándar, código QR, reversa).                          |
| `TRANSACTION_ROUTE_CASHOUT` · `TRANSACTION_ROUTE_CASHOUT_REVERSAL`                                   | **Requerida**                 | IDs de ruta de transacción para la familia de cash-out.                                                        |
| `TRANSACTION_ROUTE_INTRAPSP` · `TRANSACTION_ROUTE_INTRAPSP_REVERSAL`                                 | **Requerida**                 | IDs de ruta de transacción para las transferencias intra-PSP y sus reversas.                                   |
| `OPERATION_ROUTE_CASHIN_*`                                                                           | **Requerida**                 | IDs de ruta de operación para cada leg de cash-in (crédito, débito, código QR, externa, variantes de reversa). |
| `OPERATION_ROUTE_CASHOUT_*`                                                                          | **Requerida**                 | IDs de ruta de operación para cada leg de cash-out (crédito, débito, externa, variantes de reversa).           |

<Note>
  `OPERATION_ROUTE_CASHIN_*` y `OPERATION_ROUTE_CASHOUT_*` representan exactamente doce variables concretas de mapeo de ruta por leg (ocho de cash-in, cuatro de cash-out). Cada una mapea un leg del pipeline a un ID de ruta de operación de Midaz; define cada una de forma explícita:

  **Cash-in (8):** `OPERATION_ROUTE_CASHIN_CREDIT`, `OPERATION_ROUTE_CASHIN_CREDIT_QRCODE`, `OPERATION_ROUTE_CASHIN_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHIN_DEBIT`, `OPERATION_ROUTE_CASHIN_DEBIT_QRCODE_EXTERNAL`, `OPERATION_ROUTE_CASHIN_DEBIT_REVERSAL_EXTERNAL`, `OPERATION_ROUTE_CASHIN_REVERSAL_CREDIT`, `OPERATION_ROUTE_CASHIN_REVERSAL_DEBIT`

  **Cash-out (4):** `OPERATION_ROUTE_CASHOUT_CREDIT_EXTERNAL`, `OPERATION_ROUTE_CASHOUT_CREDIT_REVERSAL`, `OPERATION_ROUTE_CASHOUT_DEBIT`, `OPERATION_ROUTE_CASHOUT_DEBIT_REVERSAL_EXTERNAL`
</Note>

## Trabajos y límites

| Variable                                                                     | Valor por defecto / Requerida | Descripción                                                                                           |
| ---------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `JOBS_CRON`                                                                  | `*/10 * * * * *`              | Expresión cron para el trabajo de reconciliación/mantenimiento.                                       |
| `JOBS_CRON_TRANSACTIONS`                                                     | —                             | Expresión cron para el trabajo de procesamiento de transacciones.                                     |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC`                                         | —                             | Antigüedad en segundos tras la cual una transacción pendiente se trata como atascada y se reconcilia. |
| `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` · `TRANSACTION_LIMIT_DAILY_PERIOD_END` | —                             | Inicio y fin de la ventana diaria usada para la contabilidad de límites de transacción.               |
| `MAX_PAGINATION_LIMIT` · `MAX_PAGINATION_MONTH_DATE_RANGE`                   | —                             | Cotas superiores del tamaño de página de las listas y del rango de fechas.                            |

## Notificaciones

Notificaciones opcionales al cliente final para eventos Pix. Deja los bloques de proveedor sin definir para desactivar ese canal.

| Variable                 | Valor por defecto / Requerida | Descripción                                                   |
| ------------------------ | ----------------------------- | ------------------------------------------------------------- |
| `SENDGRID_API_KEY`       | 🔒 —                          | Clave de API de SendGrid para notificaciones por email.       |
| `SENDGRID_FROM_EMAIL`    | —                             | Dirección de remitente para notificaciones por email.         |
| `SENDGRID_FROM_TEMPLATE` | —                             | ID de plantilla de SendGrid usado para el cuerpo del mensaje. |
| `TWILIO_ACCOUNT_SID`     | 🔒 —                          | SID de cuenta de Twilio para notificaciones por SMS.          |
| `TWILIO_AUTH_TOKEN`      | 🔒 —                          | Token de autenticación de Twilio para notificaciones por SMS. |
| `TWILIO_PHONE_NUMBER`    | —                             | Número de teléfono de remitente para notificaciones por SMS.  |

## CRM

| Variable            | Valor por defecto / Requerida | Descripción                                         |
| ------------------- | ----------------------------- | --------------------------------------------------- |
| `CRM_URL`           | —                             | URL del servicio CRM para búsquedas de contraparte. |
| `CRM_CLIENT_ID`     | —                             | Client ID de OAuth para M2M de CRM.                 |
| `CRM_CLIENT_SECRET` | 🔒 —                          | Client secret de OAuth para M2M de CRM.             |

## Configuración en tiempo de ejecución (systemplane)

Este rail monta la API de administración de systemplane en su puerto principal, controlada por `SYSTEMPLANE_ENABLED`.

| Variable              | Valor por defecto / Requerida | Descripción                                                                               |
| --------------------- | ----------------------------- | ----------------------------------------------------------------------------------------- |
| `SYSTEMPLANE_ENABLED` | `false`                       | Habilita la API de administración de configuración en tiempo de ejecución de systemplane. |

Cuando está habilitada, el servicio expone un plano autenticado para leer y escribir la configuración en tiempo de ejecución. Consulta [Systemplane](/es/reference/systemplane/overview) para la API, los espacios de nombres y los permisos requeridos.

## Salud y readiness

El rail expone `GET /health` (liveness) y `GET /readyz` (readiness) en el puerto principal, además de `/metrics` y `/version`. Cuando la multi-tenancy está habilitada (`MULTI_TENANT_ENABLED=true`), añade una sonda por tenant protegida por autenticación en `GET /readyz/tenant/{id}`. Consulta [Salud y readiness](/es/reference/health-and-readiness) para la forma de la respuesta y el comportamiento de arranque/drenaje.