> ## 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, emite sus credenciales y maneja los códigos de error que devuelven las operaciones.

<Warning>
  Esta funcionalidad está disponible solo en Staging para pruebas y todavía no está disponible en Producción.
</Warning>

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

## 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](/es/reference/platform/access-manager/list-partners) |
| `POST /v1/partners` | Crea un socio. Devuelve `201` con el nuevo socio y su `id`. No se crea ninguna credencial. | [Crear un socio](/es/reference/platform/access-manager/create-a-partner) |
| `GET /v1/partners/{id}` | Devuelve un socio completo. | [Consultar un socio](/es/reference/platform/access-manager/retrieve-a-partner) |
| `PATCH /v1/partners/{id}` | Cambia un socio: su acceso, su ventana de validez, su lista de IP permitidas o su estado. | [Actualizar un socio](/es/reference/platform/access-manager/update-a-partner) |
| `DELETE /v1/partners/{id}` | Elimina un socio sin aplicaciones. Devuelve `204`. | [Eliminar un socio](/es/reference/platform/access-manager/delete-a-partner) |
| `GET /v1/partners/ceiling` | Devuelve lo máximo que puedes dar a un socio en un producto. | — |

Cada operación necesita un bearer token con el permiso `partners`. Access Manager identifica tu tenant a partir del token. No hay un campo de tenant en la ruta ni en el cuerpo, y nunca ves los socios de otro tenant.

Para saber qué restricciones acepta un producto, lee su catálogo de ámbito con `GET /v1/scope-catalog/{product}`.

## Los campos del socio

***

| Campo | Obligatorio al crear | Significado |
| - | - | - |
| `displayName` | Sí | El nombre del socio, de 1 a 128 caracteres, único en tu tenant. |
| `permissions` | Sí | Una o más entradas por producto, cada una con sus propios `product`, `resources` y `actions`. Cada entrada necesita al menos un recurso y una acción. |
| `scope` | No | Una entrada por restricción: `product`, `field` y `values`. `field` es una dimensión del catálogo de ámbito del producto, como `organizationId` o `ledgerId`. |
| `ipAllowlist` | No | La lista de IP permitidas propia del socio. Cada entrada tiene un `cidr` y una `description` opcional. |
| `validFrom` | No | El inicio de la ventana de validez, como un instante RFC 3339. Si falta, significa "válido ahora". |
| `validUntil` | No | El fin de la ventana de validez, como un instante RFC 3339. Si falta, significa "sin fecha de fin". |
| `state` | No | `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 un slug de producto de [Listar aplicaciones disponibles](/es/reference/platform/access-manager/list-available-applications), como `midaz`.
* `actions` son verbos HTTP en minúsculas: `get`, `post`, `put`, `patch`, `delete`. `head` viene con `get`.
* El comodín `*` no se acepta en `resources` ni en `actions`. Lista los valores.
* Un producto en `scope` también debe estar en `permissions`.
* Midaz exige un `organizationId` para cada socio con permisos en Midaz. Una dimensión que el catálogo no marca como de varios valores acepta un solo valor.
* Access Manager no verifica que los `values` existan en el producto. Usa los IDs que devuelve la propia API del producto.
* `state` nunca muestra `expired`. Después de `validUntil`, el socio sigue en `active`, con un `validUntil` en el pasado.

## El campo de lista de IP permitidas

***

`ipAllowlist` tiene tres significados en `PATCH`, y no son iguales:

| 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 usar la lista de tu tenant. |
| Una lista de entradas | La lista propia del socio se reemplaza por estas entradas. |
| `[]` | Rechazado con `IDE-1048`. Para bloquear un socio por completo, suspéndelo. |

En `POST`, omite el campo o envía `null` para usar la lista de tu tenant. La lista propia de un socio reemplaza la lista de tu tenant. No se suma a ella.

`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, un bearer token con el permiso `partners` e IDs de tu propia organización de Midaz.

<CodeGroup>
  ```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": "midaz", "resources": ["accounts"], "actions": ["get", "post", "patch"] },
        { "product": "midaz", "resources": ["transactions"], "actions": ["get", "post"] }
      ],
      "scope": [
        { "product": "midaz", "field": "organizationId", "values": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"] },
        { "product": "midaz", "field": "ledgerId", "values": ["9c858901-8a57-4791-81fe-4a34d4dd8ab5"] }
      ],
      "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 '{
      "name": "midaz",
      "description": "Partner A access to Midaz",
      "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 }'
  ```
</CodeGroup>

## Emite las credenciales del socio

***

Un socio sin aplicación no puede llamar a nada. Después de crear el socio:

1. Crea una aplicación con [Crear una aplicación](/es/reference/platform/access-manager/create-an-application) y envía el `id` del socio en `partnerId`. Define `name` con el slug del producto, como `midaz`. Crea una aplicación por producto.
2. Copia `clientId` y `clientSecret` de la respuesta. La respuesta es la única vez que se muestra el secreto.
3. Envía los dos valores al socio por un canal seguro.

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

## 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"`.
* Un cambio se aplica desde la siguiente solicitud del socio. Una suspensión también rechaza los tokens que el socio ya tiene.
* 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.

## 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 in Request | Varios valores en una dimensión de un solo valor, o un `state` distinto de `active` o `suspended`. |
| `IDE-0036` | 400 | Invalid IP Allowlist Entry | Una entrada de `ipAllowlist` no es una dirección o 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. |
| `IDE-1043` | 400 | Permission Above Product Ceiling | Un permiso está por encima de lo que tiene el rol de editor 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` o en `actions`. |
| `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-1054` | 400 | Product Not Ready For Partners | El producto todavía no publicó su catálogo de ámbito. |
| `IDE-1055` | 400 | Product Not Opted In To Partners | El producto tiene un catálogo de ámbito pero no acepta socios. |
| `IDE-1056` | 400 | Partner Write Exceeds Its Scope | Una escritura actúa en un nivel más amplio que el ámbito del socio, como crear ledgers para un socio restringido a un ledger. |

Errores que recibe el propio sistema del socio:

| Código | Estado | Cuándo |
| - | - | - |
| `AUT-0021` | 403 | La solicitud viene de una dirección fuera de la lista de IP permitidas del socio. |
| `AUT-1009` | 401 | El socio está suspendido. Se devuelve en las solicitudes a los productos y en los pedidos de token nuevo. |
| `AUT-1010` | 401 | El socio está fuera de su ventana de validez. Se devuelve en las solicitudes a los productos y en los pedidos de token nuevo. |
| Ninguno | 403 | Los permisos o el ámbito no permiten la solicitud. El producto no dice cuál de los dos. |

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


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