> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Socios en Pix Lerian

> Restringe las credenciales de Pix Lerian de un socio a las cuentas en las que actúa, indica la cuenta en cada solicitud y entiende los rechazos que recibe.

Un [socio](https://docs.lerian.studio/es/platform/access-manager/features/partners/overview) puede llamar a Pix Lerian con su propia credencial. Restringes esa credencial a algunas cuentas de tu tenant. Lo necesitas cuando el socio actúa para algunos de tus clientes y no debe actuar sobre las cuentas de los demás.

Todo socio de Pix Lerian necesita un alcance.

## Paso a paso

***

**1. Elige los productos que usa el socio**

Pix Lerian son cuatro productos en Access Manager. Da al socio solo los productos que necesita:

| Producto | Slug del producto | Lo que atiende |
| - | - | - |
| **SPI** | `plugin-br-pix-lerian-spi` | Cash-out y cash-in, devoluciones, Pix Agendado y bloqueos de saldo. |
| **DICT hub** | `plugin-br-pix-lerian-dict` | Claves, reivindicaciones y MED. |
| **COB hub** | `plugin-br-pix-lerian-cob` | Cobros y BR Codes. |
| **Pix Automático** | `plugin-br-pix-lerian-pixauto` | Las autorizaciones del pagador y sus pagos. |

El adaptador de conectividad no acepta socios. Solo los servicios de Pix Lerian lo llaman.

**2. Elige las cuentas en las que actúa el socio**

Pix Lerian tiene una restricción, la misma en los cuatro productos:

| Restricción | Campo de la API | Lo que alcanza el socio | Lo que se rechaza |
| - | - | - | - |
| **Cuenta** | `accountId` | Los registros de Pix de cada cuenta de la lista: el ID de la cuenta en Midaz del pagador o del cliente, el mismo ID que tu cliente envía en `X-Account-Id`. | Todas las demás cuentas, y las rutas que no llevan cuenta (consulta [Rutas que ningún socio alcanza](#routes-that-no-partner-reaches)). |

Pix Lerian no tiene restricción de organización ni de ledger. Cada tenant opera una organización y un ledger de Midaz. La configuración del tenant los define, y ninguna solicitud los indica. Para restringir un socio a un ledger, dale también un [alcance en Midaz](https://docs.lerian.studio/es/platform/access-manager/features/partners/midaz.md). Consulta [Las reglas del socio en Midaz valen para sus llamadas](#the-partners-midaz-rules-apply-to-its-calls).

**3. Da al socio sus permisos y su alcance**

Crea el socio, o modifícalo, en la [Consola](https://docs.lerian.studio/es/platform/access-manager/features/partners/console.md) o con la [API de Identity](https://docs.lerian.studio/es/platform/access-manager/features/partners/api.md). Usa los slugs de producto del primer paso. La restricción acepta varias cuentas.

* Agrega la entrada de alcance `accountId` en cada producto de Pix Lerian que des. Sin ella, Access Manager rechaza el socio con `400` e `IDE-1060`.
* Revisa los recursos y las acciones. Lo máximo que puedes dar es lo que tiene el rol de editor de cada producto en tu tenant. Por encima de eso, Access Manager rechaza con `IDE-1043`.

Algunas escrituras actúan sobre rutas que no llevan cuenta:

* Los bloqueos de saldo.
* La bandeja de salida de notificaciones.
* Las rutas de operador que ejecutan y recuperan trabajos.
* La recuperación de una transferencia o de una devolución: `transfer-recovery` y `refund-recovery`, acción `post`.
* La configuración de runtime.

Access Manager las rechaza con `400` e `IDE-1056`, y la Consola marca la línea como **Fuera del alcance**.

Access Manager también rechaza, con el mismo código, las escrituras que cambian una clave, abren una recuperación de fondos o crean un pago recurrente. Consulta [Rutas que ningún socio alcanza](#routes-that-no-partner-reaches).

**4. Crea sus aplicaciones de Pix Lerian**

Crea las aplicaciones del socio con los productos de Pix Lerian que le diste. Consulta [Crea las aplicaciones del socio](https://docs.lerian.studio/es/platform/access-manager/features/partners/api.md#create-the-partners-applications) en la guía de la API, o [en la Consola](https://docs.lerian.studio/es/platform/access-manager/features/partners/console.md#create-the-partners-applications). Envía el client ID y el client secret al socio por un canal seguro.

**5. Indica la cuenta en cada solicitud**

Toda solicitud indica la cuenta en un campo que Pix Lerian ya tiene. El valor debe estar en el alcance del socio. Un socio debe enviar la cuenta en todas las rutas de esta tabla, también donde el campo es opcional para otros llamadores. Una solicitud sin ella se rechaza.

| Producto | Rutas | Dónde va la cuenta |
| - | - | - |
| SPI | Transferencias: `POST /spi/v1/transfers/cashout/initiate`, `POST /spi/v1/transfers/cashout/process`, `GET /spi/v1/transfers`, `GET /spi/v1/transfers/{id}`, `POST /spi/v1/transfers/{id}/refunds` | Encabezado `X-Account-Id` |
| SPI | Devoluciones: `GET /spi/v1/refunds`, `GET /spi/v1/refunds/{id}` | Encabezado `X-Account-Id` |
| SPI | Escrituras de Pix Agendado: `POST /spi/v1/scheduled-payments`, `POST /spi/v1/scheduled-payment-recurrences` | Cuerpo `accountId` |
| SPI | Listas de Pix Agendado: `GET /spi/v1/scheduled-payments`, `GET /spi/v1/scheduled-payment-totals`, `GET /spi/v1/scheduled-payment-limit-impact`, `GET /spi/v1/scheduled-payment-recurrences` | Query `account_id` |
| DICT hub | Claves: `GET` y `POST /dict-hub/v1/entries`, `GET` y `DELETE /dict-hub/v1/entries/{entry_id}`, `GET /dict-hub/v1/keys/{key}` | Encabezado `X-Account-Id` |
| DICT hub | Reivindicaciones: `GET` y `POST /dict-hub/v1/claims`, `GET /dict-hub/v1/claims/{claim_id}`, `POST /dict-hub/v1/claims/{claim_id}/cancel`, `/complete` y `/confirm` | Encabezado `X-Account-Id` |
| DICT hub | Recuperaciones de fondos del MED: `GET /dict-hub/v1/dict/funds-recoveries` | Query `account_id` |
| COB hub | `POST /cob-hub/v1/brcodes/static`, `GET` y `POST /cob-hub/v1/collections/immediate`, `GET` y `DELETE /cob-hub/v1/collections/immediate/{id}`, `GET` y `POST /cob-hub/v1/collections/duedate`, `GET /cob-hub/v1/collections/duedate/provider-status`, `GET`, `PATCH` y `DELETE /cob-hub/v1/collections/duedate/{id}` | Encabezado `X-Account-Id` |
| Pix Automático | Solicitudes de autorización: `GET /pixauto/v1/payer/authorization-requests`, `GET /pixauto/v1/payer/authorization-requests/{authorization_request_id}`, `POST .../{authorization_request_id}/decide` | Encabezado `X-Account-Id` |
| Pix Automático | Autorizaciones: `GET /pixauto/v1/payer/authorizations`, `GET` y `PATCH /pixauto/v1/payer/authorizations/{authorization_id}`, `GET .../{authorization_id}/history`, `POST .../{authorization_id}/cancel` | Encabezado `X-Account-Id` |
| Pix Automático | Pagos programados: `GET /pixauto/v1/payer/scheduled-payments`, `GET /pixauto/v1/payer/scheduled-payments/{scheduled_payment_id}`, `POST .../{scheduled_payment_id}/cancel`, `POST .../{scheduled_payment_id}/unblock` | Encabezado `X-Account-Id` |
| Pix Automático | `POST /pixauto/v1/payer/authorization-requests/from-qr` | Cuerpo `payerAccountId` |

Una solicitud que indica un registro de otra cuenta responde `404`, como si el registro no existiera. No se lee ni se cambia nada.

**6. Confirma que funciona**

Esta verificación supone que el socio tiene el recurso `transfers` con la acción `get` en `plugin-br-pix-lerian-spi`, y un alcance con una o más cuentas. Usa la credencial del socio. Lista las transferencias de una cuenta del alcance del socio. La respuesta es `200`:

```bash theme={null}
PIX_LERIAN_SPI_BASE_URL="https://pix.<your-domain>"          # your Pix Lerian SPI base URL
PIX_LERIAN_BEARER_TOKEN="paste-the-partner-access-token-here"
OWN_ACCOUNT_ID="paste-an-account-in-the-scope"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${PIX_LERIAN_BEARER_TOKEN}" \
  -H "X-Account-Id: ${OWN_ACCOUNT_ID}" \
  "${PIX_LERIAN_SPI_BASE_URL}/spi/v1/transfers"
```

Envía la misma solicitud con una cuenta fuera del alcance del socio. La respuesta es `403` con `PIX-0010`.

## Las reglas del socio en Midaz valen para sus llamadas

***

Algunos productos de Pix Lerian llaman a Midaz mientras atienden la solicitud del socio:

* SPI registra los débitos y los créditos en el ledger, y lee la cuenta y su titular.
* DICT hub y Pix Automático leen el titular y la cuenta en el CRM integrado en Midaz.

Cuando el socio también tiene permisos en Midaz, Midaz aplica el alcance del socio en Midaz a esas llamadas. Por ejemplo, considera un socio restringido en Midaz a la organización del tenant y a un ledger. Puede iniciar y procesar un cash-out desde una cuenta de ese ledger. Con el mismo socio restringido en Midaz a otro ledger, Pix Lerian rechaza la iniciación y el procesamiento con `403` y `PIX-0005`, y el saldo de la cuenta no cambia.

* Un socio sin permisos en Midaz se decide solo por sus permisos y su alcance en Pix Lerian.
* Puedes dar al socio sus reglas de Midaz en el mismo flujo de la Consola, o después, en el producto Midaz.
* Los barridos programados, los callbacks del proveedor y los demás trabajos en segundo plano se ejecutan sin socio. Las reglas del socio no se aplican allí.

> [!WARNING]
>
> No cuentes con las reglas de Midaz con un CRM 3.x independiente. Si tu implementación lee titulares de un CRM 3.x independiente, ese CRM no aplica las reglas del socio. Solo el CRM integrado en Midaz las aplica.

## Rutas que ningún socio alcanza

***

Un socio con alcance en Pix Lerian se rechaza con `403` y `PIX-0010` en las rutas que no llevan cuenta:

* SPI: todas las rutas de `/spi/v1/balance-locks`, las rutas de un pago programado o de una recurrencia (`/spi/v1/scheduled-payments/{schedule_id}` y `/spi/v1/scheduled-payment-recurrences/{recurrence_id}`, con las rutas debajo de ellas), y las rutas de operador.
* DICT hub: `POST /dict-hub/v1/claims/{claim_id}/acknowledge`, `POST /dict-hub/v1/keys/check`, las rutas de una recuperación de fondos, y las rutas de notificaciones de infracción, devoluciones, marcas de fraude y VSync.
* COB hub: `POST /cob-hub/v1/brcodes/decode`, `GET /cob-hub/v1/brcodes/static` y `GET /cob-hub/v1/brcodes/static/{id}`.
* Pix Automático: `POST /pixauto/v1/payer/recurring-consents` y `POST /pixauto/v1/payer/recurring-consents/{recurring_consent_id}/revoke`.

Estas rutas actúan sobre registros que ninguna cuenta indica.

Pix Lerian también rechaza un socio, con la misma respuesta, en tres rutas en las que la cuenta de la solicitud no vincula lo que la ruta cambia:

* `PATCH /dict-hub/v1/entries/{entry_id}`: la solicitud puede mover la clave a otra cuenta.
* `POST /dict-hub/v1/dict/funds-recoveries`: la ruta abre la recuperación sobre una transacción que la cuenta no vincula.
* `POST /pixauto/v1/payer/recurring-payments`: la ruta acepta el pago bajo un consentimiento que la cuenta no vincula.

Pix Lerian también rechaza un socio, con la misma respuesta, en las cuatro rutas de recuperación de SPI. Esto vale también cuando la solicitud indica una cuenta del alcance del socio:

* `POST /spi/v1/transfers/{id}/unblock` y `POST /spi/v1/transfers/{id}/credit`.
* `POST /spi/v1/refunds/{id}/unblock` y `POST /spi/v1/refunds/{id}/credit`.

Tu equipo de operaciones usa estas rutas para corregir una transacción atascada en procesamiento, o un crédito que falló en el ledger. Actúan por todo el tenant, así que la cuenta de la solicitud no las restringe.

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

## Si algo falla

***

| Código | Estado | Qué significa | Qué hacer |
| - | - | - | - |
| `PIX-0010` | 403 | La solicitud indica una cuenta fuera del alcance del socio, no indica ninguna, o está fuera de los permisos o de la lista de IP del socio. | Envía la cuenta en el campo de esa ruta, con una cuenta del alcance del socio. Revisa también los permisos y la lista de IP del socio. |
| `PIX-0010` | 401 | El socio está suspendido, o la solicitud está fuera de su período de validez. | Reactiva el socio, o cambia su período de validez. |
| `PIX-0005` | 403 | Midaz rechazó el socio en una llamada que Pix Lerian hizo para él: la llamada está fuera de los permisos o del alcance del socio en Midaz. No se mueve nada. | Revisa los permisos y el alcance del socio en Midaz. |
| `PIX-0320` | 404 | La iniciación pertenece a otra cuenta. No se lee ni se cambia nada. | Revisa el ID de la iniciación y la cuenta. |
| `PIX-0340` | 404 | La transferencia pertenece a otra cuenta. No se lee ni se cambia nada. | Revisa el ID de la transferencia y la cuenta. |

`PIX-0010` no dice si fueron los permisos o el alcance los que rechazaron la solicitud. Es intencional: un socio no puede usar un rechazo para saber qué cuentas existen fuera de su alcance.

Un cambio en un socio, como una suspensión o un nuevo alcance, vale desde su siguiente solicitud, también con un token que ya tiene.

Para todos los demás códigos, consulta la [lista de errores de Pix Lerian](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/pix-lerian-error-list.md). Para los rechazos al crear o cambiar un socio, consulta [Códigos de error](https://docs.lerian.studio/es/platform/access-manager/features/partners/api.md#error-codes) en la guía de la API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.