Tokens de API y acceso para desarrolladores

Actualizado el 4 nov 20267 min de lectura

Español

En esta página

Los tokens de API permiten que tu código o tus scripts se comuniquen con tu cuenta de Deskwoot sin usar una contraseña. Generas uno por cada integración (una sincronización con el CRM, un panel propio, una herramienta interna) y le das solo los permisos que esa integración realmente necesita. Puedes revocar un token en cualquier momento; la revocación es inmediata y no afecta a ningún otro token. La URL base es https://api.deskwoot.com/v1/ y el encabezado de autenticación es Authorization: Bearer YOUR_TOKEN. El acceso a la API es solo para Enterprise; los tokens que ya existían de planes anteriores siguen funcionando hasta que vencen.

Deskwoot ofrece una API REST que te da acceso desde código a tus datos y flujos de soporte. Ya sea que crees integraciones propias, sincronices datos de tickets con herramientas internas o automatices tareas repetitivas, los tokens de API te permiten autenticarte de forma segura sin compartir tus datos de inicio de sesión. Esta guía te explica cómo generar tokens, hacer tu primera llamada a la API y seguir las prácticas que mantienen segura tu cuenta.

La API REST es una función de Enterprise. La prueba de Enterprise de 7 días con la que empieza cada cuenta nueva no incluye tokens de API; necesitas un plan Enterprise activo para crearlos y usarlos. Si estás en un plan inferior y necesitas acceso a la API, tendrás que pasarte a Enterprise. Para ver con más detalle qué cubre la API, consulta el resumen de la API REST.

¿Cómo genero un token de API?

Inicia sesión en tu cuenta de Deskwoot y ve a Configuración > Tokens de API.
Haz clic en Crear token. Solo los administradores pueden crear tokens.
Ponle al token un nombre descriptivo (por ejemplo Sincronización CRM, producción) para saber más adelante para qué sirve.
Selecciona los permisos concretos que debe tener el token. Da solo los niveles de acceso que tu integración realmente necesita. Si quieres, elige una fecha de vencimiento.
Confirma y copia el token de inmediato. Por seguridad, el token completo se muestra una sola vez.

¿Cómo uso la API?

Todas las solicitudes a la API se hacen a esta URL base:

https://api.deskwoot.com/v1/

Incluye tu token de API en el encabezado Authorization de cada solicitud:

Authorization: Bearer YOUR_TOKEN

Ejemplo de solicitud

Una llamada sencilla con cURL para probar tu conexión podría verse así:

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.deskwoot.com/v1/me

Si el token es válido, la API devuelve el ID de tu cuenta y los permisos del token. Si no, recibes un error de autenticación. La referencia completa de endpoints está en la documentación de la API.

¿Cuáles son las buenas prácticas?

Da el mínimo acceso necesario. Asigna a cada token solo los permisos que requiere. Evita crear tokens con acceso total de administrador, a menos que de verdad lo necesites.
Cambia los tokens con regularidad. De vez en cuando, revoca los tokens antiguos y genera otros nuevos, sobre todo cuando alguien del equipo cambia de rol o se va.
Guarda los tokens de forma segura. Mantenlos en variables de entorno o en un gestor de secretos. Nunca los escribas directamente en el código del lado del cliente ni los subas a tu control de versiones.
Usa nombres descriptivos. Si nombras cada token según la integración o el entorno al que sirve, revisarlos es sencillo.
Vigila el uso. Revisa tus tokens activos en Configuración > Tokens de API con regularidad y elimina los que ya no uses.

¿Cómo soluciono errores de token?

401 Unauthorized: Comprueba que el token esté bien copiado, que no se haya revocado y que vaya en el encabezado con el prefijo Bearer.
403 Forbidden: Puede que el token no tenga permisos para el endpoint que llamas. Crea un token nuevo con los permisos correctos y revoca el antiguo. Un 403 también aparece cuando el espacio de trabajo ya no está en el plan Enterprise.
Límite de solicitudes: Si recibes errores por límite de solicitudes, llama a la API con menos frecuencia o agrega a tu código reintentos con espera exponencial.

Preguntas frecuentes

¿Y si prefiero que un agente de IA use la mesa de ayuda?

Si quieres que un agente de IA externo maneje Deskwoot en lugar de crear tu propia integración, revisa el servidor MCP. También es una función de Enterprise y usa tokens de bot con permisos limitados.

¿Dónde creo un token de API?

Configuración → Tokens de API → Crear token. Elige un nombre descriptivo, selecciona los permisos y copia el token cuando aparezca. Por seguridad, el token se muestra una sola vez. De nuestro lado solo guardamos un hash SHA-256, nunca el token en sí.

¿Qué permisos hay disponibles?

En Configuración → Tokens de API puedes elegir read (todo), write (todo), los pares más limitados contacts:read, contacts:write, conversations:read, conversations:write, help_center:read, help_center:write, e inbound:ingest (para enviar mensajes a una bandeja de entrada de canal API REST, no incluido en write). Elige el más limitado que la integración realmente necesite.

¿Qué pasa si pierdo un token?

Revócalo y crea uno nuevo. No hay forma de recuperarlo; de nuestro lado tampoco guardamos el valor del token de forma recuperable, y es a propósito.

¿Qué planes tienen acceso a la API?

Enterprise. Los tokens creados en planes antiguos antes del cambio de precios de 2026-05 siguen funcionando hasta que vencen (el indicador legacyApiAccess del registro del token los deja pasar), pero los tokens nuevos requieren Enterprise. La prueba de 7 días no incluye tokens de API.

¿Puedo limitar un token a una sola bandeja de entrada o a un solo equipo?

No con los permisos. Alternativa: filtra de tu lado cada solicitud por los ID de esa bandeja de entrada o de ese equipo.

¿Los tokens están ligados a un usuario o a una cuenta?

A los dos: un token está ligado a un usuario dentro de una cuenta. Las acciones del token se atribuyen al usuario que lo creó. Cada miembro ve y revoca solo sus propios tokens, y quitar a alguien del espacio de trabajo no revoca sus tokens, así que pídele que los revoque antes de irse. Buena práctica para integraciones compartidas: que un usuario dedicado, una cuenta de servicio “API”, sea el dueño de los tokens de integración.

¿Cómo cambio los tokens de forma segura sin interrupciones?

Crea el token nuevo, ponlo en todos lados, deja el antiguo activo durante un ciclo de despliegue y luego revócalo. Los dos tokens funcionan a la vez durante ese tiempo, así que nada se rompe.

¿La API cuenta para mi cuota de conversaciones de IA?

No. Leer conversaciones, publicar respuestas de agentes o gestionar contactos con la API no usa conversaciones de IA. Las conversaciones de IA se usan cuando Fynn o Copilot trabajan en una conversación o cuando se transcribe un mensaje de voz de esa conversación.

¿Puedo usar la API desde el navegador?

Técnicamente sí, pero no pongas tokens en el código del lado del cliente: cualquiera que vea el código fuente puede robarlos. Las llamadas desde el navegador deben pasar por tu propio backend, que es el que guarda el token.

¿Puedo ponerle una fecha de vencimiento a un token?

Sí. Al crear el token, elige una fecha en Vencimiento (opcional); el token funciona hasta el final de ese día en tu zona horaria y se rechaza en cada llamada a partir de entonces. Es útil para integraciones de corta duración (una auditoría, un script de migración de una sola vez), así no tienes que acordarte de hacer limpieza.

¿Puedo recibir webhooks en lugar de consultar la API una y otra vez?

Sí. Configuración → Webhooks → suscríbete a eventos (conversación nueva, mensaje nuevo, cambio de estado, etc.). Cada envío va firmado con HMAC (encabezado X-Deskwoot-Signature); verifica la firma antes de procesarlo.

¿La API REST está disponible en todos los planes?

No. La API REST es una función de Enterprise. Los planes de pago inferiores no la incluyen, y la prueba de Enterprise de 7 días tampoco: los tokens de API necesitan un plan Enterprise activo.

¿Puedo crear varios tokens de API?

Sí. Puedes generar todos los tokens que necesites. Recomendamos un token aparte para cada integración o entorno, así puedes revocar uno sin afectar a los demás.

¿Qué pasa si mi token queda expuesto?

Ve de inmediato a Configuración > Tokens de API, revoca el token expuesto y genera uno nuevo. Luego actualiza los servicios que usaban el token antiguo.

¿Dónde creo un token?

En Configuración > Tokens de API. Ponle un nombre al token, dale solo los permisos que necesita y cópialo enseguida, porque el valor completo se muestra una sola vez.

¿Te resultó útil esta guía?

Sigue leyendo

Preguntar a Fynn sobre esta guía

Recibe una respuesta corta basada en esta guía y el resto del centro de ayuda.