La récupération du minuteur actif d'une tâche dans Zoho Desk nécessite une seule requête GET authentifiée vers la sous-ressource activeTimer de la tâche, qui renvoie le minuteur actuellement en cours d'exécution pour cette tâche.
Pourquoi c'est important
Lorsque votre équipe support suit les heures facturables ou la conformité aux SLA via les tâches Zoho Desk, vous pouvez avoir besoin de vérifier par programmation si un minuteur est déjà en cours avant d'en démarrer un nouveau. La récupération du minuteur actif vous permet d'afficher des données de suivi du temps en direct dans vos tableaux de bord, d'éviter les minuteurs en double ou d'alimenter le temps écoulé dans des outils de reporting en aval. Cela est distinct de la récupération de l'historique complet des minuteurs d'une tâche, qui utilise un endpoint distinct.
---
Étape par étape
Étape 1. Confirmez que vous disposez d'une connexion valide à l'API Zoho Desk avec un jeton d'accès OAuth actif et l'orgId correct pour votre portail. Sans ces éléments, chaque appel API sera rejeté avant d'atteindre la ressource du minuteur. [7]
Étape 2. Identifiez le taskId de la tâche dont vous souhaitez inspecter le minuteur actif. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque enregistrement de tâche — vous pouvez le récupérer à partir d'un appel de liste de tâches précédent ou depuis l'URL de la tâche dans l'interface Desk. [1]
Étape 3. Envoyez une requête GET vers l'endpoint suivant, en remplaçant l'ID de tâche par le vôtre :
GET /api/v1/tasks/{taskId}/activeTimerInclure votre en-tête Authorization: Zoho-oauthtoken <access_token> ainsi que l'en-tête orgId requis par Zoho Desk. [1]
Étape 4. Transmettez éventuellement des paramètres de requête via le dictionnaire p si votre intégration doit filtrer ou paginer la réponse. La signature de l'opération accepte un paramètre p optionnel à cet effet. [1]
Étape 5. Si vous utilisez le wrapper client Python avec lequel notre équipe travaille, l'appel se présente comme suit :
result = api.get_active_timer_for_a_2(taskId="your_task_id_here")La méthode émet la requête GET en interne et renvoie la réponse analysée. [1]
Étape 6. Analysez le corps de la réponse. Un minuteur en cours d'exécution sera présent dans le payload ; si aucun minuteur n'est actuellement actif, la réponse renverra généralement un objet de données vide ou null plutôt qu'une erreur.
---
Ne confondez pas ces trois endpoints
Zoho Desk expose des ressources activeTimer similaires à différents niveaux — il est facile d'appeler le mauvais :
| Ce que vous souhaitez | Endpoint |
|---|---|
| Minuteur actif d'une tâche | GET /api/v1/tasks/{taskId}/activeTimer [1] |
| Minuteur actif d'un ticket | GET /api/v1/tickets/{ticketId}/activeTimer [2] |
| Minuteur actif d'un agent | GET /api/v1/agents/{agentId}/activeTimer [4] |
Confondre taskId et ticketId est l'erreur la plus fréquente — les tâches et les tickets sont des objets distincts dans Zoho Desk et leurs identifiants ne sont pas interchangeables. [1][2]
Il existe également un endpoint connexe mais différent qu'il est utile de connaître :
GET /api/v1/tasks/{taskId}/timerCelui-ci récupère l'enregistrement général du minuteur d'une tâche plutôt que spécifiquement le minuteur *actif* (en cours d'exécution). Utilisez activeTimer lorsque vous souhaitez uniquement connaître ce qui est en cours d'exécution à l'instant présent. [6]
---
Erreurs courantes
- Mauvais type de ressource. Passer un ID de ticket dans l'endpoint de tâche (ou inversement) renverra une erreur 404 ou un enregistrement sans rapport. Vérifiez toujours à quel type d'objet appartient votre ID avant d'effectuer l'appel. [1][2]
- En-tête
orgIdmanquant. Zoho Desk exige l'identifiant d'organisation sur chaque requête. Si votre connexion a été configurée sans persister l'orgId, le client peut tenter de le découvrir automatiquement lors de la première utilisation — assurez-vous que cette découverte s'est effectuée avec succès avant d'effectuer des appels de minuteur. [7] - Jeton d'accès expiré. Les jetons OAuth ont une durée de vie limitée. Un mécanisme de renouvellement du jeton doit être en place afin que les requêtes de minuteur n'échouent pas silencieusement en cours de session. [7]
- Confusion entre
activeTimerettimer. L'endpoint/timerrenvoie des données de minuteur plus larges ;/activeTimerest limité à ce qui est actuellement en cours d'exécution. Utiliser le mauvais peut renvoyer des données obsolètes ou historiques au lieu de l'état en temps réel. [6]
---
Points à vérifier
- Type d'ID correct : Confirmez que l'ID que vous transmettez appartient à un objet *tâche*, et non à un ticket ou une autre entité, avant d'appeler
GET /api/v1/tasks/{taskId}/activeTimer. [1] - En-têtes d'authentification : Vérifiez que votre jeton d'accès OAuth et votre
orgIdZoho Desk sont tous deux présents et à jour dans les en-têtes de la requête. [7] - Données de réponse vs. réponse vide : Vérifiez si le payload renvoyé contient un objet de minuteur actif ou s'il est vide — une réponse vide signifie qu'aucun minuteur n'est actuellement en cours d'exécution, ce qui est valide et ne doit pas être traité comme une erreur. [1]
---
*Beam Help fournit une 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 de Zoho et à ses canaux de support.*