Saltar al contenido principal
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, streaming, telemetría y autenticación que comparte cada servicio Go de Lerian, consulta Fundamentos de configuración BYOC.
Estas variables describen un despliegue BYOC. En Lerian Cloud, no las defines.
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). Este puerto sirve la API, GET /health y GET /version. Consulta Servidor para los controles compartidos del servidor y Puertos de red predeterminados. Apunta la sonda de readiness y la recolección de métricas a HEALTH_PORT. El puerto de SERVER_ADDRESS no sirve /readyz ni /metrics. Apunta los health checks del balanceador de carga a /health en el puerto principal. El worker no tiene puerto de API: responde a las sondas del kubelet solo en HEALTH_PORT. Mantén privado el puerto de health. En la API, /readyz responde 503 hasta que Postgres y Valkey hayan respondido una vez cada uno. En el worker, responde 503 hasta que Postgres haya respondido una vez, y solo entonces el worker inicia sus jobs. Después, /readyz se mantiene en 200, y una dependencia que deja de responder aparece como degraded en el cuerpo. Toda otra dependencia se reporta en el cuerpo y nunca hace que el servicio deje de estar listo. Consulta Salud y readiness para la forma de la respuesta. Un error sin código propio, que viene de una conexión rechazada, de un límite de tiempo vencido o de un Postgres que se reinicia, responde 503 PIX-0051, y puedes reintentar. Una lectura que JD no responde a tiempo sigue respondiendo 504 PIX-1051. La API y el worker leen SHUTDOWN_DRAIN_DELAY y SHUTDOWN_TIMEOUT, que describen los Fundamentos de configuración BYOC.

​
Licencia

La clave es global para el despliegue, y el riel no lee ninguna otra variable de licencia. Usa una clave de producción. Cuando la licencia se rechaza al iniciar, o en una verificación posterior, el servicio se detiene. Para saber cómo corre la verificación, consulta el License Manager.

​
Conexiones sin TLS

Con true, Pix JD acepta direcciones http:// para estas conexiones en todo entorno, incluida producción. El tráfico en una conexión http:// no está cifrado, y lleva credenciales o datos Pix. Pix JD registra una advertencia de arranque cuando el valor es true. Mantén el valor false cuando cada conexión usa https.

​
Integración con JD

Credenciales, endpoints, reintentos y límites de tiempo de la API de JD protegida con OAuth y de su superficie Pix (JDPI). Los dos timeouts aplican en los dos modos de despliegue. Un valor de 0 o menor da el predeterminado. Mantén JDPI_TOTAL_TIMEOUT_MS por debajo del timeout de tu ingress. Así, en una solicitud de cliente, un JD que no responde recibe 504 PIX-1051 del riel, no un timeout del proxy.
Tu propio ISPB no es una variable de entorno. Viene de la clave de systemplane tenancy/jd_integration_binding, campo ispb. No hay fallback de entorno.Mientras esa clave esté vacía, el riel arranca y responde a su sonda de salud. Rechaza todos los pagos en todas las rutas de dinero con 409 PIX-0092. Escribe la clave y la solicitud siguiente pasa, sin reinicio. Para los pasos, consulta Configurar el riel.

​
Firma de la orden de pago

La clave que firma cada orden de pago de salida. Son opcionales: las necesitas solo cuando tu entorno de JD exige órdenes firmadas. La API lee estas variables. El worker no. Deja las tres vacías y el riel envía órdenes sin firma. Define solo algunas, o un valor que no sirve, y el riel rechaza cada pago a otra institución con 409 PIX-0136 antes de llamar a JD. Para la clave, el certificado y JDPI Cabine, consulta Firma de la orden de pago.

​
Alojamiento de QR codes dinámicos

El riel aloja los payloads de QR dinámico firmados (JWS) y el conjunto de JWK que los verifica. La sección de referencia de QR codes da las formas de las rutas públicas, el formato de host sin esquema y el límite de 77 caracteres de URL de payload de BACEN. Las variables siguientes definen las partes que este despliegue controla.
No cambies QRCODE_PAYLOAD_PATH después del go-live. Un QR code impreso o mostrado lleva la URL vieja, y nada la redirige.
Un participante directo puede publicar sus QR codes dinámicos en un host propio. El riel toma el host de los QR codes dinámicos de un participante directo de la primera de estas fuentes que tiene un valor:
  1. El campo qrPublicBaseUrl de la entrada del participante en el catálogo de organizaciones. Una entrada con el ISPB de tenancy/jd_integration_binding define el host de ese participante.
  2. Para el participante que nombra tenancy/jd_integration_binding, la clave del systemplane tenant_policy/qrcodes.public_base_url. Su valor predeterminado es vacío.
  3. QRCODE_PUBLIC_BASE_URL.
El campo y la clave reciben un host, con una ruta opcional, y sin esquema. Una escritura rechaza un esquema, un puerto, una query, un fragmento, información de usuario, un host que no es público y un valor de más de 37 caracteres. Cuando un valor guardado infringe estas reglas, el riel rechaza crear o actualizar los QR codes dinámicos de ese participante con 500 PIX-0053. Cuando el riel no puede leer la clave, los rechaza con 503 PIX-0122. Antes de definir o cambiar el host de un participante:
  1. Enruta la ruta de payload y la ruta de JWK del nuevo host (por defecto /qr/* y /v1/qrcodes/jwks/*) a este servicio, sin ningún autorizador delante. El PSP del pagador llama a estas rutas sin credencial.
  2. Mantén el host anterior en servicio hasta que venzan los QR codes emitidos en él. Un QR code mantiene el host en el que se emitió.
Una actualización de un QR code dinámico lo publica en el host actual de su participante.

​
Conexión con el ledger de Midaz

Los endpoints del servicio de ledger y las credenciales machine-to-machine.
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.
La identidad del ledger no es una variable de entorno. Cuatro valores le dicen al riel dónde registra asientos. Los cuatro vienen del systemplane, en los dos modos de despliegue: Las dos claves tenant_policy empiezan vacías. Hasta que escribas las dos, el riel rechaza todos los asientos, reembolsos y créditos entrantes con 409 PIX-0106. Para los pasos, consulta Configurar el riel.
El riel ya no lee MIDAZ_ORGANIZATION_ID, MIDAZ_LEDGER_ID, MIDAZ_ASSET_ID ni MIDAZ_EXTERNAL_ID. Un valor que quede en una de ellas da una advertencia de arranque y no tiene efecto.

​
Rutas contables

El riel registra cada flujo Pix en un par de rutas de operación de Midaz, una pata de crédito y una pata de débito. Los identificadores de ruta no son variables de entorno. Viven en las claves de systemplane tenant_policy/routing.<profile>.operation_credit_route y tenant_policy/routing.<profile>.operation_debit_route. No hay fallback de entorno. Cada perfil también tiene una clave opcional de ruta de transacción, tenant_policy/routing.<profile>.transaction_route. El riel envía su valor como la ruta de cada asiento de ese perfil. Un ledger de Midaz que valida rutas rechaza un asiento sin ella. El riel responde entonces PIX-4011. Cuando la clave está vacía, el asiento no lleva ruta de transacción.
Las variables TRANSACTION_ROUTE_* y OPERATION_ROUTE_* ya no existen. Un valor remanente da una advertencia de arranque y no tiene efecto. Una pata ausente de uno de los seis perfiles de pago rechaza todos los flujos de pago con 409 PIX-0105. Una pata ausente de MED o de Pix Automático rechaza solo ese flujo. Cuando falla un flujo y los demás funcionan, mira aquí primero.
Para los perfiles, los nombres exactos de las claves y cómo escribirlas, consulta Configurar el riel.

​
Jobs

La ventana diaria de 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. Cada clave toma una hora de reloj de 0 a 23. El riel ignora las variables antiguas TRANSACTION_LIMIT_DAILY_PERIOD_INIT y TRANSACTION_LIMIT_DAILY_PERIOD_END.

​
Pix Automático

El Pix Automático de JD tiene dos pasos opcionales que permanecen apagados hasta que tu institución los activa. El débito en sí siempre se ejecuta. Activa cada uno solo después de que tu institución acuerde con JD usar ese paso. El riel lee ambos al arrancar, así que un cambio requiere un reinicio.

​
Filtrado de créditos entrantes

Tu Tracer puede juzgar los créditos Pix entrantes en la validación de cuenta, síncrona y asíncrona, antes de que el riel los acepte. La clave del systemplane tenant_policy/tracer.inbound_credit_enabled activa el filtrado para un tenant. Su valor predeterminado es false. Cuando es true:
  • Tracer juzga los créditos que pasaron las verificaciones propias del riel, solo con sus reglas. No verifica ni cuenta límites.
  • Tracer no ve estos créditos, y cada uno mantiene el veredicto propio del riel:
    • un crédito cuyo pagador es Bacen
    • un crédito en el que atiendes solo el lado del pagador
    • un crédito cuyos datos de cuenta no coinciden con ninguna cuenta del CRM, o coinciden con más de una
    • un crédito sin monto
    • un crédito para un cliente de un participante indirecto
  • DENY y REVIEW rechazan el crédito con el motivo DS04.
  • Cuando Tracer no puede responder, el riel acepta el crédito sin filtrarlo. Esto incluye una MIDAZ_URL_TRACER vacía, un Tracer de una release de Midaz anterior a 4.3.0 y ninguna respuesta en 1 segundo.
  • Tracer recibe el CPF o el CNPJ y el ISPB del pagador, el monto, la cuenta del ledger acreditada y el endToEndId. No recibe nombres.
La credencial de Midaz del riel también necesita el permiso de Tracer validations (acción post). Este filtrado no es la verificación de Tracer en el ledger. Cuando esa verificación rechaza el crédito de un Pix recibido, el Pix espera a un operador. Consulta Pix recibido que espera a un operador.

​
Notificaciones

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

​
CRM

​
Mapa de propiedad de Courier

Algunas instituciones comparten un ISPB entre dos sistemas core. JD Courier mantiene un mapa de propiedad que indica qué core tiene cada cuenta. El riel consulta ese mapa en un solo caso. El receptor de un Pix saliente nombra el ISPB propio del participante que paga, y tú declaras ese ISPB como compartido. Pix JD intercambia COURIER_CLIENT_ID y COURIER_CLIENT_SECRET con Access Manager por un token, y envía ese token en cada llamada a JD Courier. Declaras un ISPB compartido en el systemplane. La clave tenant_policy/onus.shared_ispb_gate_enabled cubre tu organización predeterminada, y su valor predeterminado es false. Una organización del catálogo de organizaciones usa su campo sharedIspbGate. Mientras la declaración es false, el riel no consulta el mapa. Cuando la declaración es true, estos rechazos aplican a un Pix saliente hacia una cuenta en tu propio ISPB: El riel rechaza antes de reservar un saldo, así que un rechazo no mueve dinero. Tres claves de systemplane definen los límites de tiempo de la consulta. Aplican en los dos modos de despliegue:

​
Pix entre cores

Cuando el mapa asigna la cuenta al otro core, el riel no envía el Pix al SPI. Retiene el monto en la cuenta del pagador contra la cuenta @intercore. Después, envía el Pix al otro core por el relay de JD Courier: La clave de systemplane tenant_policy/crosscore.relay.timeout_ms limita una llamada de relay, en milisegundos. El valor predeterminado es 8000 y el rango va de 1000 a 15000. Una llamada que agota el límite tiene un resultado desconocido: el riel mantiene la retención y envía el mismo Pix de nuevo. Por el relay, el riel también recibe los Pix que envía el otro core y las devoluciones de los Pix que el riel envió. Acredita al receptor contra @intercore. Una devolución de un Pix que el riel recibió del otro core vuelve por el relay. Antes del primer Pix entre cores, crea la cuenta @intercore en el ledger. Un Pix o una devolución del otro core la debita, así que permite el sobregiro en su saldo. Define también las rutas de los perfiles cross_core_out, cross_core_in, cross_core_return_out y cross_core_return_in. Sin las rutas de un perfil, el riel rechaza su flujo con 409 PIX-0105.

​
Reclamaciones en el Courier

Consulta Conectar un motor. Cuando el Courier está configurado, el worker reclama en el Courier cada lado de las recurrencias de Pix Automático que el riel mantiene. Como institución del pagador, reclama la recurrencia. Como institución del cobrador, reclama la recurrencia y el CNPJ del cobrador. En cada pasada, reclama hasta 100 recurrencias de cada lado. Cuando una reclamación falla, el worker la envía de nuevo en una pasada posterior. El worker no envía de nuevo una reclamación que el Courier rechaza con un conflicto. El worker lee la configuración del Courier del mismo lugar que la API. El worker y la ruta de abajo reclaman cada participante en su propio Courier, y omiten un participante que no tiene Courier. Antes de que el Courier empiece a recibir tu Pix, llama a la ruta de propiedad del Courier (POST /v1/pix-automatico/courier-ownership). Reclama las recurrencias que ya existen y declara los bloqueos del débito y los agendamientos de los pagos en curso. Llámala de nuevo después de que el Courier empiece a recibir tu Pix, para declarar las etapas abiertas entre las dos llamadas. La ruta también reclama de nuevo las recurrencias que el Courier rechazó antes. heldElsewhere en la respuesta lista las claves que el Courier rechazó con un conflicto. Puede listar el CNPJ de un cobrador como DOCUMENT:<cnpj>. Un operador resuelve cada una.

​
Participantes indirectos

Solo es relevante si este despliegue liquida Pix por cuenta de otras instituciones.
Sin esta clave, todos los registros de participante indirecto se rechazan con 409 PIX-0107. El rechazo llega 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 para el onboarding que requiere esta clave.

​
Configuración de runtime (systemplane)

Este riel monta la API de administración de systemplane en su puerto principal. SYSTEMPLANE_ENABLED la activa. Cuando la habilitas, el servicio expone un plano autenticado para leer y escribir la configuración de runtime. Consulta Systemplane para la API, los namespaces y los permisos necesarios. El riel lee varios valores solo desde ese plano, en los dos modos de despliegue. Un despliegue que los deja sin definir arranca sano y rechaza dinero: La clave de systemplane tenant_policy/med.detection_enabled es true por defecto. Con false, el worker detiene la detección de MED del tenant: no lee nuevos reportes de infracción ni solicitudes de devolución. Sigue confirmando o cancelando las reservas ya retenidas para las liquidaciones de MED. Déjala en true salvo que detengas MED a propósito.
Con SYSTEMPLANE_ENABLED=false, el servicio no monta el grupo de rutas /system. Todas las escrituras de configuración responden entonces 404. Una ruta de dinero que no puede leer su configuración responde el 503 PIX-0051 reintentable, no un rechazo por aprovisionamiento. El permiso de escritura es systemplane:write. Sin él, las escrituras responden 403.
Configurar el riel muestra cada una de estas claves, el cuerpo exacto de cada escritura y cómo confirmarla.

​
Autorización máquina a máquina

Estas dos variables deciden cómo el plugin autoriza un token de aplicación. JD Courier necesita las dos en true, y también una aplicación que listas para JD en tenant_policy/jd.direct_client_ids. Con las dos en false, el plugin autoriza cada token de aplicación con el rol de editor del propio plugin y no lee el sujeto del token. JD Courier recibe entonces 403 en las rutas que llama.
AUTH_M2M_INVERSION_ENABLED=true vale para toda aplicación que llama al plugin, no solo para JD Courier. Cada aplicación pasa a autorizarse con sus propios permisos, y no con el rol de editor del plugin. Un token cuyo tipo no es normal-user ni application recibe 401. Antes de definir la variable, comprueba que cada aplicación que llama al plugin tiene los permisos que necesita.
En Lerian Cloud, Lerian define las dos variables. En tu propia instalación, defínelas como describe el README del chart de Pix JD. Para los pasos, mira Dale a JD su credencial.

​
Declaración de permisos

Al iniciar, el servicio puede publicar su declaración de permisos en el Access Manager. En el modo multi-tenant, el Tenant Manager la publica. Con IDP_DECLARATION_ENABLED=true, el servicio no inicia cuando una de las otras tres variables está vacía, cuando IDP_HOST no es válida, o cuando PLUGIN_AUTH_ENABLED no es true. Cuando el Access Manager rechaza la publicación o no responde, el servicio inicia de todos modos.

​
Actualizar desde una versión anterior

Sigue los pasos de cada versión por la que pasas camino a la versión que instalas. A 1.6.0.
  1. Cambia la sonda de readiness y la recolección de métricas a HEALTH_PORT. Consulta Servidor y puerto. El puerto de la API ya no sirve /readyz ni /metrics, y un pod cuya sonda de readiness sigue en ese puerto nunca queda listo. La imagen del worker ahora también responde a las sondas en HEALTH_PORT.
  2. Pon una clave global de producción en LICENSE_KEY. Una clave emitida para IDs de organización falla, y la API y el worker no inician. Quita ORGANIZATION_IDS y IS_DEVELOPMENT del entorno: el riel no los lee. Una licencia rechazada ahora detiene el servicio. Consulta el License Manager.
  3. La API y el worker ahora siguen la secuencia de apagado compartida, con SHUTDOWN_DRAIN_DELAY y SHUTDOWN_TIMEOUT. Consulta los Fundamentos de configuración BYOC para los valores predeterminados, y defínelos si tu rollout necesita otros valores.
A 1.4.0.
  1. En un despliegue self-hosted donde la declaración de permisos de Pix JD no está publicada, dale a los roles de Pix el permiso parked-credits (acción post). Sin él, las dos rutas de créditos en espera responden 403.
  2. Actualiza fuera del intervalo 00:00–08:00, hora de Brasilia. Los bloqueos y los débitos de Pix Automático corren en ese intervalo.
  3. Una aplicación existente de JD con el origen jd-consultores sigue funcionando, y una instalación detrás de JD Courier no necesita ningún paso. Para una nueva integración directa con JD, mira Dale a JD su credencial.
A 1.3.0.
  1. Si la aplicación de JD no tiene el origen jd-consultores, lista su client ID como describe Dale a JD su credencial, en cuanto el riel corra la 1.4.0. Hasta que lo listes, el riel rechaza cada llamada que hace JD, Pix entrantes incluidos, con 403 PIX-0005. Con JD Courier, la credencial del Courier debe tener el origen jd-courier.
  2. En modo single-tenant con ENV_NAME=production, confirma que JD_BASE_URL es una dirección https. De lo contrario, el servicio no inicia.
  3. Confirma que tus clientes envían el header X-Idempotency cuando registran una clave aleatoria (keyType 4). Sin él, el riel responde 400 PIX-0061.
  4. Confirma que tus clientes usan solo los nombres de campo en inglés. Consulta Nombres de campo en inglés.
A 1.2.0. En un despliegue self-hosted, antes de la actualización, dale a la aplicación que COURIER_CLIENT_ID nombra el permiso ownership:write en JD Courier. Donde la declaración de permisos de Pix JD no está publicada, confirma también que los roles de Pix en el Access Manager tienen el permiso courier-ownership (acción post). La ruta de propiedad del Courier de esta versión necesita courier-ownership, y responde 403 sin él. En un despliegue single-tenant, define también las variables CRM_*, y con JD Courier las variables COURIER_*, en el worker. Consulta Reclamaciones en el Courier. A 1.1.1. No se requiere ningún paso. Las tres variables de firma de la orden de pago son nuevas y opcionales. Defínelas solo si JD exige órdenes de pago firmadas para tu institución. Consulta Firma de la orden de pago. A 1.1.0. En un despliegue self-hosted donde la declaración de permisos de Pix JD no está publicada, antes de la actualización, confirma que los roles de Pix en el Access Manager tienen el permiso entries-lookup (acción get). La ruta de consulta de claves de esta versión lo necesita, y responde 403 sin él. A 1.0.0, desde el plugin Pix anterior.
  1. Antes de la actualización, escribe tenant_policy/midaz.asset_id y tenant_policy/midaz.external_id. Usa los valores de MIDAZ_ASSET_ID y MIDAZ_EXTERNAL_ID. Sin ellos, el riel actualizado rechaza todos los asientos con 409 PIX-0106.
  2. Vuelve a leer tenancy/jd_integration_binding. Confirma que organizationId y ledgerId nombran la organización y el ledger en los que este despliegue registra asientos. El riel los lee en cada llamada.
  3. Antes de actualizar, configura MIDAZ_FEE_MODE=legacy en la API y en el worker. El valor predeterminado es auto. Cambia el valor a auto solo después de que se cumplan estas dos condiciones:
    • Ningún pod de la versión anterior atiende a ningún tenant.
    • Revisaste tus paquetes de tarifas. Un paquete de tarifas sin ruta de transacción puede cobrar una tarifa en cada flujo Pix.
    Agrega una entrada refundSent al catálogo de organizaciones solo después de que ningún pod de la versión anterior atienda al tenant.
  4. Con el streaming de eventos activo, el servicio no arranca mientras su outbox tenga eventos sin entregar en un formato de evento anterior. Entrega esos eventos con el build que los escribió antes de actualizar.
  5. Después de la actualización, elimina de tu entorno las cuatro variables de identidad MIDAZ_*.

​
Salud y readiness

GET /health y GET /version responden en el puerto principal. GET /health, GET /readyz, GET /metrics y GET /version responden en HEALTH_PORT. Consulta Servidor y puerto y Salud y readiness para la forma de la respuesta.