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

# Gestiona socios por API

> Crea, lee, cambia y elimina socios con la Identity API, lee los catálogos de ámbito de los productos, crea aplicaciones de socios y maneja los códigos de error.

La Identity API gestiona [socios](https://docs.lerian.studio/es/platform/access-manager/features/partners/overview) y sus aplicaciones. Úsala cuando gestionas socios desde tus propias herramientas en lugar de la Console.

## Antes de empezar

***

Para gestionar socios, un usuario necesita los permisos `partners` de `plugin-identity`: `get` para leer socios y catálogos de ámbito, `post` para crear un socio, `patch` para cambiar uno y `delete` para eliminar uno. Gestionar sus aplicaciones necesita los permisos `applications` `get`, `post` y `delete`. El rol `plugin-identity-editor-role` los tiene todos.

## Las operaciones

***

| Operación | Qué hace | Referencia |
| - | - | - |
| `GET /v1/partners` | Lista tus socios, una página a la vez, con `applicationsCount` para cada uno. | [Listar socios](https://docs.lerian.studio/es/reference/platform/access-manager/list-partners.md) |
| `POST /v1/partners` | Crea un socio. Devuelve `201` con el nuevo socio y su `id`. No crea ninguna aplicación. | [Crear un socio](https://docs.lerian.studio/es/reference/platform/access-manager/create-a-partner.md) |
| `GET /v1/partners/{id}` | Devuelve un socio. | [Consultar un socio](https://docs.lerian.studio/es/reference/platform/access-manager/retrieve-a-partner.md) |
| `PATCH /v1/partners/{id}` | Cambia un socio: su nombre, sus permisos, su ámbito, su ventana de validez, su lista de IP permitidas o su estado. | [Actualizar un socio](https://docs.lerian.studio/es/reference/platform/access-manager/update-a-partner.md) |
| `DELETE /v1/partners/{id}` | Elimina un socio sin aplicaciones. Devuelve `204`. | [Eliminar un socio](https://docs.lerian.studio/es/reference/platform/access-manager/delete-a-partner.md) |
| `GET /v1/partners/ceiling` | Devuelve lo máximo que puedes dar a un socio en el producto que nombra el parámetro de consulta `product`. | [Consultar el techo de socios de un producto](https://docs.lerian.studio/es/reference/platform/access-manager/retrieve-the-partner-ceiling-of-a-product.md) |
| `GET /v1/scope-catalog` | Lista los catálogos de ámbito que publicaron los productos, con `partners` para cada uno. | [Listar catálogos de ámbito](https://docs.lerian.studio/es/reference/platform/access-manager/list-scope-catalogs.md) |
| `GET /v1/scope-catalog/{product}` | Devuelve el catálogo de ámbito de un producto. Un producto sin catálogo devuelve `404` con `IDE-1053`. | [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 saber qué dimensiones acepta un producto en `scope`, lee su catálogo de ámbito. Cada dimensión tiene un `name` y los indicadores `required`, `multi` y `explicit`.

## Los campos del socio

***

| Campo | Obligatorio al crear | Significado |
| - | - | - |
| `displayName` | Sí | El nombre del socio, de 1 a 100 caracteres. Una letra con tilde, y cualquier otro carácter fuera del ASCII simple, cuenta como dos o más. Un nombre más largo se rechaza. El nombre es único en tu tenant, y la comparación ignora mayúsculas y minúsculas. |
| `permissions` | Sí | Una o más entradas, cada una con sus propios `product`, `resources` y `actions`. Cada entrada necesita al menos un recurso y una acción. |
| `scope` | Sí, para cada producto cuyo catálogo de ámbito declara dimensiones | Una entrada por restricción: `product`, `field` y `values`. `field` es el `name` de una dimensión del catálogo de ámbito del producto. |
| `ipAllowlist` | No | La lista de IP permitidas propia del socio. Cada entrada tiene un `cidr` y una `description` opcional de hasta 255 caracteres. |
| `validFrom` | No | El inicio de la ventana de validez, como un instante RFC 3339. Si falta, no hay fecha de inicio. |
| `validUntil` | No | El fin de la ventana de validez, como un instante RFC 3339. Si falta, no hay fecha de fin. |
| `state` | No se acepta | `active` o `suspended`. Todo socio nuevo es `active`. Lo cambias con `PATCH`. |

La respuesta también trae `id`, `applicationsCount`, `createdAt` y `updatedAt`.

Reglas que se aplican a los campos:

* `product` es el slug de producto que trae el catálogo de ámbito del producto, como `plugin-br-pix-jd`.
* Escribe `actions` en minúsculas, como las devuelve [Consultar el techo de socios de un producto](https://docs.lerian.studio/es/reference/platform/access-manager/retrieve-the-partner-ceiling-of-a-product.md): verbos HTTP como `get`, `post`, `patch` y `delete` en Midaz, Pix JD y Reporter, y acciones nombradas como `read` y `activate` en Flowker.
* `resources` × `actions` es un producto cartesiano completo. Para dar acciones distintas sobre recursos distintos, envía más de una entrada para el mismo producto.
* Access Manager rechaza el comodín `*` en `resources`, `actions` y `values`. Lista los elementos.
* Un producto en `scope` también debe estar en `permissions`.
* Un producto cuyo catálogo de ámbito declara dimensiones necesita al menos una entrada de ámbito en cada socio con permisos en ese producto. La excepción es una entrada de permisos que tiene solo permisos que el producto reserva para socios: no necesita ámbito, y aplica a todo el tenant. Sin una entrada de ámbito, Access Manager rechaza crear o cambiar el socio, con `IDE-1060`. Un socio guardado sin ella antes de esta regla se rechaza con `403` en cada solicitud a ese producto, hasta que agregues una entrada de ámbito.
* Una dimensión que el catálogo marca como `required` necesita una entrada de ámbito en cada socio con permisos en ese producto, o Access Manager rechaza con `IDE-0001`. Una dimensión sin `multi` acepta solo un valor, o Access Manager rechaza con `IDE-0002`.
* Para una dimensión que el catálogo marca como `explicit`, un permiso sobre la colección de esa dimensión necesita una entrada de ámbito que liste sus IDs. Sin ella, Access Manager rechaza con `IDE-1052`. El socio alcanza solo los IDs que listas.
* Access Manager no verifica que los `values` existan en el producto. Usa los identificadores que devuelve la propia API del producto.
* `state` es `active` o `suspended`, nunca `expired`. Después de `validUntil`, una lectura sigue devolviendo el estado guardado.
* Después de la fecha `validUntil` del socio, Access Manager rechaza sus solicitudes, también con un token que ya tiene, y rechaza tokens nuevos.

## El campo de lista de IP permitidas

***

`ipAllowlist` tiene tres significados en `PATCH`:

| Envías | Qué pasa |
| - | - |
| El campo omitido | La lista guardada queda como está. |
| `null` | La lista propia del socio se elimina. El socio vuelve a la lista de tu tenant. |
| Una lista de entradas | Estas entradas reemplazan la lista propia del socio. |
| `[]` | Rechazado con `IDE-1048`. |

Cada entrada de la lista propia del socio debe ser un rango IPv4 de `/24` o más estrecho, o un rango IPv6 de `/48` o más estrecho. Una entrada más amplia se rechaza con `IDE-1052`. Una entrada que el socio ya tiene no se verifica de nuevo.

En `POST`, omite el campo o envía `null` para usar la lista de tu tenant.

Cuando un socio tiene su propia lista de IP, esa lista reemplaza la lista de IP del tenant para las solicitudes del socio.

`validFrom` y `validUntil` funcionan de forma parecida en `PATCH`. Omite un límite para conservarlo, envía un instante para definirlo o envía `null` para quitarlo.

## Ejemplos

***

Reemplaza los marcadores por la URL base de tu Identity API, tu bearer token e identificadores de tu propio despliegue.

```bash Create a partner theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/partners" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Partner A",
    "permissions": [
      { "product": "plugin-br-pix-jd", "resources": ["entries"], "actions": ["get", "post"] }
    ],
    "scope": [
      { "product": "plugin-br-pix-jd", "field": "participantId", "values": ["12345678"] }
    ],
    "ipAllowlist": [
      { "cidr": "203.0.113.10", "description": "Partner A gateway" }
    ]
  }'
```

```bash Create its application theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/applications" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "plugin-br-pix-jd",
    "description": "Partner A access to Pix JD",
    "partnerId": "'"${PARTNER_ID}"'"
  }'
```

```bash Suspend it theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "suspended" }'
```

```bash Go back to the tenant's IP list theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "ipAllowlist": null }'
```

## Crea las aplicaciones del socio

***

Un socio llama a un producto con una aplicación que le pertenece. Después de crear el socio:

1. Crea una aplicación con [Crear una aplicación](https://docs.lerian.studio/es/reference/platform/access-manager/create-an-application.md). Envía el `id` del socio en `partnerId` y el slug del producto en `target`, como `plugin-br-pix-jd`.
2. La Identity API devuelve el client secret solo en la respuesta que crea la aplicación. Guárdalo en ese momento. Si pierdes el secret, elimina la aplicación y crea una nueva.
3. Envía el client ID y el secret al socio por un canal seguro.
4. Repite los pasos 1 a 3 para cada producto al que llama el socio. Crea una aplicación por producto.

Para listar las aplicaciones de un socio, envía su `id` en el parámetro de consulta `partnerId` de [Listar aplicaciones](https://docs.lerian.studio/es/reference/platform/access-manager/list-applications.md). Si `partnerId` no nombra un socio de tu tenant, las dos operaciones devuelven `404` con `IDE-1046`.

## Cambia, suspende o elimina un socio

***

* En `PATCH`, envía solo los campos que cambias. Una lista `permissions` o `scope` reemplaza la lista guardada completa. Lee primero el socio y después envía la nueva lista completa.
* Para suspender un socio, envía `"state": "suspended"`. Para reactivarlo, envía `"state": "active"`.
* Suspender un socio en Access Manager detiene su acceso, incluidos los tokens que ya tiene. Reactivar el socio dentro de su ventana de validez restaura el acceso con las mismas credenciales.
* [Cuándo se aplica un cambio](https://docs.lerian.studio/es/platform/access-manager/features/partners/overview#when-a-change-applies) indica cuándo el socio ve un cambio de permisos o de ámbito.
* No puedes eliminar un socio que todavía tiene aplicaciones. La respuesta es `409` con `IDE-1049`, y su lista `errors` nombra cada aplicación que bloquea, con su client ID. Elimina primero esas aplicaciones.
* Eliminar una aplicación hace que sus tokens dejen de funcionar.

## Códigos de error

***

Errores en las operaciones de socios:

| Código | Estado | Título | Cuándo |
| - | - | - | - |
| `IDE-0001` | 400 | Missing Fields in Request | Falta un campo obligatorio, o el ámbito no tiene una entrada para una dimensión que el producto exige. |
| `IDE-0002` | 400 | Invalid Field Type | Una dimensión que acepta un valor recibió varios. |
| `IDE-0036` | 400 | Invalid IP Allowlist Entry | Una entrada de `ipAllowlist` no es una dirección ni un rango CIDR válido. |
| `IDE-1040` | 409 | Partner Display Name Already Exists | Otro socio de tu tenant tiene el mismo `displayName`. |
| `IDE-1042` | 400 | Unknown Scope Field | Un `field` de ámbito no está en el catálogo de ámbito del producto, o el producto no tiene catálogo de ámbito. |
| `IDE-1043` | 400 | Permission Above Product Ceiling | Un permiso está por encima del techo del producto en tu tenant. |
| `IDE-1044` | 400 | Scope Without Permissions | Un producto está en `scope` pero no en `permissions`. |
| `IDE-1045` | 400 | Invalid Validity Window | `validUntil` no es posterior a `validFrom`. |
| `IDE-1046` | 404 | Partner Not Found | No existe un socio con este `id` en tu tenant. |
| `IDE-1047` | 400 | Wildcard Not Allowed | `*` está en `resources`, `actions` o `values`. |
| `IDE-1048` | 400 | Empty IP Allowlist | `ipAllowlist` es un arreglo vacío. |
| `IDE-1049` | 409 | Partner Has Applications | El socio todavía tiene aplicaciones, así que no se puede eliminar. |
| `IDE-1050` | 400 | Duplicate IP Allowlist Entry | La misma red aparece dos veces en `ipAllowlist`. |
| `IDE-1052` | 400 | Partner Rejected | El proveedor de identidad rechazó el socio por otro motivo, por ejemplo un permiso sobre la colección de una dimensión `explicit` sin sus IDs, o un permiso que ninguna solicitud del socio puede usar dentro de su ámbito. El mensaje repite ese motivo. |
| `IDE-1053` | 404 | Scope Catalog Not Found | El producto no publicó un catálogo de ámbito. |
| `IDE-1054` | 400 | Product Not Ready For Partners | Un permiso nombra un producto que no publicó su catálogo de ámbito. |
| `IDE-1055` | 400 | Product Not Opted In To Partners | Un permiso nombra un producto cuyo catálogo de ámbito no acepta socios. |
| `IDE-1056` | 400 | Partner Write Exceeds Its Scope | Un permiso de escritura actúa en un nivel más amplio que el ámbito del socio. |
| `IDE-1057` | 400 | Partner Read Rejected | El proveedor de identidad rechazó la lectura del techo, por ejemplo para un producto desconocido. |
| `IDE-1060` | 400 | Partner Product Without Scope | Un permiso que el producto no reserva para socios nombra un producto cuyo catálogo de ámbito declara dimensiones, y `scope` no tiene una entrada para ese producto. En `PATCH`, quitar la última entrada de ámbito de un producto que conserva sus permisos también se rechaza. |

Para cualquier otro código, consulta la [lista de errores de Access Manager](https://docs.lerian.studio/es/reference/platform/access-manager/access-manager-error-list.md).


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