Saltar al contenido

Apartado 3 de 15 · Empezar

Lo que el token abre, y lo que no

Qué rutas abre un token estricto de Chatendo según sus permisos, qué pasa con los tokens heredados y cómo se aíslan los datos entre cuentas.

Revisado el API 1.158.0 10 min de lectura

En esta página (3)
  1. Los permisos, uno por uno
  2. El token nunca puede más que la persona que lo creó
  3. Varias cuentas a la vez

Los tokens que se crean en Desarrolladores → Tokens de API son estrictos: solo entran en las rutas que declaran un permiso que les hayas marcado. Una ruta que no declara ninguno es del panel, y a un token estricto le queda cerrada.

Medido el 27-09-2026 en el entorno de pruebas, con el mismo código que corre en producción, con un token estricto que tiene solamente contacts:read:

Ruta Respuesta
GET /contacts · GET /tags 200 — tiene el permiso
GET /conversations 403 — le falta conversations:read
GET /analytics 403 — le falta analytics:read
GET /webhook-endpoints 403 — le falta webhooks:manage
GET /tenant/settings 403 — le falta settings:read
GET /channels · GET /imports/whatsapp 403 — le falta channels:read
GET /users 403 — le falta team:read
GET /contacts/{id}/timeline 403 — junta mensajes y notas: pide además conversations:read y notes:read
GET /notifications 403 — es del panel: ningún permiso la abre

Cada 403 dice en required qué permiso falta (vacío si la ruta es del panel). Tres rutas se abren a cualquier token: GET /auth/me, POST /auth/logout y GET /novedades.

Los tokens de antes siguen como estaban. En la lista salen con el distintivo Heredado: las rutas que declaran permiso se lo piden igual, pero las que no declaran ninguno las atraviesan (con uno así, GET /tenant/settings da 200). Para que uno sea estricto, crea otro con los permisos que usa, cámbialo en tu programa y revoca el viejo.

Aun así: un token por integración, permisos mínimos, y revocar en cuanto una integración deja de usarse. Entre cuentas no pasa nada, ni con un token estricto ni con uno heredado: está probado con dos, justo abajo.

Los permisos, uno por uno

Estos son los permisos de un token (los mismos que salen en Desarrolladores → Tokens de API, y la lista viva la da GET /tokens/abilities). La columna Se marca en Ajustes dice si ese permiso se puede dar desde el panel: los que llevan No hacen cosas que un programa de fuera no debe hacer por su cuenta (cerrar o asignar conversaciones, lanzar campañas, conectar canales, gestionar el equipo…) y un token creado allí no los tiene: la ruta que los pide da 403 TOKEN_SCOPE_DENIED. Si tu integración necesita uno, se pide y se acuña desde el servidor.

Permiso Qué abre Se marca en Ajustes
contacts:read Leer contactos. Ver la lista y la ficha de contactos, sus etiquetas, campos y pedidos. Sí
contacts:write Crear y editar contactos. Dar de alta, cambiar, fusionar, importar y borrar contactos y sus etiquetas. Sí
conversations:read Leer conversaciones. Ver la bandeja, los mensajes, los adjuntos y el estado de cada conversación. Sí
conversations:write Gestionar conversaciones. Asignar, reclamar, cerrar, reabrir, marcar como leída, borrar y mover de etapa conversaciones; guardar su external_id; abrir una conversación por teléfono. No
messages:send Enviar mensajes. Mandar mensajes, adjuntos y enlaces a los clientes por sus canales, programar mensajes y escribir a un teléfono que aún no tiene conversación. Sí
notes:read Leer notas internas. Ver las notas que el equipo deja en contactos y conversaciones. Sí
notes:write Escribir notas internas. Crear, cambiar y borrar notas internas de contactos y conversaciones. Sí
appointments:read Leer la agenda. Ver citas, huecos libres y recordatorios. Sí
appointments:write Gestionar la agenda. Dar, mover y anular citas y recordatorios. Sí
campaigns:read Leer campañas. Ver las campañas y su informe de envío, y a cuántos llegarán. Sí
campaigns:write Gestionar campañas. Crear, lanzar, pausar y cancelar campañas: son envíos masivos de verdad. No
analytics:read Leer estadísticas. Ver cifras de la bandeja, del equipo, de satisfacción y del uso de la IA. Sí
webhooks:manage Gestionar avisos (webhooks). Dar de alta, cambiar y borrar las direcciones a las que avisamos, ver sus entregas y reenviar las fallidas. Sí
events:read Leer eventos. Consultar el diario de eventos de los últimos 7 días (GET /events). Sí
channels:read Leer canales. Ver los canales, su menú del bot, plantillas, catálogo y quién los atiende. Sí
channels:manage Gestionar canales. Conectar, cambiar y borrar canales (también un buzón de correo), su menú del bot, plantillas, catálogo e importaciones. No
settings:read Leer ajustes. Ver los ajustes de la cuenta, del agente IA, respuestas rápidas y etiquetas de chat. Sí
settings:write Cambiar ajustes. Cambiar los ajustes de la cuenta, el agente IA y su material, el cupo de IA y los avisos internos. Sí
team:read Leer el equipo. Ver los usuarios, equipos, invitaciones y el chat interno. Sí
team:write Gestionar el equipo. Dar de alta y baja usuarios, invitar, cambiar roles, equipos, inicio de sesión único y chat interno. No
apps:manage Gestionar apps. Activar, configurar y usar las apps de la cuenta. No
opportunities:read Leer oportunidades. Ver las oportunidades, su historial, el tablero del embudo y los motivos de pérdida, y exportarlas (app «Embudo de ventas»). Sí
opportunities:write Gestionar oportunidades. Crear, editar, mover de etapa, ganar, perder, reabrir y borrar oportunidades. No escribe a ningún cliente. Sí
tasks:read Leer tareas. Ver las tareas, sus contadores y exportarlas (app «Tareas»). Nunca escribe a un cliente. Sí
tasks:write Gestionar tareas. Crear, editar, completar, cancelar, reabrir, posponer y borrar tareas, y registrar actividades. Nunca escribe a un cliente. Sí
companies:read Leer empresas. Ver las empresas, sus personas, oportunidades, tareas e historia, los posibles duplicados y los sectores (app «Empresas»). Sí
companies:write Gestionar empresas. Crear, editar, borrar, importar y fusionar empresas, y vincular y desvincular personas. Sí
catalog:read Leer el catálogo. Ver los productos y servicios, sus categorías, unidades y ajustes de precio, y exportarlos (app «Catálogo»). Sí
catalog:write Gestionar el catálogo. Dar de alta, cambiar, archivar, borrar e importar productos y cambiar las listas de categorías y unidades. Sí
quotes:read Leer presupuestos. Ver los presupuestos, sus líneas, su historial y sus PDF, y exportarlos (app «Presupuestos»). Sí
quotes:write Gestionar presupuestos. Hacer, cambiar, emitir, anular y borrar presupuestos, compartir su enlace y enviarlos por WhatsApp a quien los pidió. Sí
sales-reports:read Leer informes de venta. Ver los informes de venta (embudo, resultados, previsión, por origen y actividad) y descargarlos en CSV. Sí
leads:read Leer captación. Ver las fuentes, los formularios, los leads recibidos y el registro de errores (app «Captación»). Sí
leads:write Gestionar captación. Encender fuentes, crear y editar formularios, rotar su clave, reprocesar leads y reintentar errores. Sí
correo-marketing:read Leer marketing por correo. Ver campañas, informes, suscriptores, dominios y ajustes de la app «Marketing por correo». Sí
correo-marketing:write Gestionar marketing por correo. Crear y editar campañas, suscriptores, plantillas, dominios y remitentes, y enviar, programar, pausar o cancelar campañas a tus clientes. Sí

Hay más permisos que no son de integraciones de uso general: los de las llamadas de WhatsApp (calls:initiate, calls:read, que tampoco se ofrecen) y los de integraciones hechas a medida para una cuenta, de LinkedIn (linkedin:*), de la publicidad y de la plataforma. Una app apagada en tu cuenta cierra sus rutas aunque el token tenga el permiso: 403 APP_INACTIVE.

El token nunca puede más que la persona que lo creó

Desde la versión 1.32 (17-10-2026) una cuenta tiene once roles de serie —los seis de siempre (Propietario, Administrador, Supervisor, Agente, Solo lectura y Auditor) y cinco pensados para un equipo comercial: Comercial, Jefe de ventas, Marketing, Soporte y Finanzas— y puede crear roles a medida eligiendo, módulo a módulo, qué se hace y sobre qué. Un token actúa en nombre de quien lo creó, y cada petición pasa dos puertas, en este orden:

  1. El permiso del token (contacts:read, conversations:write…). Si falta: 403 TOKEN_SCOPE_DENIED, con el permiso en required.
  2. El rol que esa persona tiene hoy. Si su rol no deja hacer eso: 403 FORBIDDEN, la misma respuesta que recibiría ella en el panel.

O sea: lo que puede un token es lo que tienen a la vez sus permisos y el rol de quien lo creó. Si a esa persona le cambian el rol, sus tokens lo notan en la petición siguiente; no hay que crearlos otra vez. El alcance del rol también cuenta: con un token creado por alguien con el rol Comercial, las listas de conversaciones y contactos traen solo lo suyo (lo asignado a esa persona y lo nuevo sin asignar de sus canales), y el id de una conversación ajena da 404.

Para los seis roles de siempre esto no cambia nada: está comprobado ruta por ruta (las 590) que cada uno puede exactamente lo mismo que antes. Lo que cambia es que, si el token de tu integración lo creó alguien con un rol de los nuevos o a medida, conviene mirar qué le deja. Para saberlo sin probar ruta por ruta, cualquier token puede leer lo suyo:

Terminal
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
     -H "Accept-Language: es" https://app.chatendo.app/api/v1/me/permissions

Respuesta de un token con contacts:read, conversations:read y campaigns:read creado por una persona con el rol Comercial (captura de una prueba automática sobre el código de la 1.32, recortada):

JSON
{
  "user": {"id": 1, "name": "Integracion ERP", "role": "comercial", "custom_role": null},
  "role": {"id": null, "slug": "comercial", "name": "Comercial"},
  "permissions": [
    {"key": "conversaciones.ver", "module": "conversaciones", "scope": "propios", "in_effect": true},
    {"key": "contactos.ver", "module": "contactos", "scope": "propios", "in_effect": true}
  ],
  "summary": {"headline": "Integracion ERP puede usar 9 de los 21 módulos de la cuenta.", "lines": ["…"], "hidden_modules": ["…"]},
  "token": {
    "id": 1,
    "abilities": ["contacts:read", "conversations:read", "campaigns:read"],
    "effective_abilities": ["contacts:read", "conversations:read"]
  }
}

effective_abilities es lo que el token puede de verdad: campaigns:read se queda fuera porque el rol Comercial no ve campañas, y GET /campaigns con ese token da 403 {"message": "Forbidden.", "code": "FORBIDDEN"}. En permissions, scope es el alcance (propios, equipo o todos; null si el módulo no lo tiene) e in_effect: false marca un permiso que el rol guarda pero que hoy no abre nada (módulos que todavía no existen o apps apagadas en la cuenta).

Los roles se leen por API; se cambian solo en el panel. Con team:read:

Ruta Qué da
GET /permissions El catálogo entero: cada módulo con sus acciones (contactos.ver, campanas.enviar…), qué módulos admiten alcance, y qué claves pide cada permiso de token (token_abilities). Incluye los módulos reservados de lo que está en obra (el correo y la exportación de datos), con reserved: true; embudo, tareas, empresas, catalogo y presupuestos ya no: son apps (las de §13 y §14, entre otras)
GET /roles · GET /roles/{rol} Los roles de serie (por su nombre corto: comercial, jefe-de-ventas…) y los a medida de tu cuenta (por su número), con sus permisos y alcances. Paginada, en orden estable
GET /users/{id}/effective-permissions Lo mismo que /me/permissions, de otra persona de tu cuenta

Las tres piden además que quien creó el token gestione el equipo (Propietario o Administrador); si no, 403 FORBIDDEN. Crear, editar, duplicar o borrar un rol y cambiar el rol de alguien (POST/PATCH/DELETE /roles, PATCH /users/{id}) responden 403 REQUIRES_SESSION_AUTH a cualquier token: se hace desde Ajustes → Roles y permisos. El rol de otra cuenta no existe para la tuya: su número da 404.

Hay acciones que ningún rol a medida puede llevar, y el catálogo las marca con grantable: false: gestionar el equipo y gestionar roles (solo Propietario y Administrador), y gestionar propietarios y administradores y gastar presupuesto o escribir a personas en LinkedIn (usuarios.gestionar_administradores, linkedin.gastar: solo el Propietario, ni siquiera el Administrador). El panel las enseña con candado, y si un rol a medida llega a pedirlas, el guardado responde 422 PERMISSION_NOT_GRANTABLE.

Varias cuentas a la vez

Si integras a varios clientes de Chatendo —una agencia, un programa de gestión con muchos comercios—, cada uno te da su token y cada token vive en su cuenta. Probado el 22-09-2026 con dos cuentas, A y B, en el entorno de pruebas de Chatendo:

Prueba Resultado
A da de alta un contacto Queda en la cuenta A, no en la B
A pide un contacto de B por su id 404 — ni siquiera se confirma que exista
A intenta editarlo o borrarlo 404, y el contacto de B sigue intacto
La lista de contactos de A Trae los de A, nunca los de B
B da de alta el mismo teléfono que ya tiene A 201: cada cuenta tiene su agenda; un teléfono no «choca» entre cuentas

Los controles también pasaron: cada token sí lee, edita y lista lo suyo. Veinte comprobaciones, veinte en verde.

Para tu lado: guarda cada token junto a la cuenta a la que pertenece. Un id de contacto solo vale con el token de su cuenta; con otro, es un 404.

Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento