Comment lister les entrées de temps d'une tâche dans Zoho Desk

Lister les entrées de temps d'une tâche dans Zoho Desk est simple dès lors que vous disposez du bon identifiant de tâche et des scopes OAuth appropriés — une seule requête GET retourne toutes les entrées de temps associées à cette tâche.

Pourquoi c'est important

Lorsque votre équipe support enregistre du temps sur des tâches dans Zoho Desk, vous pouvez avoir besoin de récupérer ces enregistrements par programmation — à des fins de facturation, de reporting ou d'intégration avec des outils externes. Connaître le bon endpoint et les permissions requises vous évite un débogage par tâtonnement. C'est particulièrement pertinent si vous construisez des automatisations ou des tableaux de bord qui exposent les données d'effort des agents.

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut le scope lié aux tâches approprié. Votre connexion Zoho Desk doit être autorisée avec au minimum Desk.tasks.READ (et idéalement Desk.tasks.ALL) pour récupérer les données d'entrées de temps. Sans ce scope, l'API rejettera la requête avant qu'elle n'atteigne l'endpoint. ^[5]

Étape 2. Identifiez le taskId de la tâche dont vous souhaitez récupérer les entrées de temps. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque enregistrement de tâche. Vous pouvez l'obtenir à partir d'un appel précédent de listage de tâches ou directement depuis l'URL de la tâche dans l'interface Zoho Desk. ^[6]

Étape 3. Envoyez une requête GET vers l'endpoint suivant, en remplaçant l'identifiant de tâche par le vôtre :

GET /api/v1/tasks/{taskId}/timeEntries

Le nom de l'opération pour cet appel est listtasktime_entries. L'endpoint accepte deux paramètres : taskId (obligatoire, l'identifiant unique de la tâche) et p (optionnel, utilisé pour la pagination ou des paramètres de requête supplémentaires). ^[6]

Étape 4. En Python, l'appel peut être structuré comme indiqué ci-dessous. Le paramètre p est passé sous forme de dictionnaire et peut être omis si vous n'avez pas besoin de filtrer ou de paginer les résultats :

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

Cette méthode envoie la requête via votre client Zoho Desk configuré, qui gère automatiquement l'authentification et l'identifiant d'organisation. ^[6]

Étape 5. Assurez-vous que l'identifiant d'organisation Zoho Desk (deskorgid) est correctement défini sur votre client API avant d'effectuer l'appel. Si l'identifiant d'organisation est manquant ou incorrect, la plateforme ne pourra pas router la requête vers le bon compte. L'outillage de notre équipe détecte automatiquement l'identifiant d'organisation à partir du premier élément retourné par l'endpoint des organisations et le stocke pour les appels ultérieurs. ^[7]

Erreurs courantes

• Scope manquant : Si Desk.tasks.READ ou Desk.tasks.ALL est absent de votre token OAuth, la requête échouera avec une erreur d'autorisation. Réautorisez votre connexion avec la liste complète des scopes de tâches avant de réessayer. ^[5]
• taskId incorrect ou obsolète : Passer un identifiant appartenant à une tâche supprimée ou inaccessible retournera un résultat vide ou une erreur. Validez toujours l'identifiant de tâche par rapport à une réponse de listage de tâches récente. ^[6]
• Identifiant d'organisation non résolu : Si la propriété org_id de votre client est vide, Zoho Desk ne peut pas identifier quelle organisation interroger. Déclenchez le flux de découverte d'organisation pour renseigner cette valeur avant d'appeler un endpoint Desk. ^[7]

Points à vérifier

• Vérifiez que votre token OAuth actif inclut Desk.tasks.READ ou Desk.tasks.ALL dans sa liste de scopes. ^[5]
• Confirmez que la valeur taskId est valide et appartient à une tâche au sein de la bonne organisation Zoho Desk. ^[6]
• Vérifiez que deskorgid est renseigné sur votre client API afin que les requêtes soient routées vers le bon compte. ^[7]

---

*Beam Help fournit une assistance experte indépendante pour Zoho — nous ne sommes pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, consultez toujours directement la documentation de l'API Zoho Desk.*