Comment obtenir le minuteur actif d'un ticket dans Zoho Desk

Récupérer le minuteur actif d'un ticket Zoho Desk est simple : envoyez une seule requête GET authentifiée vers l'endpoint activeTimer, en passant l'identifiant du ticket comme paramètre de chemin.

Pourquoi c'est important

Lorsque les agents enregistrent du temps sur des tickets de support, vous pouvez avoir besoin de vérifier par programmation si un minuteur est actuellement en cours d'exécution — par exemple, pour appliquer des règles de facturation, créer des tableaux de bord, ou déclencher des automatisations lorsque le suivi du temps est actif. L'endpoint dédié activeTimer renvoie uniquement le minuteur en cours, ce qui simplifie la logique de votre intégration et évite de devoir filtrer une liste complète de minuteurs.

Étape par étape

Étape 1. Assurez-vous que votre jeton OAuth inclut les scopes Zoho Desk appropriés. Vous avez besoin au minimum de Desk.tickets.READ (et idéalement de Desk.tickets.ALL) autorisé pour votre application connectée. Ces scopes doivent être présents lors de la génération ou du renouvellement du jeton. ^[8]

Étape 2. Obtenez un jeton d'accès valide pour l'utilisateur cible. Si le jeton a expiré, votre intégration doit appeler le flux de renouvellement du jeton en utilisant le refreshtoken stocké, votre clientid et votre clientsecret pour recevoir un nouveau accesstoken avant de continuer. ^[6]

Étape 3. Identifiez le ticketId du ticket dont vous souhaitez inspecter le minuteur actif. Il s'agit de l'identifiant numérique ou alphanumérique unique que Zoho Desk attribue à chaque enregistrement de ticket. ^[1]

Étape 4. Effectuez une requête GET vers l'endpoint suivant, en substituant l'identifiant réel du ticket dans le chemin :

GET /api/v1/tickets/{ticketId}/activeTimer

La requête accepte un dictionnaire de paramètres de requête optionnel (p) si vous avez besoin de passer des filtres supplémentaires ou des indications de pagination. ^[1]

Étape 5. En Python, en utilisant le wrapper de l'API Zoho Desk, l'appel ressemble à ceci :

# Assuming `api` is an initialised ZohoDeskApi instance
response = api.get_active_timer_for_a(ticketId="1234567890")
print(response)

Passez un dictionnaire p comme second argument si vous avez besoin de paramètres de requête supplémentaires ; sinon, la valeur par défaut est None. ^[1]

Étape 6. Analysez la réponse. Un appel réussi renvoie les détails du minuteur en cours d'exécution pour ce ticket. Si aucun minuteur n'est actif, l'API retournera généralement un résultat vide ou un indicateur de statut approprié — gérez les deux cas dans votre code. ^[1]

Étape 7. Si vous avez également besoin de l'enregistrement complet du minuteur (pas seulement le minuteur actif), utilisez plutôt l'endpoint complémentaire :

GET /api/v1/tickets/{ticketId}/timer

Celui-ci récupère les données générales du minuteur du ticket, qu'il soit actuellement en cours d'exécution ou non. ^[3]

Étape 8. Pour modifier le minuteur après l'avoir récupéré, utilisez l'endpoint PATCH :

PATCH /api/v1/tickets/{ticketId}/timer

Passez vos modifications sous forme de dictionnaire data dans le corps de la requête. ^[2]

Étape 9. Si vous avez besoin de démarrer un nouveau minuteur depuis le début, utilisez l'endpoint de démarrage dédié :

POST /api/v1/tickets/{ticketId}/timer/start

Fournissez les champs requis dans le paramètre de corps data. ^[5]

Erreurs courantes

• Jeton d'accès manquant ou expiré. Si le access_token est absent ou périmé, chaque appel API échouera avec une erreur d'authentification. Vérifiez toujours que le jeton est renouvelé avant d'effectuer des requêtes sur les minuteurs. ^[6]
• orgid incorrect ou manquant. Les appels à l'API Zoho Desk nécessitent que l'identifiant d'organisation soit défini sur le client. Si deskorg_id n'est pas stocké, le client doit le découvrir automatiquement en appelant d'abord l'endpoint des organisations ; sans cela, les requêtes peuvent retourner des erreurs de permission ou de routage. ^[7]
• Scopes OAuth insuffisants. Les endpoints de minuteurs relèvent des permissions de tickets. Si Desk.tickets.READ ou Desk.tickets.ALL n'a pas été inclus lors de l'autorisation de la connexion OAuth, l'appel sera rejeté même avec un jeton valide. ^[8]
• Aucun minuteur actif n'existe. L'endpoint activeTimer est spécifique aux minuteurs en cours d'exécution. Si aucun minuteur n'est actuellement actif sur le ticket, ne supposez pas qu'il s'agit d'une erreur — vérifiez le corps de la réponse avant de le traiter comme un échec. ^[1]

Ce qu'il faut vérifier

• Confirmez que votre jeton OAuth possède au moins le scope Desk.tickets.READ et qu'il n'a pas expiré avant d'effectuer la requête. ^[8]
• Vérifiez que le ticketId que vous passez est correct et appartient à la même organisation Zoho Desk contre laquelle votre client est authentifié. [^1, ^7]
• Si la réponse est vide, effectuez une vérification croisée en utilisant GET /api/v1/tickets/{ticketId}/timer pour confirmer si un enregistrement de minuteur existe pour ce ticket. ^[3]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho.*