## Visión general

La **API de Plataforma** opera **por encima** de las cuentas: permite crear y gestionar **cuentas**,
**usuarios**, **vinculos usuario-cuenta** y **agent bots** de forma programatica. Todo vive bajo un
**Platform App** — una aplicacion de plataforma que el operador crea y que recibe su propio token.

Diferencia con la **API REST de la cuenta**:

- La **API REST** trabaja **dentro** de una sola cuenta (contactos, conversaciones, mensajes) y usa el
  token de un usuario/agente de esa cuenta.
- La **API de Plataforma** trabaja **entre cuentas** (aprovisionamiento y ciclo de vida) y usa el
  token del Platform App. Sus endpoints viven bajo el prefijo `/platform/api/v1`.

Un Platform App solo ve y modifica los objetos de su lista de **permisibles** (las cuentas, usuarios y
bots que creo o que se le asociaron).

## Requisitos previos

- Un **Platform App** creado por el operador (Super Admin -> Platform Apps).
- El **token de acceso** de ese Platform App (generado junto con el app).
- El token debe circular **solo en el backend** del operador — nunca en el front-end.

## Paso a paso

1. **El operador crea un Platform App** en Super Admin -> Platform Apps. Al guardar, la plataforma
   genera un token de acceso vinculado al app.
2. **Autentica** cada llamada incluyendo la cabecera `api_access_token` con el token del Platform App.
   Si el token no pertenece a un Platform App, la respuesta es `401 Invalid access_token`.
3. **Crea una cuenta**:

   ```
   POST /platform/api/v1/accounts
   api_access_token: <token-de-plataforma>
   Content-Type: application/json

   { "name": "Cliente XPTO", "locale": "es", "support_email": "soporte@cliente.com" }
   ```

   La cuenta creada se agrega automaticamente a los permisibles del app.
4. **Crea un usuario**:

   ```
   POST /platform/api/v1/users
   { "name": "Maria", "email": "maria@cliente.com", "password": "<contrasena-fuerte>" }
   ```

   El usuario tambien entra en los permisibles del app. Si ya existe un usuario con ese correo, la
   plataforma reutiliza el usuario existente.
5. **Vincula usuario y cuenta** (`account_user`) con un rol:

   ```
   POST /platform/api/v1/accounts/<account_id>/account_users
   { "user_id": <user_id>, "role": "administrator" }
   ```

   Usa `administrator` o `agent` en el campo `role`.
6. **Aprovisiona agent bots**:

   ```
   POST /platform/api/v1/agent_bots
   { "name": "Bot de Ventas", "account_id": <account_id>, "outgoing_url": "https://mi-bot/webhook" }
   ```

Endpoints complementarios: `GET/PATCH/DELETE /platform/api/v1/accounts/:id`, `GET :id` y `DELETE :id`
de usuarios, `GET .../account_users` (listar), `DELETE .../account_users` (quitar vinculo),
`GET :id/login` (genera un enlace de acceso SSO para el usuario) y `POST :id/token`.

## Configuracion y opciones

- **Objetos permisibles**: cada Platform App mantiene una lista de cuentas, usuarios y agent bots que
  puede gestionar. Los objetos que el app crea entran en esa lista automaticamente.
- **Alcance del token**: el token del Platform App solo actua sobre los permisibles del app — no llega
  a cuentas/usuarios de otros apps ni a los datos internos de una cuenta (para eso, usa la API REST de
  la cuenta).
- **Parametros de cuenta**: `name`, `locale`, `domain`, `support_email`, `status`, ademas de
  `features`, `limits` y `custom_attributes`.
- **Parametros de usuario**: `name`, `display_name`, `email`, `password` y `custom_attributes`.

## Casos de uso

- **Onboarding multicliente / reventa**: crear una cuenta por cliente y poblar usuarios en masa.
- **Aprovisionamiento estilo SSO**: crear el usuario y generar el enlace de acceso (`GET :id/login`)
  para llevar al usuario directo al panel sin contrasena manual.
- **Ciclo de vida automatizado**: crear, actualizar y desactivar cuentas y vinculos desde tu propio
  sistema (por ejemplo, al completar o cancelar una suscripcion).

## Consejos, limites y buenas practicas

- Manten el token del Platform App **solo en el backend** del operador. Tiene poder de
  aprovisionamiento — nunca lo expongas en el front-end ni en apps cliente.
- Trabaja con **permisos restringidos**: el app solo debe tocar los objetos que el mismo creo.
- La eliminacion de cuentas y usuarios es **asincrona** (encolada) — una respuesta `200` indica que la
  eliminacion fue agendada, no completada en el mismo instante.
- Maneja la **idempotencia**: crear un usuario con un correo ya existente reutiliza el registro; crear
  el mismo vinculo cuenta-usuario no lo duplica.

## Solucion de problemas

- **401 Invalid access_token**: el token no pertenece a un Platform App (o falta/es incorrecto en la
  cabecera `api_access_token`).
- **401 Non permissible resource**: el objeto (cuenta/usuario/bot) no esta en la lista de permisibles
  del app — estas intentando cambiar algo que el app no gestiona.
- **404**: el `id` indicado no existe.

## Ver tambien

- [API REST, tokens y webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-es)
- [Referencia de API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-es)
- [Vision general de API & Desarrolladores](/hc/ajuda/articles/api-developers-overview-es)