Comment obtenir le minuteur de tâche dans Zoho Desk

Les minuteurs de tâches dans Zoho Desk vous permettent de suivre le temps passé sur des tâches individuelles. L'API Zoho Desk expose deux endpoints distincts pour récupérer ces données — l'un pour l'enregistrement complet du minuteur et l'autre pour le minuteur en cours d'exécution.

Pourquoi c'est important

Lorsque vous devez auditer le temps enregistré sur des tâches de support, créer des tableaux de bord de reporting personnalisés, ou intégrer les données de temps de tâche Zoho Desk dans un outil de facturation tiers, vous devez savoir quel endpoint API appeler et comment vous authentifier correctement. Deux opérations de lecture distinctes sont disponibles : récupérer l'enregistrement complet du minuteur pour une tâche, et récupérer uniquement le minuteur *actif* (en cours d'exécution). Choisir le mauvais peut renvoyer des données vides ou une réponse trompeuse.

---

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth incluent les permissions de tâches.

Avant d'effectuer toute requête de minuteur, vérifiez que votre token OAuth Zoho Desk connecté a été émis avec au moins Desk.tasks.READ (ou Desk.tasks.ALL) dans sa liste de scopes. Sans cela, l'API rejettera votre requête avec une erreur d'autorisation. ^[5]

Étape 2. Obtenez un token d'accès valide.

Votre intégration doit disposer d'un token d'accès actuel pour Zoho Desk. Si le token a expiré, utilisez votre refresh token stocké pour appeler l'endpoint de token de Zoho avec votre clientid, clientsecret et granttype: refreshtoken. Une réponse réussie inclura un nouveau accesstoken et une valeur tokenexpires_at mise à jour. ^[6]

Étape 3. Identifiez le taskId que vous souhaitez interroger.

Chaque requête de minuteur est limitée à une tâche spécifique. Vous avez besoin de l'identifiant unique de la tâche (par ex. "1234567890") avant d'appeler l'un ou l'autre des endpoints. Celui-ci est généralement renvoyé lorsque vous créez ou listez des tâches via l'API Zoho Desk.

Étape 4. Récupérez l'enregistrement complet du minuteur pour une tâche.

Envoyez une requête GET vers :

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

Remplacez {taskId} par votre identifiant de tâche réel. Un dictionnaire de paramètres de requête optionnel (p) peut être transmis pour tout argument de filtre ou de pagination pris en charge. En Python, cela ressemble à : ^[1]

response = desk_api.get_task_timer(taskId="1234567890")

Cela renvoie l'enregistrement complet du minuteur associé à cette tâche, y compris les entrées de temps historiques.

Étape 5. Récupérez uniquement le minuteur actuellement actif (le cas échéant).

Si vous avez uniquement besoin de savoir si un minuteur est *en cours d'exécution* sur une tâche, appelez plutôt l'endpoint dédié au minuteur actif :

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

Là encore, substituez votre vrai taskId. En Python : ^[2]

response = desk_api.get_active_timer_for_a_2(taskId="1234567890")

Cet endpoint renvoie des données uniquement lorsqu'un minuteur est activement en cours d'exécution sur la tâche spécifiée. Si aucun minuteur n'est en cours, attendez-vous à une charge utile vide ou nulle.

Étape 6. (Optionnel) Mettez à jour le minuteur si nécessaire.

Si les données du minuteur récupérées nécessitent une correction — par exemple, ajuster le temps enregistré — vous pouvez effectuer une requête PATCH vers le même chemin /api/v1/tasks/{taskId}/timer, en fournissant un dictionnaire data avec les champs à mettre à jour. ^[7]

Étape 7. Initialisez le client API Desk avec le bon org_id.

Zoho Desk est limité à une organisation. Lors de la construction du client API, assurez-vous que le orgid est renseigné. S'il est manquant, le système peut le découvrir automatiquement en appelant l'endpoint de liste des organisations et en conservant le premier id renvoyé. Sans un orgid valide, tous les appels à l'API Desk — y compris les requêtes de minuteur — échoueront. ^[4]

---

Erreurs courantes

• Appeler le mauvais endpoint. GET /api/v1/tasks/{taskId}/timer renvoie l'historique complet du minuteur, tandis que GET /api/v1/tasks/{taskId}/activeTimer renvoie uniquement un minuteur en cours d'exécution. ^[1][2] Si vous attendez un statut en temps réel mais appelez le premier, vous risquez de voir des données obsolètes.
• Token d'accès manquant ou expiré. Le flux de renouvellement du token doit se terminer avec succès — plus précisément, la réponse doit contenir access_token — avant tout appel à l'API Desk. Une clé d'erreur dans la réponse de renouvellement signifie que le token n'a pas été renouvelé. ^[6]
• Scopes OAuth insuffisants. La récupération des données de minuteur nécessite des permissions de lecture au niveau des tâches (Desk.tasks.READ ou Desk.tasks.ALL). Les scopes sont définis au moment de l'autorisation OAuth et ne peuvent pas être ajoutés rétroactivement sans une nouvelle autorisation. ^[5]
• orgid manquant. Zoho Desk requiert un identifiant d'organisation sur chaque requête. Si votre enregistrement de connexion ne contient pas deskorg_id, le client doit le résoudre avant de continuer. ^[4]

---

Ce qu'il faut vérifier

• Couverture des scopes : Confirmez que Desk.tasks.READ ou Desk.tasks.ALL apparaît dans votre configuration de scope OAuth active. ^[5]
• Validité du token : Vérifiez que tokenexpiresat est dans le futur ; sinon, déclenchez un renouvellement avant d'appeler les endpoints de minuteur. ^[6]
• Sélection du bon endpoint : Utilisez /activeTimer pour les vérifications de statut en temps réel et /timer pour les enregistrements historiques complets, et confirmez que le taskId dans le chemin correspond à la tâche que vous souhaitez interroger. ^[1][2]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho — nous ne sommes pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, référez-vous toujours à la documentation officielle de l'API Zoho Desk.*