API de Plataforma (aprovisionamiento multicuenta)

Abrir en

Ver como Markdown

Abrir en ChatGPT Abrir en Claude

Conversa Labs

Última actualización el Jul 27, 2026

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

El operador crea un Platform App en Super Admin -> Platform Apps. Al guardar, la plataforma genera un token de acceso vinculado al app.
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.

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.

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.

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.

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.