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.
En esta página (3)
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 |
403 — le falta settings:read |
GET /channels · GET /imports |
403 — le falta channels:read |
GET /users |
403 — le falta team:read |
GET /contacts |
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:
- El permiso del token (
contacts:read,conversations:write…). Si falta:403 TOKEN_SCOPE_DENIED, con el permiso enrequired. - 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:
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
-H "Accept-Language: es" https://app.chatendo.app/api/v1/me/permissionsRespuesta 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):
{
"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 |
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 |
Lo mismo que /me, 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.