2 de junio de 2026Atención al cliente

Conéctate a la API de initdesk en 15 minutos

La API de initdesk ya está disponible: emite un token, encuentra el ID de tu organización y lista tickets con curl en una sola sesión.

La API de initdesk está disponible hoy en developers.initdesk.com, con peticiones enviadas a https://api.initdesk.com.

Si no estás seguro de si necesitas la API, webhooks o BYOD, lee primero API, webhooks o BYOD; este artículo asume que quieres que tu código llame a initdesk (crear o leer tickets, solicitantes, mensajes o contenido del Help Center).

Abajo está el camino más corto hasta una llamada que funcione: token, ID de organización, un curl, y luego la especificación OpenAPI para todo lo demás.

Qué necesitas antes de empezar

Una cuenta de initdesk donde seas Propietario de la cuenta o Administrador (solo esos roles pueden emitir tokens de API).
El ID numérico de la organización en Configuración → General. Las rutas de la API usan este número, no el public_id de cadena de la organización en las URL del producto.
Un sitio seguro para guardar el token. initdesk almacena un hash en el servidor; ves el token en bruto solo una vez al crearlo.

Emite un token de organización

Abre Configuración → Acceso a la API.
Genera un nuevo token de integración con alcance de organización.
Copia el token de inmediato en tu gestor de secretos o bóveda de contraseñas.

Envíalo en cada petición con la cabecera personalizada:

X-Initdesk-Token: YOUR_TOKEN_HERE

Ese token solo puede acceder a recursos de la organización para la que se emitió. Las llamadas a URL de otra organización devuelven 403 Forbidden. Los tokens inválidos o revocados devuelven 401 o 403 según corresponda. Revoca tokens comprometidos en la misma pantalla de configuración.

Detalles: Autenticación y límites.

Tu primera petición: confirma la organización

Sustituye ORG_ID y YOUR_TOKEN en los ejemplos siguientes.

curl -sS \
  -H "X-Initdesk-Token: YOUR_TOKEN" \
  "https://api.initdesk.com/organizations/ORG_ID/"

Una respuesta correcta confirma que estás en el inquilino correcto y muestra la configuración de la organización que puede afectar al comportamiento de los tickets (por ejemplo, si el etiquetado automático está activado). Si obtienes 401 o 403, vuelve a comprobar el token y que ORG_ID coincida con Configuración → General.

Lista bandejas (necesario antes de crear tickets)

Los tickets se crean en una bandeja concreta. Listalas para copiar un id de bandeja para llamadas POST posteriores:

curl -sS \
  -H "X-Initdesk-Token: YOUR_TOKEN" \
  "https://api.initdesk.com/organizations/ORG_ID/inboxes/"

Los endpoints de listado devuelven JSON paginado: count, next, previous y results (tamaño de página por defecto 20). Sigue las URL de next hasta tener lo que necesites.

Lista tickets (ruta de lectura)

curl -sS \
  -H "X-Initdesk-Token: YOUR_TOKEN" \
  "https://api.initdesk.com/organizations/ORG_ID/tickets/"

Por defecto se excluyen los tickets de spam. Para trabajar con spam, pasa is_spam=true. Filtra por solicitante con customer_id cuando conozcas el id de API del cliente.

Para búsqueda y filtros predefinidos, usa el endpoint de búsqueda de tickets documentado en el índice de referencia de la API, útil para paneles de operaciones sin exportar toda la bandeja.

`id` frente a `public_id` del ticket (y dónde viven los mensajes)

Cada ticket tiene dos identificadores:

Campo	Uso
`id`	Clave primaria en las URL de la API (`/tickets/{id}/`, `/tickets/{id}/messages/`)
`public_id`	Número visible para humanos en asuntos de correo y la interfaz («Ticket n.º 1234»)

Usa siempre id en las llamadas a la API. Muestra public_id a los clientes cuando necesites la etiqueta habitual.

La fila del ticket es el contenedor (asunto, estado, asignado, bandeja, etiquetas). El hilo (respuestas, notas internas, eventos del sistema) está en mensajes:

/organizations/{organization_id}/tickets/{ticket_id}/messages/

Recupera un ticket para metadatos; lista mensajes cuando necesites la conversación completa. El comportamiento a nivel de campo está en Entidades y relaciones.

OpenAPI, paginación y límites de tasa

Esquema OpenAPI: https://api.initdesk.com/schema.yaml — genera clientes o explora cada ruta bajo /organizations/{organization_id}/.
Paginación: listas por número de página con count, next, previous, results.
Límites de tasa: 60 peticiones por minuto por token para la mayoría de endpoints. La creación de tickets también está limitada por organización por hora. Ante 429 Too Many Requests, espera con retardo exponencial y reintenta.

Crear tickets, responder, sincronizar artículos del Help Center y gestionar clientes están documentados en la referencia para desarrolladores; este artículo se detiene en lectura/listado para que verifiques la autenticación antes de escribir datos.

Preguntas sobre endpoints beta o acceso: support@initdesk.com.

initdesk es un help desk con IA para equipos pequeños. La API se lanza hoy junto con developers.initdesk.com. Más en Actualizaciones del producto y X @initdeskhq.