Socios en Pix JD

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, y el sistema de cada cliente debe ver y mover solo su propio Pix. Todo socio de Pix JD necesita un ámbito. Un socio con permisos en Pix JD y sin restricción en Pix JD se rechaza.

Paso a paso

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 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 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. Nada del participante directo, y nada de los otros participantes indirectos.

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 pasa a ser rechazado en casi todas las rutas, y no queda restringido a ese participante indirecto. Usa indirectId.

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. 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, y crear o cambiar códigos QR dinámicos. 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 escrituras que actúan sobre todo el tenant, como las acciones del operador y los callbacks del arreglo, nunca se dan a un socio.

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.

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

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.

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 pertenece a otro participante. No se lee ni se cambia nada, y la respuesta no dice quién tiene el registro.	Nombra el participante bajo el que se creó el registro, o 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.

Introducción

Access Manager

Console

Streaming Hub

Multi-tenancy

Observabilidad

Narya

Lifecycle Management

Licenciamiento

Socios en Pix JD

Paso a paso

Rutas que ningún socio alcanza

Si algo falla

​Paso a paso

​Rutas que ningún socio alcanza

​Si algo falla

Paso a paso

Rutas que ningún socio alcanza

Si algo falla