Socios en Pix JD

Restringe la credencial de un socio en Pix JD a los participantes directos o a los participantes indirectos para los que actúa, nombra ese participante en cada solicitud, lee los rechazos que recibe y dale a JD sus rutas de canal como socio.

Un socio puede llamar a Pix JD con su propia credencial. Restringes esa credencial a los participantes directos (ISPBs) o a los participantes indirectos para los que actúa. Lo necesitas cuando un despliegue de Pix JD atiende a varios participantes.

Un socio de Pix JD necesita un ámbito, a menos que tenga solo los permisos de canal de JD. Un socio con otros permisos en Pix JD y sin restricción en Pix JD se rechaza. Consulta JD como socio.

Paso a paso

---

1. Elige para quién actúa el socio

   Pix JD tiene dos restricciones:

   Restricción	Campo en la API	Valores
   Participante directo de Pix (ISPB)	participantId	El ISPB de cada participante directo para el que actúa el socio, 8 letras mayúsculas o dígitos.
   Participante indirecto	indirectId	El indirectId de cada participante indirecto para el que actúa el socio, tal como Pix JD lo devolvió cuando registraste el participante indirecto.

   Úsalas de una de estas dos formas:

   El socio actúa para	Dale	Lo que alcanza
   Un participante directo, con todos sus participantes indirectos	Solo participantId, con el ISPB del participante directo	Todo el Pix de ese participante: claves, reclamos, límites, pagos, devoluciones, códigos QR, Pix Automático, MED, marcas de fraude y sus participantes indirectos.
   Un participante indirecto	Solo indirectId, con ese participante indirecto	Pagos y sus lecturas, devoluciones, códigos QR dinámicos, la decodificación de QR y la lista de códigos QR, infracciones, solicitudes de devolución y recuperaciones del MED, la consulta de clave, y el registro y las transacciones del propio participante indirecto.

   Para restringir un socio a un participante indirecto, dale solo indirectId. No agregues el ISPB del participante directo que liquida por él. Con los dos, el socio también lee los datos propios del participante directo: sus claves, reclamos, límites, marcas de fraude y registros de Pix Automático.

   Un socio restringido solo por ISPB es el socio de todo el participante directo. Alcanza a todos los participantes indirectos de ese participante directo.

   No pongas el ISPB de un participante indirecto en participantId. Access Manager lo acepta, pero el socio no queda restringido a ese participante indirecto. Usa indirectId.

2. Da al socio sus permisos y su ámbito

   Crea el socio, o cámbialo, en la Console o con la API de Identity. El identificador del producto es plugin-br-pix-jd. Las dos restricciones aceptan varios valores.

   • Agrega al menos una restricción para Pix JD. Sin ella, Access Manager rechaza el socio con 400 y IDE-1060.
   • Marca los recursos y las acciones. Lo máximo que puedes dar es lo que el rol plugin-br-pix-jd-editor-role tiene en tu tenant, más los permisos de canal de JD. Por encima de eso, Access Manager rechaza con IDE-1043.

   Access Manager verifica cada escritura que das contra el ámbito, y rechaza con 400 y IDE-1056 una escritura más amplia que el ámbito del socio. La Console marca la línea como Outside the scope:

   • Un socio con un participante indirecto en su ámbito solo puede recibir estas escrituras: crear pagos, crear devoluciones, crear o cambiar códigos QR dinámicos, y decodificar códigos QR. Toda otra escritura actúa sobre todo el participante directo: registrar claves, reclamos, límites, códigos QR estáticos, Pix Automático, marcas de fraude, las acciones sobre registros del MED, y registrar o cambiar participantes indirectos.
   • Las acciones del operador actúan sobre todo el tenant, y nunca se dan a un socio. Da los permisos de canal de JD solo en una entrada de permisos propia. Consulta JD como socio.
3. Crea su aplicación de Pix JD

   Crea la aplicación del socio con el producto plugin-br-pix-jd. Consulta cómo crear las aplicaciones del socio en la guía de la API o en la Console. Envía el client ID y el client secret al socio por un canal seguro.

4. Nombra el participante en cada solicitud

   Cada solicitud nombra para quién actúa el socio, en un campo que Pix JD ya tiene. El valor debe estar dentro del ámbito del socio. Una solicitud que no nombra a nadie se rechaza.

   Un socio de un participante directo nombra su ISPB:

   Rutas	Escrituras	Lecturas y rutas por ID
   Pagos y devoluciones: /v1/transactions, /v1/refunds	Cuerpo payerIspb	Query ispb
   Límites: /v1/limits	Cuerpo payerIspb	Query payer_ispb
   Claves y reclamos: /v1/entries, /v1/claims, /v1/account-closures, /v1/holder-removals	Cuerpo ispb, también en DELETE	Query ispb
   Códigos QR: /v1/qrcodes	Cuerpo ispb	Query ispb
   Pix Automático: /v1/pix-automatico	Cuerpo recipient.ispb para crear una autorización o una programación, recurrence.recipient.ispb para crear un código QR compuesto, payer.ispb para confirmar una autorización, requesterIspb para cancelar una programación, e ispb para decodificar o validar	Query ispb, también para responder, cancelar o cambiar el valor máximo de una autorización
   MED: /v1/med	Cuerpo ispb para crear una recuperación, una solicitud de devolución o una marca de fraude, y para cancelar una marca de fraude. Query ispb para las acciones sobre una infracción, una solicitud de devolución o una recuperación	Query ispb. Para listar infracciones, creatorIspb o counterpartIspb. Para listar solicitudes de devolución, requesterIspb o contestedIspb
   Participantes indirectos: /v1/indirects	Cuerpo directIspb para registrar uno, query directIspb para cambiar uno	Query directIspb

   Para pagar a través de uno de sus participantes indirectos, envía su propio ISPB en payerIspb y el participante indirecto en indirectId.

   Un socio de un participante indirecto nombra su indirectId:

   Rutas	Dónde
   Crear un pago o una devolución: POST /v1/transactions, POST /v1/refunds	Cuerpo indirectId. payerIspb no es necesario.
   Crear o cambiar un código QR dinámico: /v1/qrcodes/dynamic	Cuerpo indirectId
   Decodificar un código QR: POST /v1/qrcodes/decode, POST /v1/qrcodes/decode/url	Cuerpo indirectId
   Leer pagos: GET /v1/transactions, GET /v1/transactions/{transactionId}	Query indirectId
   Listar códigos QR, consultar una clave: GET /v1/qrcodes/list, GET /v1/entries/{entryId}/lookup	Query indirectId
   Infracciones, solicitudes de devolución y recuperaciones del MED: /v1/med	Query indirectId
   Su propio registro y sus transacciones: /v1/indirects/{indirectId}	El path

   Un campo del cuerpo que acepta un participante acepta un valor. No envíes una lista en él.

   Una solicitud a través de un participante indirecto declara al cliente y no nombra ninguna cuenta: payer en un pago, X-Payer-Document en la consulta de clave y en la decodificación de QR, y recipient en un código QR dinámico. Una devolución no necesita cuenta. Si viene de un socio, una cuenta en estas solicitudes (accountId, o account_id en la consulta) responde 400 con PIX-0061. Mira Declara al cliente del participante indirecto.

5. Confirma que funciona

   Usa la credencial del socio. Lee uno de los pagos del propio socio, nombrando su propio ISPB. La respuesta es 200:

   PIX_JD_BASE_URL="https://pix.<your-domain>"            # your Pix JD base URL
   PIX_JD_BEARER_TOKEN="paste-the-partner-access-token-here"
   OWN_ISPB="12345678"                                    # an ISPB in the partner's scope
   TRANSACTION_ID="paste-a-transaction-id-here"
   
   curl -s -o /dev/null -w '%{http_code}\n' \
     -H "Authorization: Bearer ${PIX_JD_BEARER_TOKEN}" \
     "${PIX_JD_BASE_URL}/v1/transactions/${TRANSACTION_ID}?ispb=${OWN_ISPB}"
   

   Para un socio de un participante indirecto, envía indirectId en lugar de ispb, con su propio valor.

   Envía la misma solicitud con un ISPB fuera del ámbito del socio. La respuesta es 403 con PIX-0005. Envíala con el ID de un pago de otro participante. La respuesta es 404 con PIX-0147.

JD como socio

---

JD puede llamar a las rutas que llama en Pix JD como socio de tu tenant. Estas rutas reciben Pix entrantes, devoluciones, validaciones de cuenta y los mensajes de Pix Automático. Dale al socio estos nueve permisos en el producto plugin-br-pix-jd, en una entrada de permisos que no tiene nada más:

Recurso	Acciones
cash-ins	post
reversals	post
validates	post
validates-async	post
authorizations-inbound	post
schedules-inbound	post
settlements-inbound	post, delete
events	post

Esta entrada no necesita ámbito, y aplica a todos los participantes de tu tenant. Access Manager la acepta solo cuando Pix JD publica su declaración de permisos. Crea el socio y su aplicación con la API de Identity. Luego, dale a JD el client ID y el client secret.

Rutas que ningún socio alcanza

---

Un socio con ámbito en Pix JD se rechaza con 403 en estas rutas:

• Los directorios que no nombran participante: GET /v1/banks, GET /v1/banks/participants y GET /v1/refunds/reasons.
• Los cambios de código QR compuesto: PUT /v1/pix-automatico/composite/cobv/{id}, PUT /v1/pix-automatico/composite/dynamic/{id} y PUT /v1/pix-automatico/composite/recurrence/{id}.

Usa una aplicación de tu propia institución para esas rutas.

Si algo falla

---

Código	Estado	Qué significa	Qué hacer
PIX-0005	403	La solicitud nombra un participante fuera del ámbito del socio, no nombra ninguno, o está fuera de los permisos del socio. Una lista en una query con un valor fuera del ámbito también se rechaza.	Nombra el participante en el campo de esa ruta, con un valor del ámbito del socio. Verifica también que el socio tenga el permiso de esa ruta.
PIX-0002	400	Un campo del cuerpo recibió varios participantes, o dos campos de la misma solicitud nombran participantes distintos.	Envía un participante, el mismo en todos los campos.
PIX-0147	404	El registro que la solicitud direcciona no se mantiene bajo el participante que nombra la solicitud. No se lee ni se cambia nada, y la respuesta no dice quién tiene el registro.	Verifica el ID.
PIX-0061	400	En una consulta por ID de Pix Automático (una autorización, una programación o sus cancelaciones), el registro pertenece a otro participante.	Nombra el participante bajo el que se creó la autorización o la programación.
PIX-0128	422	El ISPB está en el ámbito del socio, pero tu institución no lo opera en Pix JD.	Verifica el ISPB.
PIX-0004	401	El socio está suspendido, o la solicitud está fuera de su ventana de validez.	Reactiva el socio, o cambia su ventana de validez.

PIX-0005 no indica si fueron los permisos o el ámbito los que rechazaron la solicitud. Es intencional: un socio no puede usar un rechazo para saber qué participantes existen fuera de su ámbito.

Para todos los demás códigos, consulta la lista de errores de Pix JD. Para los rechazos al crear o cambiar un socio, consulta los códigos de error de la guía de la API.