Variables de entorno

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.

​

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

​

Conexiones sin TLS

​

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.

​

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. 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. 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.

​

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. Para los perfiles, los nombres exactos de las claves y cómo escribirlas, consulta Configurar el riel.

​

Jobs

​

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: 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 las recurrencias de Pix Automático que el riel aceptó como la institución del pagador. Envía hasta 100 reclamaciones en cada pasada. 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. Un operador resuelve cada una.

​

Participantes indirectos

Solo es relevante si este despliegue liquida Pix por cuenta de otras instituciones.

​

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: Configurar el riel muestra cada una de estas claves, el cuerpo exacto de cada escritura y cómo confirmarla.

​

Llamadas de JD sin JD Courier

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.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.1. El riel ya no lee MULTI_TENANT_ALLOW_INSECURE_HTTP. En modo multi-tenant con un Tenant Manager en http://, define ALLOW_INSECURE_TLS=true en la API y en el worker antes de la actualización. De lo contrario, el servicio no inicia. Si tu despliegue ya define ALLOW_INSECURE_TLS=true, Pix JD 1.2.1 y posteriores también aceptan direcciones http:// para las conexiones de Conexiones sin TLS, en todo entorno. 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

El riel expone GET /health (liveness) y GET /readyz (readiness) en el puerto principal, además de /metrics y /version. Consulta Salud y readiness para la forma de la respuesta.