Cómo recuperar métricas de tickets en Zoho Desk

Las métricas de tickets en Zoho Desk están disponibles a través de un único endpoint REST que devuelve datos de rendimiento para cualquier ticket individual — sin necesidad de navegar por el panel de control.

Por qué esto es importante

Cuando necesitas auditar tiempos de respuesta, medir el cumplimiento del SLA o extraer datos de rendimiento sin procesar hacia un pipeline de informes, la API de Zoho Desk te ofrece acceso programático directo a las métricas por ticket. Esto es especialmente útil para equipos que crean paneles personalizados o automatizan controles de calidad sin tener que navegar manualmente por la interfaz del agente de Desk.

Paso a paso

Paso 1. Confirma que tu token OAuth incluye los scopes correctos de Desk antes de realizar cualquier llamada a la API. Como mínimo, necesitas Desk.tickets.READ en tu lista de scopes autorizados — opciones más amplias como Desk.tickets.ALL también satisfacen este requisito. ^[3]

Paso 2. Identifica el ticket_id numérico del ticket cuyas métricas deseas obtener. Puedes encontrarlo en la URL del portal del agente de Zoho Desk, que sigue el patrón https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}, o consultando primero el endpoint de lista de tickets. ^[4]

Paso 3. Envía una solicitud GET al endpoint de métricas, sustituyendo el ID de tu ticket en la ruta:

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

El endpoint acepta ticket_id como parámetro de ruta obligatorio y un parámetro opcional p para cualquier opción de consulta adicional que desees incluir. ^[1]

Paso 4. En Python, la llamada tiene este aspecto usando el wrapper ZohoDeskApi:

metrics = api.get_ticket_metrics(ticket_id="12345")

Pasa un diccionario opcional como segundo argumento (p) si necesitas incluir parámetros de consulta adicionales. ^[1]

Paso 5. Analiza el diccionario de respuesta que se devuelve. Nuestro equipo recomienda imprimir o registrar la respuesta completa durante el desarrollo para que puedas ver exactamente qué campos de métricas devuelve tu organización de Desk — la disponibilidad de campos puede variar según el plan y la configuración. ^[5]

Paso 6. Si estás creando un flujo de trabajo conversacional o automatizado, el patrón del asistente de Zoho Desk consiste en invocar siempre la herramienta con datos reales en lugar de adivinar valores. Confirma que tienes el ticket_id antes de invocar el endpoint; si falta, solicítalo explícitamente antes de continuar. ^[5]

Errores comunes

• Scopes de OAuth ausentes o incorrectos. Si tu token fue generado sin Desk.tickets.READ (o Desk.tickets.ALL), la API devolverá un error de autorización. Verifica la cadena de scopes en tu configuración OAuth — cada scope debe estar separado por comas sin espacios al final. ^[3]

• Tokens de acceso caducados. Los tokens de acceso de Zoho caducan (normalmente después de una hora). La capa de API debería actualizarse automáticamente usando el refreshtoken almacenado; si ves errores 401, verifica que tu lógica de actualización de tokens esté escribiendo el nuevo accesstoken de vuelta en tu almacén de conexiones antes de reintentar. ^[8]

• Dominio de centro de datos incorrecto. Desk está alojado en múltiples centros de datos regionales. La URL base cambia según tu DC — por ejemplo https://desk.zoho.com para cuentas .com frente a https://desk.zoho.{dc} para las regiones EU, IN, AU y otras. Usar el dominio incorrecto provocará errores de conexión o errores 404. ^[4]

• ID de organización no configurado. El ZohoDeskClient requiere un encabezado orgid válido en cada solicitud. Si tu registro de conexión aún no tiene deskorg_id configurado, el cliente intentará descubrirlo automáticamente llamando al endpoint de organizaciones en el primer uso. Asegúrate de que este paso de descubrimiento se complete correctamente antes de llamar al endpoint de métricas. ^[8]

Qué verificar

• Comprueba que la respuesta contiene los campos de métricas esperados (p. ej., tiempo de respuesta, tiempo de resolución) y que ninguno es null debido a que el ticket sigue abierto o sin asignar.
• Confirma que tus scopes de OAuth incluyen al menos Desk.tickets.READ y que el token se ha actualizado si tiene más de una hora de antigüedad. ^[3]
• Compara el ticket_id devuelto con la URL del portal del agente de Desk para asegurarte de haber consultado el ticket correcto. ^[4]

---

*Beam Help ofrece orientación experta independiente sobre productos Zoho y no es el soporte oficial de Zoho.*