La API REST de Zoho Desk expone tres endpoints dedicados que te permiten recuperar datos de registros de tiempo para cualquier agente — ya sea como una lista completa, un registro individual o filtrado por tipo de facturación.
Por qué esto es importante
Cuando necesitas auditar cómo los agentes están invirtiendo su tiempo, generar informes de facturación o enviar datos de seguimiento de tiempo a un sistema externo, debes poder consultar los registros de tiempo de los agentes de forma programática. Zoho Desk proporciona operaciones de API diseñadas específicamente para este caso de uso, y saber qué endpoint llamar — y con qué parámetros — ahorra un esfuerzo de desarrollo considerable.
> Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho.
---
Paso a paso
Paso 1. Identifica al agente cuyos registros de tiempo necesitas.
Cada solicitud requiere un agentId. Este es el identificador único del registro del agente dentro de tu organización de Zoho Desk. Puedes obtenerlo desde la sección Agentes del panel de administración de Desk o desde una llamada a la API anterior que devuelva objetos de agente. Guarda este valor a mano — aparece en la ruta URL para las tres operaciones que se describen a continuación. [5]
Paso 2. Lista todos los registros de tiempo de un agente.
Envía una solicitud GET a la siguiente ruta, sustituyendo el identificador del agente:
GET /api/v1/agents/{agentId}/timeEntriesLa operación se llama listagenttime_entries. Un parámetro opcional p te permite pasar filtros en la cadena de consulta (como paginación o rango de fechas) junto con la solicitud. En Python, la llamada tiene este aspecto:
client.list_agent_time_entries(agentId="12345678", p={"from": 1, "limit": 50})Esto devuelve la colección completa de registros de tiempo asociados a ese agente. [5]
Paso 3. Recupera un registro de tiempo específico.
Si ya conoces el identificador de un registro de tiempo en particular — por ejemplo, de la lista devuelta en el Paso 2 — puedes obtener solo ese registro con:
GET /api/v1/agents/{agentId}/timeEntries/{timeEntryId}La operación se llama getagenttime_entry y requiere tanto agentId como timeEntryId como parámetros de ruta. El diccionario opcional p puede contener cualquier parámetro de consulta adicional que necesite tu integración. [7]
client.get_agent_time_entry(agentId="12345678", timeEntryId="98765432")Paso 4. Filtra los registros de tiempo por tipo de facturación.
Cuando solo quieres entradas que coincidan con una clasificación de facturación específica (por ejemplo, facturable vs. no facturable), usa la variante del endpoint por tipo de facturación:
GET /api/v1/agents/{agentId}/timeEntries/billingTypeLa operación se llama getagenttimeentriesby. Pasa el tipo de facturación deseado a través del diccionario de parámetros p. Esto es especialmente útil al generar facturas o conciliar horas facturables. [3]
client.get_agent_time_entries_by(agentId="12345678", p={"type": "Billable"})Paso 5. Gestiona la respuesta.
Los tres endpoints devuelven JSON. Analiza el cuerpo de la respuesta para extraer los campos de registro de tiempo que necesitas — como duración, referencia del ticket y clasificación de facturación — y mapéalos en tu flujo de trabajo de informes o facturación. [5][7][3]
---
Errores comunes
- Formato incorrecto de
agentId. Pasar un nombre de visualización o un correo electrónico en lugar del ID numérico del agente resultará en una respuesta 404 o vacía. Siempre resuelve el ID del agente desde la API antes de construir tu solicitud. [5] - Confundir el endpoint de tipo de facturación con el endpoint de lista. La ruta
/timeEntries/billingTypees una ruta distinta, no un sub-recurso de una entrada específica. No insertes untimeEntryIdentretimeEntriesybillingType. [3] - Parámetros de paginación ausentes. El endpoint de lista (
/timeEntries) puede devolver un conjunto de resultados paginado. Si omites los controles de paginación en el diccionariop, es posible que solo recibas la primera página de entradas y pierdas silenciosamente registros más antiguos. [5]
---
Qué verificar
- Confirma que el
agentIdque estás usando corresponde a un agente activo en tu organización de Zoho Desk antes de realizar solicitudes masivas. - Verifica que tus credenciales de API tengan el permiso de lectura del ámbito Time Entry; sin él, los tres endpoints devolverán un error de autorización.
- Después de recuperar los registros, compara al menos uno con la interfaz de Zoho Desk (perfil del agente → registros de tiempo) para confirmar que los datos coinciden con lo que se muestra en el portal. [5][7][3]