Lister les entrées de temps d'un agent dans Zoho Desk est simple via l'API REST — une seule requête GET authentifiée vers le point de terminaison des entrées de temps de l'agent renvoie le journal complet pour cet agent.
Pourquoi c'est important
Lorsque vous devez auditer la façon dont les agents utilisent leur temps, générer des rapports de facturation ou alimenter les données de Desk dans un outil d'analyse externe, l'accès programmatique aux enregistrements d'entrées de temps est essentiel. Plutôt que d'exporter manuellement des données depuis l'interface, l'API vous permet d'extraire des enregistrements structurés à la demande. Cela est particulièrement utile pour les équipes qui gèrent des pipelines de reporting automatisés ou qui intègrent Zoho Desk avec des systèmes de paie et de gestion de projet.
Étape par étape
Étape 1. Identifiez l'agentId de l'agent dont vous souhaitez récupérer les entrées de temps. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque enregistrement d'agent — vous pouvez l'obtenir depuis le point de terminaison de la liste des agents ou depuis le profil de l'agent dans votre panneau d'administration Desk. [8]
Étape 2. Construisez l'URL de votre requête en utilisant le modèle suivant :
GET /api/v1/agents/{agentId}/timeEntriesRemplacez {agentId} par l'identifiant d'agent réel que vous avez récupéré à l'étape 1. [8]
Étape 3. Ajoutez les paramètres de requête optionnels en utilisant le dictionnaire p (ou la chaîne de requête équivalente). Le point de terminaison accepte un paramètre p qui peut contenir des options de pagination ou de filtrage — passez None si vous souhaitez obtenir le jeu de résultats par défaut. [8]
Étape 4. Envoyez la requête GET authentifiée. En Python, en utilisant un wrapper client préconfiguré, l'appel ressemble à ceci :
def list_agent_time_entries(self, agentId: str, p: dict = None):
return self.c.request("GET", f"/api/v1/agents/{agentId}/timeEntries", p, None)La méthode transmet le chemin, les paramètres de requête optionnels et None comme corps de la requête (puisqu'il s'agit d'un GET en lecture seule). [8]
Étape 5. Analysez la réponse JSON. La charge utile retournée contiendra les enregistrements d'entrées de temps associés à cet agent. Parcourez les entrées pour extraire des champs tels que le temps enregistré, le ticket associé et les horodatages selon les besoins de votre processus en aval. [8]
Erreurs courantes
- Format d'
agentIdincorrect. Passer un nom d'affichage ou une adresse e-mail au lieu de l'ID d'agent numérique ou textuel entraînera une réponse 404 ou vide. Résolvez toujours l'ID de manière programmatique avant d'appeler ce point de terminaison. [8] - En-têtes d'authentification manquants. Comme tous les appels à l'API Zoho Desk, ce point de terminaison nécessite un token OAuth 2.0 valide dans l'en-tête
Authorization. Une requête non authentifiée sera rejetée avant qu'aucune donnée ne soit renvoyée. [8] - Ignorer la pagination. Si un agent possède un grand volume d'entrées de temps, la réponse peut être paginée. Utilisez le paramètre
ppour parcourir les pages plutôt que de supposer que la première réponse contient tous les enregistrements. [8]
Ce qu'il faut vérifier
- Confirmez que l'
agentIddans votre requête correspond à l'enregistrement de l'agent dans Zoho Desk — une discordance est la cause la plus fréquente de réponses vides ou d'erreurs. [8] - Vérifiez que votre token OAuth dispose du bon périmètre d'API Desk et qu'il n'a pas expiré avant d'effectuer l'appel. [8]
- Examinez la structure de la réponse pour vous assurer que tous les champs d'entrées de temps attendus sont présents, et gérez le cas où le paramètre de pagination
psignale des pages de résultats supplémentaires. [8]
---
*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, référez-vous toujours à la documentation officielle et aux canaux de support de Zoho.*