> ## 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 Midaz

> Restringe la credencial de un socio en Midaz a una organización y, dentro de ella, a los ledgers, cuentas, alias, carteras, segmentos, titulares o rutas que elijas, y lee los rechazos que recibe.

Un [socio](https://docs.lerian.studio/es/platform/access-manager/features/partners/overview) puede llamar a Midaz con su propia credencial. En Midaz, restringes esa credencial a una organización y, si quieres, a algunos elementos dentro de ella. Esta página muestra cómo elegir ese ámbito, qué alcanza cada opción y qué recibe el socio cuando sale de él.

Todo socio de Midaz necesita un ámbito. La organización siempre es obligatoria.

## Paso a paso

***

**1. Elige dónde actúa el socio**

Elige el ámbito más estrecho que cubra lo que el socio necesita. Cada fila es una restricción que puedes agregar. El **campo en la API** es el `field` de una entrada de ámbito; la Console muestra el nombre de la primera columna.

| Restricción | Campo en la API | Lo que alcanza el socio | Lo que se rechaza |
| - | - | - | - |
| **Organización de Midaz** (obligatoria, un valor) | `organizationId` | Sin otra restricción: todo lo que sus permisos le dan dentro de esa organización, en cualquier ledger. | Todas las demás organizaciones. |
| **Ledger** | `ledgerId` | Sus propios ledgers por ID, y las cuentas, saldos y transacciones dentro de ellos. También lee su organización. | Otros ledgers, la lista de ledgers de la organización, titulares, instrumentos sin ledger, los registros de auditoría del CRM y las rutas de operación y de transacción (ver la última fila). |
| **Cuenta** | `accountId` | Cada cuenta listada, sus saldos y sus operaciones, por ID de cuenta. | Listar las cuentas del ledger, un saldo por su propio ID, transacciones (lista y por ID) y las rutas por alias. |
| **Alias de cuenta** | `accountAlias` | Cada cuenta listada y sus saldos, por las rutas por alias. Puede crear transacciones desde sus propios alias. | Las rutas por ID de cuenta. |
| **Cartera** o **Segmento** | `portfolioId`, `segmentId` | Listar cuentas filtradas por su propia cartera o segmento, y crear cuentas en ella. | Una cuenta por ID, saldos y transacciones. |
| **Titular** | `holderId` | Sus propios titulares, sus cuentas y la lista de cuentas filtrada por su propio titular. | Listar todos los titulares. |
| **Ruta de operación** o **Ruta de transacción** | `operationRouteId`, `transactionRouteId` | Solo las rutas cuyos IDs listas, leídas por ID bajo el ledger del socio. | Listar rutas, y leer una ruta bajo la organización en lugar del ledger cuando el socio también está restringido por ledger. |

El catálogo de ámbito lista todas las restricciones de Midaz, incluidas las que no están en esta tabla. Léelo con [Consultar el catálogo de ámbito de un producto](https://docs.lerian.studio/es/reference/platform/access-manager/retrieve-a-product-s-scope-catalog.md) para `midaz`.

Algunas reglas valen para todo ámbito:

* Una solicitud que no nombra un elemento de un tipo restringido se rechaza cuando actúa sobre lo que esa restricción limita. Por ejemplo, un socio restringido a algunos ledgers no puede listar todos los ledgers de su organización. Una solicitud fuera de lo que la restricción limita solo necesita la organización.
* Una solicitud que lista varios valores, como varios alias en un cuerpo o en una query, se rechaza cuando cualquiera de ellos está fuera del ámbito.
* Las rutas que actúan sobre todo el tenant, como listar organizaciones o leer la configuración del tenant, se rechazan a todo socio.

**2. Da al socio sus permisos y su ámbito**

Crea el socio, o cámbialo, en la [Console](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). El identificador del producto es `midaz`.

* Agrega la entrada de ámbito de la organización, con exactamente un valor. Sin ella, Access Manager rechaza el socio con `400` y `IDE-0001`. Con dos organizaciones, rechaza con `IDE-0002`.
* Agrega las otras restricciones que elegiste en el paso 1.
* Marca los recursos y las acciones. Lo máximo que puedes dar es lo que el rol `midaz-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:

* Una escritura que actúa sobre todo el tenant, como crear una organización, nunca se da a un socio.
* Una escritura que actúa por encima del ámbito del socio se rechaza. Por ejemplo, un socio restringido a un ledger no puede recibir el derecho de crear, cambiar o eliminar ledgers, titulares, o rutas de operación y de transacción: esas escrituras actúan sobre toda la organización.
* Los dos rechazos responden `400` con `IDE-1056`. La Console marca la línea como **Outside the scope**.

Para dar lectura de las rutas de operación o de transacción, lista los IDs de las rutas en el ámbito. Sin ellos, Access Manager rechaza el socio con `400` y `IDE-1052`. Access Manager no verifica que el ID de una ruta pertenezca al ledger del socio: el socio lee toda ruta cuyo ID listas. Lista solo las rutas de sus propios ledgers.

No des `transactions` con `post` a un socio restringido solo por cartera, segmento o titular. Access Manager lo acepta, pero toda transacción de ese socio se rechaza.

**3. Crea su aplicación de Midaz**

Crea la aplicación del socio con el producto `midaz`. Consulta cómo crear las aplicaciones del socio en la [guía de la API](https://docs.lerian.studio/es/platform/access-manager/features/partners/api.md#create-the-partners-applications) o en la [Console](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.

**4. Indica al socio cómo nombrar sus elementos**

En la mayoría de las rutas de Midaz, la organización y el ledger ya están en el path, así que el socio no envía nada extra. El socio nombra sus demás elementos en los paths, queries y cuerpos que Midaz ya tiene. Cada valor debe estar dentro del ámbito del socio.

En la tabla, `…/ledgers/{ledger_id}` representa `/organizations/{organization_id}/ledgers/{ledger_id}`, después de `/v1` o `/v2`.

| Rutas | Escrituras | Lecturas y rutas por ID |
| - | - | - |
| Organizaciones y ledgers: `/v1` y `/v2` `/organizations/{organization_id}`, `/organizations/{organization_id}/ledgers` | Path `organization_id` para crear un ledger, y `ledger_id` para cambiarlo, eliminarlo o cambiar su configuración | Path `organization_id`, y `ledger_id` para un ledger y su configuración |
| Cuentas: `/v1` y `/v2` `…/ledgers/{ledger_id}/accounts` | Para crear: cuerpo `portfolioId`, `segmentId` y `parentAccountId`, y en `/v2` también `holderId`. Para cambiar, eliminar o cerrar (solo en `/v2`): path `account_id` | Para listar: query `portfolio_id`, `segment_id` o `holder_id`. Una cuenta: path `account_id`, o `alias` en `…/accounts/alias/{alias}` |
| Cuentas de un titular: `/v2/organizations/{organization_id}/holders/{holder_id}/accounts`, `/v2/…/ledgers/{ledger_id}/holders/{holder_id}/accounts` | Para crear una cuenta para el titular: path `holder_id`, y cuerpo `portfolioId`, `segmentId` y `parentAccountId` | Path `holder_id`, y query `ledger_id`. La respuesta trae solo las cuentas de ese ledger |
| Excepciones de bloqueo de cuenta: `/v2/…/ledgers/{ledger_id}/accounts/block-exceptions` | Cuerpo `exceptions[].accountAlias` | Ninguna: la ruta solo escribe |
| Saldos: `/v1` y `/v2` `…/ledgers/{ledger_id}/balances`, `…/accounts/{account_id}/balances`, `…/accounts/alias/{alias}/balances` | Para crear: path `account_id`. Para cambiar o eliminar: path `balance_id` | Path `account_id` o `alias` para los saldos de una cuenta, y `balance_id` para un saldo y su historial |
| Operaciones: `/v1` y `/v2` `…/accounts/{account_id}/operations`, `…/transactions/{transaction_id}/operations/{operation_id}` | Para cambiar: path `transaction_id` y `operation_id` | Path `account_id`, y `operation_id` para una operación |
| Transacciones en `/v1`: `/v1/…/ledgers/{ledger_id}/transactions` | Para crear con `json`, `outflow`, `annotation`, `block` o `unblock`: cuerpo `send.source.from[].accountAlias`. `inflow` nombra solo el ledger. Para confirmar, cancelar, revertir o cambiar: path `transaction_id` | Path `transaction_id` |
| Transacciones en `/v2`: `/v2/transactions`, `/v2/…/ledgers/{ledger_id}/transactions` | Para crear con `direct`, `hold`, `block` o `unblock`: cuerpo `debits[].organizationId`, `debits[].ledgerId` y `debits[].alias`, y los mismos tres en `credits[]`. Con `batch`, los mismos campos en cada elemento de `transactions[]`. Para confirmar, cancelar, revertir o cambiar: path `transaction_id` | Path `transaction_id` |
| Titulares e instrumentos: `/v2/organizations/{organization_id}/holders`, `/v2/organizations/{organization_id}/holders/{holder_id}/instruments`, `/v2/organizations/{organization_id}/instruments` | Para cambiar o eliminar un titular: path `holder_id`. Para crear un instrumento: path `holder_id`, y cuerpo `ledgerId` y `accountId`, siempre. Para cambiar o eliminar uno: path `holder_id` e `instrument_id` | Path `holder_id`, e `instrument_id` para un instrumento. Para listar instrumentos: query `holder_id`, `account_id` o `ledger_id` |
| Rutas de operación y de transacción: `/v1` y `/v2` `…/ledgers/{ledger_id}/operation-routes`, `…/ledgers/{ledger_id}/transaction-routes`, y en `/v2` también bajo `/organizations/{organization_id}` | Path `organization_id`, y `ledger_id` en las rutas bajo el ledger | Path `ledger_id`, con `operation_route_id` o `transaction_route_id`. Las rutas bajo la organización no nombran el ledger |
| Tarifas y facturación: `/v2/…/ledgers/{ledger_id}/packages`, `…/billing-packages`, `…/fee-debts` | Paquete de tarifas: cuerpo `segmentId`. Paquete de facturación: cuerpo `accountTarget.segmentId`, `accountTarget.portfolioId` y `accountTarget.aliases[]`. Para cobrar deudas de tarifas: cuerpo `accountAlias` | Paquetes de tarifas: query `segmentId`. Deudas de tarifas: query `account_alias`. Un elemento: path `package_id`, `billing_package_id` o `fee_debt_id` |
| Planes de tarifas y cobros de comisiones: `/v2/…/ledgers/{ledger_id}/account-plans`, `…/accounts/{account_id}/account-plan`, `…/accounts/{account_id}/fee-charges` | Para crear un plan: path `ledger_id`. Para cambiar o eliminar uno: path `account_plan_id`. Para asignar un plan: path `account_id` y cuerpo `accountPlanId`. Para terminar una asignación o cobrar comisiones de servicio: path `account_id` | Path `account_plan_id` para un plan, sus versiones y sus cuentas. Path `account_id` para la asignación, el uso y los cobros, y `fee_charge_id` para un cobro |
| Configuración del ledger y dashboard: activos, tasas de cambio, tipos de cuenta, carteras, segmentos y `…/ledgers/{ledger_id}/dashboard` | Path `ledger_id`. Para cambiar o eliminar un elemento: path `asset_id`, `account_type_id`, `portfolio_id` o `segment_id` | Path `ledger_id`. Un elemento: path `asset_id`, `account_type_id`, `portfolio_id` o `segment_id` |

> [!WARNING]
>
> En las rutas de transacción de `/v1`, solo se verifican las cuentas de origen. Un socio restringido por alias puede enviar dinero desde sus propios alias a cualquier cuenta de su ledger. Para mantenerlo entre sus propias cuentas, no le des `transactions` con `post`.

En las rutas `/v2/transactions`, cada débito y cada crédito nombra una organización y un ledger dentro del ámbito. Un socio restringido por alias solo puede usar sus propios alias en los dos lados.

Un socio restringido por cuenta o alias no puede usar estas rutas de transacción: `inflow` en `/v1`, y confirmar, cancelar, revertir, cambiar, leer por ID o listar. Un socio restringido por alias puede crear una retención. Un socio restringido por ID de cuenta no puede crear transacciones. Para que mueva dinero desde cuentas específicas, restríngelo por alias.

Un campo del cuerpo que acepta un elemento acepta un valor, como `portfolioId` o el `alias` de un débito. No envíes una lista en él.

**5. Confirma que funciona**

Esta verificación supone que el socio tiene el recurso `accounts` con la acción `get` en Midaz, y un ámbito restringido a una organización y a uno o más de sus ledgers. Usa la credencial del socio. Lista las cuentas de un ledger dentro de su ámbito. La respuesta es `200`:

```bash theme={null}
MIDAZ_BASE_URL="https://midaz.<your-domain>"              # your Midaz ledger API base URL
MIDAZ_BEARER_TOKEN="paste-the-partner-access-token-here"
ORGANIZATION_ID="paste-the-organization-id-here"          # the organization in the partner's scope
LEDGER_ID="paste-a-ledger-id-in-the-scope-here"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${MIDAZ_BEARER_TOKEN}" \
  "${MIDAZ_BASE_URL}/v1/organizations/${ORGANIZATION_ID}/ledgers/${LEDGER_ID}/accounts"
```

Envía la misma solicitud con un ledger de la misma organización que está fuera del ámbito. La respuesta es `403` con el código `AUT-1020`.

## Si algo falla

***

| Código | Estado | Qué significa | Qué hacer |
| - | - | - | - |
| `AUT-1020` | 403 | La solicitud está fuera de los permisos o fuera del ámbito del socio, o no nombra un elemento que el ámbito exige. El mensaje nombra el recurso y la acción: "the credential is not allowed to perform `<resource>:<action>` on this request". | Verifica que la solicitud nombre su organización y sus elementos, y que estén en el ámbito del socio. Verifica también que el socio tenga el permiso de esa ruta. |
| `0047` | 400 | Midaz no puede leer el ámbito de la solicitud: un campo que necesita falta, está vacío o no es una cadena. | Envía cada campo que el ámbito necesita, como una cadena no vacía. |
| `AUT-1009` | 401 | El socio está suspendido. | Reactiva el socio. |
| `AUT-1010` | 401 | La solicitud está fuera de la ventana de validez del socio. | Cambia la ventana de validez. |
| `AUT-0021` | 403 | La solicitud viene de una dirección fuera de la lista de IP del socio, o de la lista de tu tenant cuando el socio no tiene una. | Agrega la dirección a la lista de IP del socio. |

La respuesta 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é elementos existen fuera de su ámbito.

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


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