El recorrido
- Revisa los requisitos previos, y otorga acceso a quien hace la configuración.
- Configura la firma de órdenes de pago, solo si JD la exige para tu institución.
- Aprovisiona el ledger y los registros de titulares en Midaz y en el CRM.
- Crea las rutas contables en Midaz.
- Configura el riel: los ajustes del plugin.
- Envía el pago que crea las filas de límite.
- Comprueba que la configuración está completa, hasta una clave Pix registrada.
- Agrega las capacidades opcionales que tu institución necesita.
Paso 1: Revisa los requisitos previos
Usas tres direcciones. No las confundas.-
El plugin Pix en funcionamiento. La API de ajustes del plugin debe estar habilitada (
SYSTEMPLANE_ENABLED=true). Sin ella, cada llamada de configuración del paso 5 responde404. En SaaS, Lerian la habilita. -
En un despliegue self-hosted donde la declaración de permisos de Pix JD no está publicada, estos permisos en los roles de Pix en el Access Manager:
entries-lookup(acciónget), para la ruta de consulta de claves.parked-credits(acciónpost), para las rutas de créditos en espera.- Con JD Courier,
courier-ownership(acciónpost), para la ruta de propiedad del Courier.
403. Una vez publicada la declaración, los roles que declara tienen estos permisos. - Un Bearer token para Midaz y uno para el plugin, emitidos por el Access Manager. Pueden venir de audiencias distintas.
- La credencial de JD, cuando JD llama al plugin sin JD Courier. Mira Dale a JD su credencial.
-
El acceso correcto para quien hace la configuración. El paso de acceso de abajo lista los grupos. Sin él, las llamadas responden
403. - El ISPB de tu institución: el identificador de tu acreditación en BACEN, 8 letras mayúsculas o dígitos.
Otorga acceso a quien hace la configuración
Por qué existe este paso. Configurar Pix toca dos productos: Midaz, con sus registros de titulares de cuenta (CRM), y el propio plugin Pix JD. Cada uno revisa su propio permiso. Sin él, la llamada responde403 y no se graba nada.
Si eres administrador, ya tienes todo. El grupo Administrator (admin-group) tiene acceso completo a los dos productos. Sigue al paso siguiente.
Para que otra persona haga la configuración sin ser administradora, agrégala a los grupos de abajo en el Access Manager, desde la consola o con Update a User. Es el acceso mínimo que cubre todos los pasos de esta página:
plugin-br-pix-jd-contributor-group) alcanza. No puede cambiar la configuración de Pix, así que un error de operación no cambia el enrutamiento de tu dinero. Para quien solo consulta, usa Plugin PIX JD Viewer (plugin-br-pix-jd-viewer-group).
Prueba que el acceso es correcto antes de seguir. Con el token de esa persona:
GET /system/-/catalogtiene que responder200.- La primera escritura en
/system, la del vínculo de integración del paso 5, tiene que responder204 No Content. Un403ahí significa que la persona no está en el grupo Plugin PIX JD Editor.
Dale a JD su credencial
Por qué existe este paso. JD llama al plugin para el Pix recibido y para los flujos de Pix Automático. Esas rutas aceptan cuatro credenciales: la credencial de JD Courier, la aplicación existente de JD con el origenjd-consultores, una aplicación que listas para JD, y un socio que tiene los permisos de canal de JD. Cualquier otro llamador recibe 403 PIX-0005.
Detrás de JD Courier, JD no necesita una credencial tuya. El Courier llama al plugin con su propia credencial. En el modo multi-tenant, el Tenant Manager la emite. En el modo single-tenant, un administrador la emite con Emitir una credencial de servicio, con el origen jd-courier y el destino plugin-br-pix-jd. Esa llamada responde 422 mientras la declaración de permisos de Pix JD no está publicada.
Una aplicación existente con el origen jd-consultores sigue funcionando. No necesitas nada más para ella.
JD también puede llamar como socio de tu tenant. Consulta JD como socio.
Para listar una aplicación para JD, sin JD Courier:
- Define
AUTH_M2M_INVERSION_ENABLED=trueyAUTH_M2M_PRODUCT_FORWARD_ENABLED=trueen el plugin. Define las dos juntas. Solo con la primera, el plugin rechaza JD Courier con403. En Lerian Cloud, Lerian las define. - En el Access Manager, crea una aplicación con el destino
plugin-br-pix-jdy sin origen. - Escribe su client ID en la clave del plugin
tenant_policy/jd.direct_client_ids. Una persona de Plugin PIX JD Editor, o un administrador, debe hacer la escritura. Un token de aplicación recibe403. UnPUTreemplaza la lista entera, así que lee la clave primero y envía cada client ID que debe quedar, separados por comas. - Entrega a JD el client ID y el secret.
403 PIX-0005 en cada ruta que JD no llama.
Paso 2: Configura la firma de órdenes de pago, si JD la exige
JD puede exigir una firma en cada orden de pago de tu institución. Confírmalo con JD. Si JD la exige, sigue Firma de la orden de pago ahora, antes de cualquier pago. Si JD no la exige, omite este paso.Paso 3: Aprovisiona el ledger y los registros de titulares
Estos pasos se ejecutan contra Midaz y su CRM. Crean las cuentas en las que el riel registra los asientos, y los registros de titulares desde los que lee las contrapartes. Acceso: Midaz Editor.Crear la organización y el ledger
201 sin id en el cuerpo no es un éxito. Nada puede referenciar el objeto nuevo, ni tú ni una limpieza posterior. Detente ahí. No lleves un id vacío al paso siguiente.Crear el activo BRL y esperar a que aparezca
BRL.201 como 409 son buenas respuestas. Un ledger identifica un activo por su código, así que “ya existe” significa lo mismo que éxito.Aquí pasan dos cosas:- El ledger empieza a aceptar cuentas en ese activo. Antes de esto, rechaza todas las cuentas con
0034 Asset Code Not Found. - Midaz crea la cuenta
@external/BRLjunto con el activo. Es la única cuenta de un libro que puedes debitar antes de cualquier crédito. El saldo de apertura sale de ella. También es la contraparte de cada liquidación con el mundo exterior.
Crear una cuenta por rol
accountId de las llamadas de negocio que haces al plugin. El alias (@payer) es el nombre corto con el que el libro lee y registra. Vuelve a aparecer en el paso siguiente.Crear el titular en el CRM
documentdebe ser un CPF o CNPJ válido, con dígitos verificadores correctos.typesigue la longitud del documento. UsaNATURAL_PERSONpara un CPF (11 dígitos) yLEGAL_PERSONpara un CNPJ (14). El plugin convierte este tipo en el número que va a JD. Un tipo equivocado registra a la parte como el tipo de persona equivocado.externalIdguarda el alias de la cuenta en el ledger (@payer). El CRM lo llama un identificador externo de correlación, así que parece opcional. Para este riel no lo es. Un registro de clave Pix para un titular sinexternalIdresponde422 PIX-0108.addresses.primary.cityes obligatorio para los QR codes y Pix Automático. Es la ciudad del receptor en el código. Sin ella, el plugin se niega a generar un QR y responde422 PIX-0033parapayee.city. Ninguna ruta de pago lee el campo, así que su ausencia solo se nota cuando alguien genera un QR.
Vincular el titular a la cuenta
Fondear las cuentas
@external/BRL, que Midaz creó junto con el activo, dos pasos más arriba.@external/BRL tiene dos usos. Uno es la posición de liquidación @pi de un participante indirecto hospedado. El otro es un entorno de prueba u homologación, donde no llega ningún Pix real. Consulta El modelo directo e indirecto para saber qué es cada posición.@external/BRL en un cuerpo, pero no en una ruta. El alias contiene una barra, y la ruta del ledger no la decodifica. Una lectura de saldo por ruta responde 404 o un 200 vacío. Registrar asientos desde ella es normal. Leerla de esa forma no lo es.Paso 4: Crea las rutas contables
Cada ruta de dinero de este riel tiene su propio par de rutas de operación de Midaz: una pata de crédito y una pata de débito. El paso 5 guarda los UUID de las rutas en el plugin. Acceso: Midaz Editor. Qué pares necesitas. No creas un par para cada perfil. Crea un par para cada uno de los seis perfiles de pago. Los demás perfiles reutilizan un par, o quedan vacíos:in. Un débito MED y un débito de Pix Automático sacan dinero, como out.
Crea cada pata con una llamada:
{"id": "..."}. Guarda cada id con su perfil y su pata. El paso 5 los escribe.
Busca una ruta por título antes de crearla. Con dos rutas del mismo título, la búsqueda siguiente puede tomar cualquiera de las dos. Si aprovisionas el mismo libro más de una vez, lista primero.
Si tu ledger valida rutas, crea también una ruta de transacción de Midaz por cada perfil que uses. Un ledger que valida rutas rechaza un asiento que no nombra ninguna ruta de transacción. Consulta Entidades de enrutamiento de transacciones para saber cómo crear una.
Paso 5: Configura el riel
El plugin guarda su configuración viva en su systemplane. Escribes estos valores por la API de administración, y toman efecto sin un redespliegue ni un reinicio. Cada escritura es unPUT a /system/<namespace>/<key> con un cuerpo {"value": ...}. Un éxito responde 204 No Content, sin cuerpo.
El tenant viene del bearer validado, nunca de la URL ni del cuerpo.
Acceso: cada escritura de abajo exige Plugin PIX JD Editor. Estos valores deciden con qué institución se presenta el plugin ante JD y en qué cuentas registra los asientos, así que solo ese grupo y los administradores pueden cambiarlos. Cualquier grupo de Pix JD puede leerlos.
GET /system/-/catalog lista todas las claves con su tipo y descripción, y GET /system/-/catalog/<namespace>/<key> describe una clave. El catálogo es la fuente de verdad. Esta página es una copia de él, y las copias envejecen.Escribir el vínculo de integración con JD
tenancy/jd_integration_binding, sin fallback de entorno. Mientras la clave esté vacía, el plugin arranca y responde a su sonda de salud. Rechaza todos los pagos en todas las rutas de dinero.Qué se rompe sin él. 409 PIX-0092, “Tenant Pix integration not provisioned”. El texto de la respuesta te pide que contactes a soporte y no nombra la clave. Busca el código.El valor es un documento JSON dentro de una cadena. El cuerpo siempre es {"value": ...}. Aquí value no es un objeto. Es una cadena, y su contenido es un documento JSON. El plugin lo guarda con las comillas internas escapadas:jq haga el escapado:organizationId o ledgerId está ausente o no se puede usar, el plugin rechaza todos los asientos, devoluciones y créditos entrantes con 409 PIX-0106.value vuelve como un objeto y no como una cadena entre comillas, escribiste la forma equivocada. Si vuelve como "", la escritura no ocurrió. Revisa el código de estado del PUT. La prueba real es que las rutas de dinero dejan de responder 409 PIX-0092.No puedes guardar un ISPB malformado por esta ruta. El validador de escritura usa el mismo decodificador que la lectura. Rechaza en el acto un ISPB de 7 dígitos o un UUID roto, con 400 validation_error. No descubres el error en el primer pago.409 PIX-0121, “Tenant Pix integration ISPB invalid”, cuando sigues esta página. Ese código significa que el vínculo existe y su ispb no tiene 8 letras mayúsculas o dígitos, y esta ruta no puede crear ese estado. Aparece solo cuando un valor llegó a la clave por otra vía. Algunos ejemplos son una escritura directa a la base de datos del plugin, o una escritura de antes del validador. Su mensaje nombra tanto la clave como el campo a corregir.409 PIX-0092. No lo hagas en un entorno que paga.Prueba la conexión con JD
200 con la lista de participantes, como esta (resumida), prueba que el plugin llegó a JD y recibió el catálogo de participantes:Escribir las claves de enrutamiento
tenant_policy. Cada una guarda una cadena: el UUID de una ruta que existe en Midaz.409 PIX-0105: enviados, recibidos, por QR code y entre tus propias cuentas. Una pata ausente de MED o de Pix Automático rechaza solo ese flujo. refund_sent es la excepción. Mientras sus dos patas estén vacías, el riel registra una devolución que envías en las rutas de out.204. Si no usas MED ni Pix Automático, deja sus perfiles vacíos. Ese flujo entonces rechaza, lo que es mejor que un asiento en una ruta indefinida.La ruta de transacción de cada perfil. Cada perfil también tiene una clave opcional, tenant_policy/routing.<profile>.transaction_route. Complétala cuando tu ledger valide rutas. El plugin entonces nombra esa ruta de transacción en cada asiento del perfil. Sin ella, ese ledger rechaza el asiento, y el plugin responde PIX-4011. Cuando tu ledger no valida rutas, deja estas claves vacías.Definir el activo de registro y la cuenta de compensación
tenant_policy los guardan, en los dos modos de despliegue:409 PIX-0106, “Tenant ledger configuration missing”. La respuesta nombra los campos del vínculo y las dos claves. Este código no es PIX-0105. Un tenant puede tener todas las patas de ruta y aun así rechazar todos los asientos, porque el activo o la cuenta de compensación está vacío.Las variables de despliegue MIDAZ_ASSET_ID y MIDAZ_EXTERNAL_ID ya no existen. El plugin las ignora.Definir la ventana diaria
400. El plugin no lo recorta al límite.Declarar si este despliegue hospeda participantes indirectos
plugin-br-pix-jd.indirects/enabled declara lo que el tenant es. Un participante directo simple lo define en false.{"value":"true"} responde 400. Si este despliegue liquida Pix para otras instituciones, el paso 8 lo define en true.Paso 6: Crea las filas de límite de transacción con un pago pequeño
El producto no tiene ninguna ruta para crear lo que este paso necesita. Qué esperas. Aprovisionas una cuenta y lees su límite disponible. Qué pasa.GET /v1/limits/available responde 404 PIX-0063, “The specified transaction limit was not found in the system. Please verify the identifier and try again.” GET /v1/limits responde {"data":[]}. La cuenta parece rota, pero no lo está. Es el estado inicial normal de una cuenta que nunca envió un pago.
PIX-0063 nombra la cosa que buscó el plugin. La lista de errores muestra su forma genérica, “The specified entity was not found in the system”. Esta ruta pone transaction limit en ella. El código y el 404 no cambian.
Por qué no puedes crear las filas. No hay ruta de creación. PATCH /v1/limits actualiza filas que ya existen. Solo la verificación de límites de un pago saliente crea las filas. Cuando una cuenta envía su primer pago, el plugin no encuentra filas. Crea los valores predeterminados, los vuelve a leer y continúa.
Así que envía un pago saliente pequeño. Un centavo alcanza.
Acceso: el pago exige Plugin PIX JD Contributor o Plugin PIX JD Editor. Cambiar un límite después con PATCH /v1/limits exige lo mismo.
Cómo verificar. GET /v1/limits pasa de {"data":[]} a una lista. /v1/limits/available pasa de 404 a 200.
Haz este paso después de todos los pasos de arriba. El pago tiene que registrarse, así que necesita todos los valores de los pasos 3 a 5. Sin una ruta, por ejemplo, falla con PIX-0105.
Paso 7: Comprueba que la configuración está completa
Ejecuta estas comprobaciones en orden. Cada una falla por una razón distinta. Eso hace que la secuencia sea más útil que una sola prueba de humo.- El ledger acepta una cuenta. Crea una cuenta desechable y elimínala. Si el libro rechaza, el rechazo nombra el eslabón que falta. Sin esta comprobación, el mismo problema vuelve más tarde como “cuenta no encontrada” dentro de un flujo de pago, a tres capas de su causa. No fondees la cuenta de prueba: Midaz se niega a eliminar una cuenta con saldo. Eliminarla exige Midaz Editor.
- El vínculo vuelve como una cadena entre comillas con tu ISPB, tu organización y tu ledger, como se muestra en el paso 5.
GET /v1/banksresponde200con la lista de participantes de Pix, como en la verificación de conexión del paso 5.- Las dos claves
tenant_policy/midaz.*vuelven con el código del activo y el alias de la cuenta de compensación. - La consulta de instrumentos devuelve tu cuenta, filtrada por documento, sucursal y número de cuenta.
- Una ruta de dinero deja de responder
409 PIX-0092y409 PIX-0106. Usa la llamada que ya haces. No necesitas un arnés de pruebas. GET /v1/limitsdevuelve una lista para la cuenta que envió el pago del paso 6.- Una clave Pix se registra y aparece en la lista de la cuenta. Esta comprobación pasa por el CRM, el vínculo y el DICT en JD.
keyType 4 y ninguna key: el DICT crea el valor de la clave. Una clave aleatoria no necesita código de confirmación, así que va al DICT en la primera llamada. Necesita el header X-Idempotency, un texto de 255 bytes como máximo. Un reenvío con el mismo valor devuelve la clave que el DICT ya creó:
DELETE /v1/entries/{entryId}.
Paso 8: Agrega las capacidades opcionales
Tu configuración termina en el paso 7 si tu institución es un participante directo con un libro, y liquida solo el Pix de sus propios clientes. De lo contrario, continúa en la página que corresponda:- Varios libros, o varios participantes directos en un despliegue. Sigue Multiorganización y ledgers.
- Liquidar Pix para otras instituciones. Sigue Hospedar participantes indirectos. Agrega la clave de cifrado, la postura de hospedaje, el registro de cada participante indirecto, su propio certificado de QR si tiene uno, y el fondeo de su posición de liquidación.
Cómo se ve cada paso omitido
Cada rechazo de abajo es un409, salvo el de los límites. Ninguno desaparece si esperas. Cada uno desaparece cuando aprovisionas el valor que falta.
PIX-0092 deja de aparecer, los pagos no siempre pasan. Es solo la primera barrera. Con el vínculo en su lugar, una ruta contable vacía sigue respondiendo PIX-0105. Un activo o una cuenta de compensación ausente sigue respondiendo PIX-0106. Tres códigos tienen tres causas y tres correcciones distintas.No reintentes un 409. Sí reintenta su hermano 503
El estado te dice si el problema es tu configuración o una caída.
Un 409 de arriba es conocimiento positivo de ausencia. El riel leyó tu configuración y no encontró nada ahí. Solo un operador puede aportar el valor, así que repetir la solicitud obtiene la misma respuesta. Un cliente que reintenta con este código entra en un bucle infinito. Cada una de esas respuestas nombra qué definir.
La mayoría de esas condiciones tiene un hermano 503. Se aplica cuando el riel no pudo leer la configuración en absoluto. El riel no sabe nada de lo que aprovisionaste. La respuesta nombra la dependencia que falló, y reintentar es la acción correcta.
PIX-0121 es un caso especial. No puedes provocarlo por la API de administración, porque el validador de escritura rechaza un ispb malformado antes de guardarlo. Aparece solo cuando un valor llegó a la clave por otra vía. Mira el vínculo en el paso 5.detail exacto de cada uno.
A dónde ir después
Variables de entorno
Multiorganización y ledgers
Participantes indirectos
Pix Directo vía JD
Lista de errores de Pix JD
PIX-NNNN, su estado y el texto detail que lleva la respuesta.
