Cómo listar las entradas de tiempo de un ticket en Zoho Desk

Listar todas las entradas de tiempo registradas en un ticket de Zoho Desk es sencillo una vez que conoces el endpoint de API correcto y los scopes de OAuth necesarios. Este artículo te guía por el proceso completo, desde la autenticación hasta la interpretación de la respuesta.

Por qué es importante

Las entradas de tiempo registran cuánto tiempo dedican los agentes a trabajar en un ticket, y acceder a ellas de forma programática te permite crear informes de facturación, auditar el esfuerzo de los agentes o enviar datos a herramientas externas de nómina y facturación. Si estás integrando Zoho Desk con un sistema de terceros, o simplemente quieres extraer datos de seguimiento de tiempo en bloque, este endpoint es tu punto de partida. Ten en cuenta que Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho.

Paso a paso

Paso 1. Confirma que tus scopes de OAuth incluyen permisos de tickets.

Antes de realizar cualquier llamada a la API, verifica que tu cliente OAuth conectado tenga concedidos los scopes de Desk necesarios. Como mínimo necesitas Desk.tickets.READ en tu cadena de scopes; una configuración más amplia también incluye Desk.tickets.ALL junto con scopes para contactos, tareas y otros módulos. ^[2]

Paso 2. Identifica el ID del ticket que quieres consultar.

Cada solicitud de entradas de tiempo está limitada a un único ticket. Localiza el ticketId numérico o alfanumérico del ticket en cuestión — puedes encontrarlo en la URL de Zoho Desk al visualizar el ticket, o recuperarlo de forma programática a través del endpoint de lista de tickets. ^[3]

Paso 3. Envía una solicitud GET al endpoint de entradas de tiempo.

Realiza un GET HTTP a la siguiente ruta, sustituyendo el identificador real de tu ticket:

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

En Python, usando un wrapper de cliente preconfigurado, la llamada tiene este aspecto:

def list_ticket_time_entries(self, ticketId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/tickets/{ticketId}/timeEntries", p, None)

El parámetro opcional p acepta un diccionario de parámetros de cadena de consulta (por ejemplo, opciones de paginación o filtrado). ^[3]

Paso 4. (Opcional) Filtra los resultados por tipo de facturación.

Si solo necesitas entradas agrupadas o filtradas por su clasificación de facturación, utiliza el sub-recurso dedicado al tipo de facturación:

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

Esto devuelve las entradas de tiempo organizadas por su categoría de facturación en lugar de una lista plana. ^[6]

Paso 5. (Opcional) Recupera un resumen consolidado en lugar de entradas individuales.

Cuando necesitas totales agregados — como el total de horas facturables de un ticket — llama al endpoint de resumen:

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

Esto te proporciona una suma de todo el tiempo registrado en el ticket sin devolver cada registro individual. ^[7]

Paso 6. Gestiona la paginación con el parámetro p.

Tanto el endpoint de lista principal como el de tipo de facturación aceptan un diccionario p para los parámetros de consulta. Pasa las claves de paginación (como from y limit) dentro de este diccionario para navegar por conjuntos de resultados grandes. ^[3][6]

Paso 7. Crea o actualiza entradas si es necesario.

Una vez que puedes leer entradas, puede que también quieras escribirlas. Para registrar una nueva entrada, envía un POST a la misma ruta base con un payload data:

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

Para modificar una entrada existente, usa una solicitud PATCH que también incluya el timeEntryId:

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

^[8][4]

Errores comunes

• Scopes ausentes o insuficientes. Si tu token fue generado sin Desk.tickets.READ (o Desk.tickets.ALL), la API devolverá un error de autorización. Vuelve a generar tu token OAuth con la cadena de scopes correcta antes de reintentar. ^[2]
• Formato incorrecto del ID de ticket. Pasar el *número* de ticket (la referencia legible que se muestra en la interfaz) en lugar del *ID* interno del ticket resultará en un 404 o una respuesta vacía. Utiliza siempre el identificador interno. ^[3]
• Confundir el endpoint de lista con el endpoint de resumen. La ruta /timeEntries devuelve registros individuales; /timeEntries/summary devuelve totales agregados. Llamar al incorrecto te dará datos con una estructura inesperada. ^[3][7]

Qué verificar

• Confirma que tu token de acceso OAuth incluye Desk.tickets.READ o Desk.tickets.ALL en sus scopes concedidos antes de realizar la solicitud. ^[2]
• Verifica que el ticketId en la ruta de tu solicitud sea el ID de registro interno de Zoho Desk, no el número de ticket que se muestra en pantalla. ^[3]
• Si esperas múltiples páginas de resultados, asegúrate de pasar los parámetros de paginación adecuados dentro del diccionario p para que no se omita ninguna entrada de forma silenciosa. ^[3][6]