Variables de entorno

Variables de entorno para el rail Pix Directo vía JD: integración con JD, hosting de QR dinámico, 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. DevOps define su comportamiento mediante variables de entorno en el momento del despliegue. Para cambiar una variable, reinicia 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 que comparten todos los servicios Go de Lerian, consulta la referencia de configuración BYOC.

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.

​

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 para los ajustes de servidor compartidos y Puertos de red predeterminados.

​

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. El plugin sirve esos documentos bajo el host de QRCODE_PUBLIC_BASE_URL. Define un host simple (FQDN) sin esquema de URL, porque JDPI rechaza un esquema.

Variable	Valor por defecto / Requerida	Descripción
QRCODE_PUBLIC_BASE_URL	Requerida	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 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	1	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

El plugin mapea los flujos Pix de cash-in, cash-out, reversa e intra-PSP a rutas nombradas de transacción y operación de Midaz. 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).

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

​

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	*/10 * * * * *	Expresión cron para el trabajo 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.
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	100 · 3	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 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 habilitas la multi-tenancy (MULTI_TENANT_ENABLED=true), el rail añade una sonda por tenant protegida por autenticación en GET /readyz/tenant/{id}. Consulta Salud y readiness para la forma de la respuesta y el comportamiento de arranque/drenaje.