Cómo recuperar el historial de tickets en Zoho Desk

La recuperación del historial de tickets en Zoho Desk se realiza a través de un endpoint de API dedicado que devuelve un registro cronológico de todos los cambios realizados en un ticket determinado. Aquí en Beam Help — soporte experto independiente para Zoho (no soporte oficial de Zoho) — te explicamos exactamente cómo llamarlo y qué debes tener configurado previamente.

Por qué esto es importante

Cuando un ticket de soporte pasa por varios agentes, cambios de estado o actualizaciones de prioridad, necesitas un registro de auditoría fiable para entender qué ocurrió y cuándo. El endpoint de historial de tickets te proporciona ese registro completo de forma programática, lo que resulta útil para informes, verificaciones de cumplimiento o depuración de estados inesperados en los tickets. Si estás desarrollando una integración o automatización sobre Zoho Desk, este suele ser uno de los primeros datos que querrás obtener.

Paso a paso

Paso 1. Confirma que tus scopes de OAuth están configurados correctamente.

Antes de realizar cualquier llamada a la API, tu aplicación conectada debe tener los permisos adecuados concedidos. Para el historial de tickets en concreto, necesitas como mínimo el scope Desk.tickets.READ autorizado en tu cliente OAuth. Se puede conceder un acceso más amplio con Desk.tickets.ALL, que cubre las operaciones de lectura, escritura, creación, actualización y eliminación de tickets. ^[2]

Paso 2. Obtén un token de acceso válido.

Tu integración se autentica mediante OAuth 2.0. Si tu token de acceso actual ha expirado, debes renovarlo enviando una solicitud POST al endpoint de tokens de Zoho con tu clientid, clientsecret y refreshtoken usando granttype: refreshtoken. Una respuesta exitosa devuelve un nuevo accesstoken junto con un valor expiresin (normalmente 3600 segundos) que debes almacenar junto con un timestamp calculado tokenexpires_at para saber cuándo renovarlo de nuevo. ^[8]

Paso 3. Identifica el ID de tu organización (org_id).

Las llamadas a la API de Zoho Desk requieren una cabecera orgId para enrutar las solicitudes al portal correcto. Si aún no lo has almacenado, puedes obtenerlo llamando al endpoint de organizaciones y leyendo el campo id del primer elemento del array data devuelto. Una vez recuperado, persístelo para no tener que buscarlo en cada solicitud. ^[4]

Paso 4. Llama al endpoint de historial de tickets.

Envía una solicitud GET autenticada a la siguiente ruta, sustituyendo el identificador real del ticket:

GET /api/v1/tickets/{ticket_id}/history

El nombre de la operación para esta llamada es gettickethistory. El ticket_id se pasa como parámetro de ruta. Se puede proporcionar un parámetro opcional p como diccionario de consulta para fines de paginación o filtrado. ^[3]

Un ejemplo mínimo en Python tiene este aspecto:

# Assuming `client` is an initialised ZohoDeskClient
history = client.request("GET", f"/api/v1/tickets/{ticket_id}/history", p, None)

Donde p es None o un diccionario de parámetros de consulta adicionales. ^[3]

Paso 5. Navega al ticket en la interfaz de Zoho Desk (verificación opcional).

Si deseas contrastar la respuesta de la API con lo que se muestra en el navegador, el patrón de URL directa para la página de detalle de un ticket sigue esta estructura:

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{ticket_id}

Reemplaza {dc} con el sufijo de tu centro de datos (p. ej., com, eu, in), {portal} con el nombre de tu portal o el ID de la organización, y {ticket_id} con el identificador numérico del ticket. ^[7]

Errores comunes

• orgId ausente o incorrecto: Si el org_id está vacío o es incorrecto, la API no podrá enrutar tu solicitud al portal de Desk correcto. Verifica siempre que esté almacenado y no esté vacío antes de realizar llamadas a tickets. ^[4]
• Scopes de OAuth insuficientes: Solicitar el historial con únicamente scopes de escritura o creación resultará en un error de autorización. Asegúrate de que Desk.tickets.READ o Desk.tickets.ALL esté incluido explícitamente en tu cadena de scopes. ^[2]
• Token de acceso expirado: Los tokens expiran aproximadamente después de una hora. Si recibes un error de autenticación, comprueba tu valor tokenexpiresat y activa una renovación antes de volver a intentarlo. ^[8]
• Dominio de centro de datos incorrecto: Zoho opera en varios centros de datos regionales. Si tu cuenta está en el centro de datos EU o IN, la URL base de tu API y la URL del token OAuth deben usar el sufijo regional correspondiente, no el dominio .com predeterminado. ^[7]

Qué verificar

• Confirma que Desk.tickets.READ (o Desk.tickets.ALL) aparece en tu lista de scopes OAuth autorizados antes de realizar la llamada. ^[2]
• Verifica que tanto un accesstoken válido y no expirado como un deskorg_id no vacío estén presentes en tu registro de conexión antes de llamar al endpoint de historial. ^[4]
• Contrasta al menos una entrada del historial de la respuesta de la API con el registro de actividad del ticket en la interfaz del agente de Zoho Desk para confirmar que los datos se devuelven correctamente. ^[7]