Saltar al contenido principal
Un despliegue nuevo de Pix Directo vía JD arranca, responde a su sonda de salud y rechaza todos los pagos. Nada está roto. El riel necesita una cadena de objetos antes de poder mover dinero. Hasta que existan, rechaza el pago y no adivina. Esta página da esa cadena como un solo recorrido, en el orden en que actúas, para un servicio que ya está instalado y en funcionamiento, con la falla que causa cada eslabón ausente. Lerian ejecuta esta configuración contigo durante el onboarding. Usa la página para saber qué tiene que existir, qué significa cada valor y cómo probar que quedó aplicado.
En Lerian Cloud, Lerian ejecuta el servicio. En Lerian Cloud multi-tenant, el onboarding de Lerian guarda tus credenciales de JD en la bóveda de credenciales de tu tenant: la URL base de JD, el client ID y el secret, los segmentos de servicio y, solo si JD lo exige, el material de firma de las órdenes de pago del paso 2. Las entregas por el canal de transferencia de credenciales que Lerian te indica en el onboarding. Nunca van a la configuración en ejecución, y ninguna llamada de esta página las escribe. Cada uno de los demás pasos de esta página te toca ejecutarlo a ti, porque crea tus propios libros y tus propios ajustes.
El orden es una cadena de dependencias. Midaz rechaza cada eslabón mientras el anterior no exista. El paso de los límites envía un pago, así que va después de los ajustes. Donde un paso puede ejecutarse en cualquier orden, la página lo dice.

El recorrido

  1. Revisa los requisitos previos, y otorga acceso a quien hace la configuración.
  2. Configura la firma de órdenes de pago, solo si JD la exige para tu institución.
  3. Aprovisiona el ledger y los registros de titulares en Midaz y en el CRM.
  4. Crea las rutas contables en Midaz.
  5. Configura el riel: los ajustes del plugin.
  6. Envía el pago que crea las filas de límite.
  7. Comprueba que la configuración está completa, hasta una clave Pix registrada.
  8. Agrega las capacidades opcionales que tu institución necesita.
  9. Recibe los callbacks de JD y, si tienes un workflow de Flowker propio, enrútalos por él.

Paso 1: Revisa los requisitos previos

Usas tres direcciones. No las confundas. También necesitas:
  • 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 responde 404. 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ón get), para la ruta de consulta de claves.
    • parked-credits (acción post), para las rutas de créditos en espera.
    • Con JD Courier, courier-ownership (acción post), para la ruta de propiedad del Courier.
    Sin su permiso, cada ruta responde 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.
Los ejemplos siguientes usan estas variables de shell. Donde el riel ya tiene un nombre para un valor, la variable lleva ese mismo nombre. Cada UUID, documento e ISPB es un marcador de posición. Usa los valores de tu propio entorno.
Midaz tiene una superficie de onboarding y una superficie de transacción. Cuando una sola dirección sirve a las dos, da el mismo valor a las dos variables. Las llamadas siguientes siguen el objeto que crea cada una.

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 responde 403 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: Después de la configuración, reduce el acceso. Para la operación del día a día (pagos, límites, participantes indirectos), Plugin PIX JD Contributor (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/-/catalog tiene que responder 200.
  • La primera escritura en /system, la del vínculo de integración del paso 5, tiene que responder 204 No Content. Un 403 ahí 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 origen jd-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.
AUTH_M2M_INVERSION_ENABLED=true vale para toda aplicación que llama al plugin, no solo para JD Courier. Lee Autorización máquina a máquina antes de definirla.
Detrás de JD Courier, el plugin necesita las dos variables máquina a máquina en true. Define AUTH_M2M_INVERSION_ENABLED=true y AUTH_M2M_PRODUCT_FORWARD_ENABLED=true en el plugin. Las dos tienen valor predeterminado false, y con false el plugin rechaza la credencial del Courier con 403. En Lerian Cloud, Lerian las define. En tu propia instalación, defínelas en el chart, como muestra Autorización máquina a máquina. 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:
  1. Define AUTH_M2M_INVERSION_ENABLED=true y AUTH_M2M_PRODUCT_FORWARD_ENABLED=true en el plugin. Define las dos juntas. Solo con la primera, el plugin rechaza JD Courier con 403. En Lerian Cloud, Lerian las define.
  2. En el Access Manager, crea una aplicación con el destino plugin-br-pix-jd y sin origen.
  3. 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 recibe 403. Un PUT reemplaza la lista entera, así que lee la clave primero y envía cada client ID que debe quedar, separados por comas.
  4. Entrega a JD el client ID y el secret.
Una aplicación listada recibe 403 PIX-0005 en cada ruta que JD no llama.
Para cortar a JD, elimina su aplicación en el Access Manager. Quitar el client ID de la lista no revoca la aplicación. Esta pasa a tener el acceso de tus propias aplicaciones, Pix enviado incluido.

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.
Haz este paso antes del paso 6. El paso 6 envía un pago. Si JD exige órdenes firmadas y la orden no está firmada, JD la rechaza. Después de rechazos repetidos, JD bloquea todos los débitos de tu institución.

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

Crear la organización y el ledger

La organización es tu institución en los libros. El ledger es el libro en el que registra. Una institución puede tener más de un ledger. Este riel registra en el predeterminado: el par que creas aquí y nombras en el vínculo del paso 5. Cada flujo usa ese par hasta que declares más libros en el catálogo de organizaciones. Para el catálogo, consulta Multiorganización y ledgers.
Un 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.
2

Crear el activo BRL y esperar a que aparezca

El activo es la moneda de los registros. Para Pix es BRL.
Tanto 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:
  1. El ledger empieza a aceptar cuentas en ese activo. Antes de esto, rechaza todas las cuentas con 0034 Asset Code Not Found.
  2. Midaz crea la cuenta @external/BRL junto 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.
El 201 llega antes de que el activo aparezca en el listado. Un script que crea el activo y luego crea una cuenta en la línea siguiente falla de vez en cuando. Sondea el listado hasta que aparezca el código, con un plazo límite:
3

Crear una cuenta por rol

Crea una cuenta para cada rol que usa tu entorno: pagador, receptor y los demás roles de tu producto.
Usas el id de la cuenta dos veces más adelante: en el vínculo del CRM de abajo y como el 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.
4

Crear el titular en el CRM

El titular es el dueño de la cuenta. El plugin lee quién es una contraparte desde el CRM, no desde el ledger.
Cuatro campos necesitan cuidado:
  • document debe ser un CPF o CNPJ válido, con dígitos verificadores correctos.
  • type sigue la longitud del documento. Usa NATURAL_PERSON para un CPF (11 dígitos) y LEGAL_PERSON para 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.
  • externalId guarda 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 sin externalId responde 422 PIX-0108.
  • addresses.primary.city es 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 responde 422 PIX-0033 para payee.city. Ninguna ruta de pago lee el campo, así que su ausencia solo se nota cuando alguien genera un QR.
5

Vincular el titular a la cuenta

El titular y la cuenta del ledger existen los dos, pero todavía nada los une. Este paso es la unión, que el CRM llama instrumento. El plugin la usa para encontrar dónde acreditar un Pix entrante y qué cuenta debita un pago.
Nunca envíes bankId como cadena vacía. Una cadena vacía es un valor. Registra “esta cuenta pertenece a la institución cuyo ISPB está vacío”, lo que es peor que ningún valor. Si todavía no tienes el ISPB, omite el campo.
Verifica qué registró el CRM, y filtra siempre. Una consulta sin filtro devuelve el primer vínculo de la organización. Así es como una verificación puede aprobar la cuenta de otra persona:
6

Fondear las cuentas

Una cuenta nueva tiene cero, y no puedes pagar desde una cuenta vacía. El crédito de apertura viene de @external/BRL, que Midaz creó junto con el activo, dos pasos más arriba.
En producción, no cargas así la cuenta de un cliente de un participante directo. El dinero entra como un Pix entrante real, o como un ingreso que hace el cliente. La carga desde @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.
Dos cuerpos idénticos enviados dentro de 300 segundos son un solo asiento. Midaz colapsa la repetición: el segundo POST responde 201 con el id del primer asiento, y nada se mueve. Usa esa propiedad cuando reintentes.El reintento de una recarga cuya respuesta perdiste tiene que enviar el cuerpo exactamente igual, description incluida, dentro de 300 segundos. Así la cuenta no puede recibir dos créditos. Después de esa ventana, lee el saldo de la cuenta antes de enviar la recarga de nuevo. Cambia la description solo para una recarga nueva. Una description nueva en un reintento real agrega un segundo crédito por error.
Puedes nombrar @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: Así que el mínimo es seis pares, doce rutas. Un perfil puede reutilizar el par de otro perfil solo cuando el dinero se mueve en la misma dirección. Una devolución MED y una reversión de Pix Automático traen dinero, como in. Un débito MED y un débito de Pix Automático sacan dinero, como out. Crea cada pata con una llamada:
Cada llamada devuelve {"id": "..."}. Guarda cada id con su perfil y su pata. El paso 5 los escribe.
Puedes invertir la dirección, y nada te avisa. Un débito sale del pagador, así que es la pata source. Un crédito llega, así que es la pata destination. Si las inviertes, cada asiento sigue respondiendo éxito, en la dirección equivocada. Ningún código de estado informa esto.
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.

Contabilidad en un ledger que valida rutas

Un ledger con accounting.validateRoutes en true (consulta Configuración del Ledger) comprueba cada asiento contra sus rutas. Dos cosas deben cumplirse en cada perfil: el asiento nombra la ruta de transacción del perfil, y cada operation route declara una entrada contable para la acción de Midaz que usa el asiento. Sin esa entrada, Midaz rechaza el asiento con 0157, que el plugin devuelve como PIX-4011. Los perfiles cross_core_* valen solo con JD Courier. Déjalos vacíos en los demás casos. Qué acciones declara cada operation route. Midaz elige una acción por asiento: direct para un asiento que se liquida al instante, y hold, commit y cancel para uno pendiente (la reserva, su confirmación y su liberación). Dos casos amplían la tabla:
  • intra_psp e intra_psp_reversal entre dos ledgers también se asientan como pendiente. El tramo de débito suma hold, commit y cancel, y el de crédito suma commit.
  • Un perfil que reutiliza el par de otro necesita todas las acciones de los perfiles que lo comparten. El débito de Pix Automático también se asienta directo, así que, si reutiliza el par de out, ese par declara también direct.
Declara las entradas al crear la ruta, o agrégalas después a la misma ruta con PATCH. El id no cambia, así que las claves routing.* del paso 5 siguen siendo válidas.
La ruta de transacción de un perfil lista exactamente sus dos operation routes, ni más ni menos. Midaz rechaza otra cantidad con 0116. Consulta Entradas contables para el modelo de acciones. Antes de activar accounting.validateRoutes. La configuración vale para el ledger entero, así que también gobierna a todo otro plugin que asienta en él. Acuérdalo antes. No repara reservas anteriores: el commit o el cancel de una reserva pendiente creada antes de activarla falla, así que vacía primero las reservas pendientes.

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 un PUT 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.
Pregúntale al plugin qué espera. No confíes en una copia. 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.
1

Escribir el vínculo de integración con JD

Qué es. El vínculo es un documento con tres campos. El ISPB es el código de 8 caracteres, letras mayúsculas o dígitos, que identifica a tu institución en el Banco Central. Va en cada mensaje Pix, y el plugin no puede firmar como tu institución sin él. Los otros dos campos nombran tu organización y tu ledger de Midaz predeterminados, del paso 3.Dónde vive. Ninguno de los tres es una variable de despliegue. Vienen de la clave de systemplane 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.
Reiniciar no ayuda. El plugin lee la clave en cada llamada, no en el arranque. Un despliegue sin ISPB sigue sin ISPB después de un reinicio. Escribe la clave con la aplicación en ejecución, y la solicitud siguiente pasa, sin redespliegue.
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:
Deja que jq haga el escapado:
El vínculo nombra tu organización y tu ledger predeterminados. Cada flujo registra en ese par a menos que resuelva otro a través del catálogo de organizaciones. Si 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.
El decodificador es estricto. Rechaza un campo desconocido, y ese rechazo detiene toda la escritura. Esto incluye el campo antiguo routeProfiles, porque las rutas contables se mudaron a las claves routing.* de abajo. Por eso un documento de una configuración vieja falla. El decodificador también rechaza todo lo que venga después del primer documento JSON.
Cómo verificarlo. Vuelve a leer la clave. No guarda ningún secreto, así que el valor vuelve en claro:
Si 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.
Por eso no ves 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.
Un 400 aquí no es un problema de permisos. Un permiso faltante responde 403. Este 400 significa que el valor está mal. La respuesta no dice qué campo, así que revisa primero el ISPB. Ese es el error más común.
El plugin acepta la cadena vacía, que significa “no aprovisionado”. Si la escribes, el despliegue vuelve a 409 PIX-0092. No lo hagas en un entorno que paga.
2

Prueba la conexión con JD

Por qué existe este paso. El vínculo es la última pieza que el plugin necesita para hablar con JD como tu institución. Antes de mover dinero, prueba que la conversación funciona: pide a JD la lista de participantes de Pix.Acceso: cualquier grupo de Pix JD, incluido Plugin PIX JD Viewer.
El plugin consulta a JD en cada llamada, sin caché, así que la respuesta es actual. List Pix participant bank IDs describe la respuesta.Una respuesta 200 con la lista de participantes, como esta (resumida), prueba que el plugin llegó a JD y recibió el catálogo de participantes:
Si la respuesta es diferente, rehaz los pasos anteriores, empezando por el acceso y el vínculo de integración. Si la respuesta sigue siendo diferente, contacta a nuestro equipo de soporte.
3

Escribir las claves de enrutamiento

Qué es. Para cada perfil, el par de UUID de las rutas de operación de Midaz del paso 4. Todas las claves viven en el namespace tenant_policy. Cada una guarda una cadena: el UUID de una ruta que existe en Midaz.
Qué se rompe sin esto. El riel lee juntos los seis perfiles de pago en cada pago. Una pata ausente de cualquiera de los seis rechaza todos los flujos de pago con 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.
Cómo verificar. Cada escritura responde 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.
La cadena vacía significa “todavía no aprovisionado”, y el plugin la acepta. El plugin rechaza el UUID de todos ceros. Ese UUID tiene un formato válido, pero nunca es un identificador real de Midaz. No llenes las rutas sin usar con ceros como un “vacío seguro”. Usa la cadena vacía.
4

Definir el activo de registro y la cuenta de compensación

Qué es. El activo de cada asiento, y la cuenta externa que representa al mundo fuera de tu institución. Dos claves de systemplane del namespace tenant_policy los guardan, en los dos modos de despliegue:Los dos valores son cadenas simples:
Escribe el código y el alias, no los UUID de Midaz del activo y de la cuenta. Los nombres de las claves terminan en _id, pero el plugin pone el valor en el asiento tal como está.
Qué se rompe sin esto. Las dos claves empiezan vacías. Hasta que escribas las dos, el plugin rechaza todos los asientos, devoluciones y créditos entrantes con 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.
5

Definir la ventana diaria

Son los dos extremos de la ventana de los límites de transacción. Ambos son enteros de 0 a 23. Son horas de reloj, no timestamps. Ambos son claves de systemplane en los dos modos de despliegue.
Por qué existe este paso. Cada institución elige la hora en que su ventana diaria de límites de transacción abre y cierra. El plugin no puede adivinarla.Los valores de arriba son un ejemplo. Usa los tuyos. El tipo JSON no cambia: un entero, sin comillas. Un valor fuera del rango responde 400. El plugin no lo recorta al límite.
6

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.
Es una escritura de configuración, así que exige Plugin PIX JD Editor. El valor es un booleano JSON, sin comillas. {"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.
Si JD exige órdenes de pago firmadas para tu institución, termina primero el paso 2. De lo contrario, JD rechaza este pago. Después de rechazos repetidos, JD bloquea todos los débitos de tu institución.
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.
Una cuenta sin filas de límite no es una cuenta sin límite. Si el plugin no puede crear los límites, rechaza el pago.No intentes forzar las filas con un monto por encima del techo. La verificación de saldo corre antes de la verificación de límites. Un monto grande falla por fondos insuficientes antes de la verificación de límites, y no aparece ninguna fila. Envía un pago común que quepa en el saldo.
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.
  1. 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.
  2. 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.
  3. GET /v1/banks responde 200 con la lista de participantes de Pix, como en la verificación de conexión del paso 5.
  4. Las dos claves tenant_policy/midaz.* vuelven con el código del activo y el alias de la cuenta de compensación.
  5. La consulta de instrumentos devuelve tu cuenta, filtrada por documento, sucursal y número de cuenta.
  6. Una ruta de dinero deja de responder 409 PIX-0092 y 409 PIX-0106. Usa la llamada que ya haces. No necesitas un arnés de pruebas.
  7. GET /v1/limits devuelve una lista para la cuenta que envió el pago del paso 6.
  8. 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.
Para la última comprobación, registra una clave aleatoria para la cuenta. Envía 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ó:
Luego lista las claves de la cuenta:
La clave está en la lista. Una clave CPF o CNPJ también va al DICT en la primera llamada. Una clave de email o de teléfono también necesita el código de 6 dígitos que el plugin envía por el proveedor de notificaciones de Variables de entorno. Register a Pix key entry describe cada respuesta. Cuando termines, elimina una clave de prueba con 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.

Paso 9: Recibe los callbacks de JD

Si un enrutador tuyo recibe primero las llamadas de JD, por ejemplo un workflow de Flowker que elige el core por ISPB y cuenta, las reenvía a tu despliegue. La tabla trae los cuatro callbacks del riel de pagos, y un enrutador Flowker lleva esos cuatro. Con Pix Automático, JD también llama a rutas bajo /v1/pix-automatico/. Las rutas que contienen /events/ exigen los headers de JD X-DataHoraEvento y X-NomeEvento aceptados y mapeados como Chave-Idempotencia. Sin ellos el plugin responde 400. Flowker normaliza la capitalización de los nombres de header, así que, en tu primera ejecución real, comprueba con qué grafía los guarda Flowker y mapéalos con esa grafía. El reenvío sigue cuatro reglas:
  1. Envía el cuerpo tal como lo envió JD, y reenvía Chave-Idempotencia sin cambios. Una reentrega con la misma clave y el mismo cuerpo recibe la primera respuesta, y nada se asienta dos veces. En la ruta asíncrona, la misma clave con otro cuerpo responde 409.
  2. El llamador debe ser una aplicación que listas en tenant_policy/jd.direct_client_ids. Una persona en Plugin PIX JD Editor escribe esa clave, como muestra Dale a JD su credencial. Sigue su procedimiento para listar una aplicación para JD e incluye el client ID de la aplicación que hace el reenvío. Omite su paso 4 para esta aplicación: su secret va en la configuración de proveedor de Flowker de abajo, nunca a JD. Un llamador que no sea ninguna de las cuatro credenciales de esa sección recibe 403 PIX-0005.
  3. Devuelve a JD el estado del propio plugin. El 200 de un crédito dice que el dinero se asentó. El reenvío nunca responde 200 por su cuenta, y nunca cuando el plugin no respondió o rechazó la llamada.
  4. La ruta que expones a JD necesita su propia protección, como en Asegurar un webhook.

Enruta los callbacks por tu workflow de Flowker

El catálogo de Flowker tiene un proveedor nativo Pix JD. Tu enrutador suma una rama para este riel: un paso en ese proveedor, junto a los pasos de tus otros cores.
1

Crea la configuración del proveedor

Lee el id del proveedor en Listar proveedores del catálogo. Llama a Crear una configuración de proveedor con el client ID y el secret de la aplicación de la regla 2, en config.auth como {"type": "lerian_token_endpoint", "config": {"client_id": "...", "client_secret": "..."}}. El proveedor no acepta otro tipo de auth. La configuración no lleva dirección: la dirección del plugin es el ajuste PIX_JD_BASE_URL del deployment de Flowker, que Lerian define en Lerian Cloud. Una configuración protegida no puede estar en un workflow junto a configuraciones no protegidas. Por eso, úsala solo si todos los proveedores del router pueden protegerse, lo que significa recrear las configuraciones de tus otros cores. De lo contrario, déjala desactivada. allowedCallers en el último paso restringe solo quién ejecuta este workflow. Sin protección, cualquier aplicación que pueda escribir workflows puede poner esta configuración en un workflow nuevo y registrar un crédito sin dinero de Pix detrás, así que el acceso de escritura a Flowker pasa a ser tu límite real. Consulta Quién puede ejecutar y cambiar un workflow.
2

Agrega un paso por callback

En el workflow, agrega un paso Pix JD por cada ruta de la tabla. Lee los ejecutores del proveedor en Listar ejecutores del catálogo. En cada disparador de webhook, agrega Chave-Idempotencia a accepted_headers, para que el paso pueda reenviarla, y mapéala al parámetro Chave-Idempotencia de cada paso que la necesita: aceptar el encabezado solo lo guarda, y sin el mapeo un crédito responde 400. Define timeout_seconds en todo paso Pix JD en 10 o menos, por el motivo del paso siguiente. Consulta Configurar un disparador de webhook.
3

Responde a JD con la respuesta del plugin

Configura el disparador con response_mode sync y response_view passthrough, y termina cada rama en su paso Pix JD. Cuando el plugin responde con un estado que está en success_status_codes del paso (por defecto 200, 201, 202 y 204), JD recibe ese estado y su cuerpo. Cuando la llamada falla, Flowker responde 502 con su propio envelope. Flowker mantiene la conexión como máximo 15 segundos y luego responde 504 con el recibo de la ejecución mientras la ejecución sigue. Mantén la ejecución completa por debajo de 15 segundos, incluidos los pasos anteriores al paso Pix JD, para que JD reciba una respuesta antes del 504 de Flowker. No pongas un paso de espera en esas ramas: una espera responde 202 a JD antes de que el plugin responda. Deja retry en el valor por defecto: Flowker no reintenta un POST si no lo pides.
4

Restringe quién activa el workflow

Este workflow mueve dinero. Define allowedCallers con las aplicaciones de los llamadores en quienes confías y actívalo. Un llamador fuera de la lista recibe 403 FLK-0519, y no empieza ninguna ejecución.
Compruébalo antes de que JD llame. En tu entorno de homologación, envía un crédito a la ruta que JD va a llamar en dos situaciones rotas: con el plugin detenido, y con el plugin aceptando la llamada sin responder nunca. En ambas, JD debe ver un estado que no sea 2xx. Un 2xx significa que la ruta confirma créditos que nadie asentó, así que no conectes a JD con ella. En Lerian Cloud no puedes detener ni trabar el plugin: pide a Lerian que ejecute los dos casos en tu entorno de homologación. Envía el crédito con la credencial de una aplicación en allowedCallers. Los dos casos deben responder 502 (o 504) desde Flowker. Un 403 o 404 significa que la llamada nunca llegó al paso Pix JD y no prueba nada.

Cómo se ve cada paso omitido

Cada rechazo de abajo es un 409, salvo el de los límites. Ninguno desaparece si esperas. Cada uno desaparece cuando aprovisionas el valor que falta.
Cuando 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.
Las rutas contables son la excepción. PIX-0105 no tiene hermano 503. Una pata de ruta ausente, vacía, malformada, el UUID de todos ceros o ilegible da el mismo 409. Así que un PIX-0105 por sí solo no distingue “esta pata no tiene valor” de “el plano de configuración no respondió”. Vuelve a leer las patas antes de decidir que es una caída.
Los dos códigos de cada par rechazan la operación. Ninguno registra ni guarda nada. La diferencia está solo en tu siguiente acción, y por eso son códigos separados.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.
Dos códigos más nombran un servicio del que depende el riel. No tienen que ver con tu configuración. Reinténtalos: La lista de errores de Pix JD tiene todos los códigos, con el detail exacto de cada uno.

A dónde ir después

Variables de entorno

La configuración de este riel en el momento del despliegue: conectividad con JD, los endpoints del ledger y del CRM, el alojamiento de QR y los proveedores de notificaciones.

Multiorganización y ledgers

Extiende esta configuración a varios libros, o varios participantes directos, en el mismo despliegue: el catálogo de organizaciones, como un toggle.

Participantes indirectos

Qué es una participación hospedada, cómo llega a ella un crédito entrante, su ciclo de vida y todos los rechazos que puede responder.

Pix Directo vía JD

Cómo aterrizan en Midaz los movimientos Pix liquidados, y cómo se correlacionan los dos sistemas.

Lista de errores de Pix JD

Todos los códigos PIX-NNNN, su estado y el texto detail que lleva la respuesta.