Cómo obtener el temporizador activo de un ticket en Zoho Desk

Recuperar el temporizador activo de un ticket de Zoho Desk es sencillo: envía una única solicitud GET autenticada al endpoint activeTimer, pasando el ID del ticket como parámetro de ruta.

Por qué es importante

Cuando los agentes registran tiempo en tickets de soporte, puede que necesites comprobar mediante programación si hay un temporizador en ejecución — por ejemplo, para aplicar reglas de facturación, construir paneles de control o activar automatizaciones cuando el seguimiento de tiempo está activo. El endpoint dedicado activeTimer devuelve únicamente el temporizador en curso, manteniendo la lógica de integración limpia y evitando la necesidad de filtrar una lista completa de temporizadores.

Paso a paso

Paso 1. Asegúrate de que tu token OAuth incluye los scopes correctos de Zoho Desk. Como mínimo necesitas Desk.tickets.READ (e idealmente Desk.tickets.ALL) autorizado para tu aplicación conectada. Estos scopes deben estar presentes cuando se genera o renueva el token. ^[8]

Paso 2. Obtén un token de acceso válido para el usuario objetivo. Si el token ha expirado, tu integración debe llamar al flujo de renovación del token usando el refreshtoken almacenado, tu clientid y tu clientsecret para recibir un nuevo accesstoken antes de continuar. ^[6]

Paso 3. Identifica el ticketId del ticket cuyo temporizador activo deseas inspeccionar. Este es el identificador numérico o alfanumérico único que Zoho Desk asigna a cada registro de ticket. ^[1]

Paso 4. Realiza una solicitud GET al siguiente endpoint, sustituyendo el ID real del ticket en la ruta:

GET /api/v1/tickets/{ticketId}/activeTimer

La solicitud acepta un diccionario de parámetros de consulta opcionales (p) si necesitas pasar filtros adicionales o indicaciones de paginación. ^[1]

Paso 5. En Python, usando el wrapper de la API de Zoho Desk, la llamada tiene este aspecto:

# Assuming `api` is an initialised ZohoDeskApi instance
response = api.get_active_timer_for_a(ticketId="1234567890")
print(response)

Pasa un diccionario p como segundo argumento si necesitas parámetros de consulta adicionales; de lo contrario, su valor predeterminado es None. ^[1]

Paso 6. Analiza la respuesta. Una llamada exitosa devuelve los detalles del temporizador en ejecución para ese ticket. Si no hay ningún temporizador activo, la API normalmente devolverá un resultado vacío o un indicador de estado relevante — gestiona ambos casos en tu código. ^[1]

Paso 7. Si también necesitas el registro completo del temporizador (no solo el activo), usa el endpoint complementario:

GET /api/v1/tickets/{ticketId}/timer

Esto recupera los datos generales del temporizador del ticket independientemente de si está en ejecución en ese momento. ^[3]

Paso 8. Para modificar el temporizador después de recuperarlo, usa el endpoint PATCH:

PATCH /api/v1/tickets/{ticketId}/timer

Pasa tus cambios como un diccionario data en el cuerpo de la solicitud. ^[2]

Paso 9. Si necesitas iniciar un nuevo temporizador desde cero, usa el endpoint de inicio dedicado:

POST /api/v1/tickets/{ticketId}/timer/start

Proporciona los campos requeridos en el parámetro de cuerpo data. ^[5]

Errores comunes

• Token de acceso ausente o expirado. Si el access_token está ausente o desactualizado, todas las llamadas a la API fallarán con un error de autenticación. Verifica siempre que el token esté renovado antes de realizar solicitudes de temporizador. ^[6]
• orgid incorrecto o ausente. Las llamadas a la API de Zoho Desk requieren que el ID de organización esté configurado en el cliente. Si deskorg_id no está almacenado, el cliente debe descubrirlo automáticamente llamando primero al endpoint de organizaciones; sin él, las solicitudes pueden devolver errores de permisos o de enrutamiento. ^[7]
• Scopes OAuth insuficientes. Los endpoints de temporizador están bajo los permisos de tickets. Si Desk.tickets.READ o Desk.tickets.ALL no se incluyeron al autorizar la conexión OAuth, la llamada será rechazada incluso con un token válido. ^[8]
• No existe ningún temporizador activo. El endpoint activeTimer es específico para temporizadores en curso. Si no hay ningún temporizador en ejecución en el ticket, no asumas que es un error — comprueba el cuerpo de la respuesta antes de tratarlo como un fallo. ^[1]

Qué verificar

• Confirma que tu token OAuth tiene al menos el scope Desk.tickets.READ y que no ha expirado antes de realizar la solicitud. ^[8]
• Verifica que el ticketId que estás pasando es correcto y pertenece a la misma organización de Zoho Desk contra la que está autenticado tu cliente. [^1, ^7]
• Si la respuesta está vacía, comprueba usando GET /api/v1/tickets/{ticketId}/timer para confirmar si existe algún registro de temporizador para ese ticket. ^[3]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho.*