Cómo obtener entradas de tiempo de tickets en Zoho Desk

Zoho Desk expone varios endpoints de API dedicados para leer entradas de tiempo en un ticket — desde listar cada entrada hasta obtener un registro individual o un resumen consolidado. A continuación te explicamos cómo usar cada uno de forma efectiva.

Por qué esto es importante

El seguimiento del tiempo en Zoho Desk es esencial para la facturación, los informes de SLA y el análisis de productividad de los agentes. Ya sea que necesites extraer todas las horas registradas en un ticket de soporte, filtrar por tipo de facturación o mostrar un resumen del tiempo total en un panel de control, la API REST de Desk ofrece endpoints diseñados específicamente para cada escenario. Como soporte experto independiente (no soporte oficial de Zoho), Beam Help te guía a través de cada opción a continuación.

Paso a paso

Paso 1. Confirma tus permisos OAuth.

Antes de realizar cualquier solicitud de entrada de tiempo, verifica que tu token OAuth incluya al menos Desk.tickets.READ y Desk.tickets.ALL en su lista de permisos. Estos permisos controlan el acceso de lectura a los sub-recursos de los tickets, incluidas las entradas de tiempo. ^[7]

Paso 2. Lista todas las entradas de tiempo de un ticket.

Para recuperar cada entrada de tiempo registrada en un ticket específico, envía una solicitud GET a:

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

Reemplaza {ticketId} con el ID numérico del ticket que estás consultando. Se puede pasar un diccionario de parámetros p opcional para controlar la paginación o el filtrado. ^[4]

Ejemplo (Python):

entries = desk_client.list_ticket_time_entries(ticketId="123456")

Paso 3. Obtén una entrada de tiempo individual por su ID.

Cuando ya conoces el timeEntryId específico que deseas inspeccionar, llama al endpoint del registro individual:

GET /api/v1/tickets/{ticketId}/timeEntries/{timeEntryId}

Tanto ticketId como timeEntryId son parámetros de ruta obligatorios. Un diccionario p opcional puede incluir parámetros de consulta adicionales. ^[3]

Ejemplo (Python):

entry = desk_client.get_ticket_time_entry(ticketId="123456", timeEntryId="789")

Paso 4. Obtén un resumen (total) de todo el tiempo registrado.

Si solo necesitas los totales agregados en lugar de los registros individuales — útil para paneles de control o resúmenes de facturación — utiliza el endpoint de resumen:

GET /api/v1/tickets/{ticketId}/timeEntries/summary

Esto devuelve una vista consolidada del tiempo registrado para el ticket en lugar de una lista de entradas individuales. ^[5]

Ejemplo (Python):

summary = desk_client.get_summation_of_ticket_time(ticketId="123456")

Paso 5. Filtra las entradas de tiempo por tipo de facturación.

Para segmentar las entradas de tiempo según si son facturables o no facturables, utiliza el sub-endpoint de tipo de facturación:

GET /api/v1/tickets/{ticketId}/timeEntries/billingType

Pasa los criterios de filtro relevantes a través del diccionario de parámetros p. ^[2]

Ejemplo (Python):

billable = desk_client.get_ticket_time_entries_by(ticketId="123456", p={"billingType": "Billable"})

Paso 6. Actualiza una entrada de tiempo si se necesitan correcciones.

Si una entrada recuperada contiene datos incorrectos, puedes modificarla con una solicitud PATCH a:

PATCH /api/v1/tickets/{ticketId}/timeEntries/{timeEntryId}

Proporciona los campos a modificar dentro del diccionario data. ^[6]

Ejemplo (Python):

desk_client.update_ticket_time_entry(
    ticketId="123456",
    timeEntryId="789",
    data={"timeSpent": "02:30"}
)

Errores comunes

• Permisos faltantes. Las solicitudes devolverán un 401 o 403 si Desk.tickets.READ o Desk.tickets.ALL no están presentes en el token. Verifica siempre la lista de permisos durante la configuración de OAuth. ^[7]
• Confundir los endpoints de resumen y lista. La ruta /summary devuelve totales agregados, no filas individuales. Intentar iterar sobre ella como una lista causará errores inesperados. ^[5]
• Orden incorrecto en la ruta. Las sub-rutas /billingType y /summary deben ir después de /timeEntries en la URL. Invertir u omitir cualquier segmento resultará en un error 404. ^[2][5]

Qué verificar

• Confirma que el ticketId que estás usando es válido y pertenece al portal de Zoho Desk de tu organización antes de llamar a cualquier endpoint. ^[4]
• Verifica que tu token OAuth no haya expirado y que incluya los permisos Desk.tickets correctos. ^[7]
• Después de una actualización mediante PATCH, vuelve a obtener la entrada con gettickettime_entry para confirmar que los cambios se aplicaron correctamente. ^[3][6]