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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Gestión de organizaciones B2B

> Aprende a gestionar grupos de cuentas, cuentas y usuarios para alianzas white-label.

Yuno ofrece un conjunto de APIs de gestión de organizaciones B2B diseñadas para plataformas y socios white-label que necesitan gestionar varias suborganizaciones y sus usuarios. Estas APIs te permiten automatizar el onboarding de tus comercios mediante la creación de una estructura jerárquica de grupos de cuentas, cuentas y usuarios.

> [!NOTE]
>
> **Requisitos previos**
> Para usar estas APIs, tu organización debe tener la propiedad **whitelabel** habilitada en el Dashboard de Yuno. Contacta a tu gerente de cuenta de Yuno para habilitar esta función.

## Flujo principal de gestión

Sigue estos pasos para configurar un nuevo entorno de comercio.

**1. Crea un grupo de cuentas**

El grupo de cuentas actúa como la entidad principal de tu comercio y centraliza la gestión de las cuentas relacionadas. Usa el endpoint [Create Account Group](https://docs.y.uno/reference/organizations/create-account-group.md) para inicializar este grupo.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
  --url https://api-sandbox.y.uno/v1/organizations/account-groups \
  --header 'PRIVATE-SECRET-KEY: <YOUR_PRIVATE_SECRET_KEY>' \
  --header 'PUBLIC-API-KEY: <YOUR_PUBLIC_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Payments",
    "merchant_id": "acme_001"
  }'
```

**Salida y siguientes pasos**: La respuesta incluirá un `id` único para el grupo de cuentas. Guarda este ID, ya que lo necesitarás para crear cuentas de comercio específicas en el siguiente paso.

**2. Crea una cuenta**

Dentro del grupo de cuentas recién creado, puedes crear una o más cuentas. Esta estructura te permite separar la lógica de negocio, las regiones o las líneas de negocio de un mismo comercio. Usa el endpoint [Create Account](https://docs.y.uno/reference/organizations/create-account.md).

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
  --url https://api-sandbox.y.uno/v1/organizations/account-groups/{account_group_id}/accounts \
  --header 'PRIVATE-SECRET-KEY: <YOUR_PRIVATE_SECRET_KEY>' \
  --header 'PUBLIC-API-KEY: <YOUR_PUBLIC_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Production"
  }'
```

**Salida y siguientes pasos**: Recibirás un `id` para la cuenta de comercio. Este ID se usa para acotar pagos, sesiones y configuraciones específicamente a este entorno de comercio.

**3. Crea un usuario y asigna permisos**

Por último, crea un usuario real y otórgale acceso a la cuenta o a todo el grupo de cuentas. Asignar roles (como `merchant-admin`) garantiza que el usuario tenga los permisos necesarios para gestionar el Dashboard del comercio. Usa el endpoint [Create User](https://docs.y.uno/reference/organizations/create-user.md).

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
  --url https://api-sandbox.y.uno/v1/organizations/users \
  --header 'PRIVATE-SECRET-KEY: <YOUR_PRIVATE_SECRET_KEY>' \
  --header 'PUBLIC-API-KEY: <YOUR_PUBLIC_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "admin@acmepay.com",
    "first_name": "John",
    "last_name": "Doe",
    "account_group_permissions": [
      {
        "account_group_id": "{account_group_id}",
        "role_id": "merchant-admin"
      }
    ]
  }'
```

**Salida y siguientes pasos**: El usuario se creará en el sistema. Para permitirle iniciar sesión en tu portal whitelabel, usa el endpoint [Authenticate Whitelabel User](https://docs.y.uno/reference/organizations/authenticate-whitelabel-user.md) para generar un token de acceso seguro.

## Anidar grupos de cuentas

Los grupos de cuentas se pueden anidar para reflejar cómo está estructurada tu organización: un grupo puede contener cuentas y subgrupos, y un subgrupo puede contener grupos propios. Cada grupo tiene como máximo un padre, y un grupo no puede anidarse dentro de su propio subárbol.

Un grupo siempre se crea como raíz. Para anidarlo, define `parent_code` en [Update Account Group](https://docs.y.uno/reference/organizations/update-account-group.md); envía `parent_code: null` para desvincularlo y volver a convertirlo en raíz. Cada respuesta de grupo de cuentas informa el padre en `parent_code` (`null` para una raíz).

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request PATCH \
  --url https://api-sandbox.y.uno/v1/organizations/account-groups/{account_group_id} \
  --header 'PRIVATE-SECRET-KEY: <YOUR_PRIVATE_SECRET_KEY>' \
  --header 'PUBLIC-API-KEY: <YOUR_PUBLIC_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_code": "{parent_account_group_id}"
  }'
```

El anidamiento es solo estructural: mover un grupo no concede ni revoca nada, por lo que los permisos de usuario existentes no cambian. Un grupo que aún tiene subgrupos o cuentas no se puede eliminar: muévelos o [quítalos](https://docs.y.uno/reference/organizations/remove-account-from-group.md) primero.

## Gestionar proveedores mediante la API

Una vez que tus comercios pueden iniciar sesión, la pestaña **Providers** de tu Dashboard white-label decide a qué proveedores de pago pueden conectarse y qué leen tus usuarios mientras lo hacen. Esa capa se puede configurar mediante la API: qué proveedores ofreces, y el nombre, las instrucciones de conexión, el enlace de documentación y el logotipo que se muestran para cada uno.

Consulta la [Descripción general de proveedores white-label](https://docs.y.uno/reference/organizations/whitelabel/overview.md) para ver el contrato común y los endpoints.

## Disponibilidad por entorno

Las APIs de gestión de organizaciones B2B están disponibles en los entornos **Sandbox** y **Producción**. Para más información sobre cómo gestionar tus claves de API y URL base, visita la página de [Entornos](https://docs.y.uno/es/docs/using-yuno/environments.md).

## Siguientes pasos

Explora la referencia completa de la API para ver opciones de gestión más avanzadas:

* [Referencia de grupos de cuentas](https://docs.y.uno/reference/organizations/list-account-groups.md)
* [Referencia de cuentas](https://docs.y.uno/reference/organizations/list-accounts.md)
* [Referencia de usuarios](https://docs.y.uno/reference/organizations/list-users.md)
* [Referencia de permisos de usuario](https://docs.y.uno/reference/organizations/retrieve-user-account-permissions.md)
* [Referencia de proveedores white-label](https://docs.y.uno/reference/organizations/whitelabel/overview.md)


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