Comment récupérer un minuteur de ticket dans Zoho Desk

Récupérer un minuteur de ticket dans Zoho Desk est simple grâce à l'API REST — vous pouvez obtenir soit l'enregistrement complet du minuteur, soit uniquement le minuteur en cours d'exécution (actif) pour n'importe quel ticket donné.

Pourquoi c'est important

Lorsque votre équipe support suit le temps passé sur les tickets, vous pouvez avoir besoin de lire les données du minuteur de manière programmatique — pour des tableaux de bord de reporting, des intégrations de facturation ou des workflows d'automatisation. Zoho Desk expose des endpoints dédiés pour le minuteur complet et le minuteur actif, vous permettant de choisir le bon selon que vous avez besoin d'un instantané de tout le temps enregistré ou uniquement de ce qui est en cours. En tant que support expert indépendant (et non le support officiel de Zoho), Beam Help vous guide à travers les deux options ci-dessous.

---

Étape par étape

Étape 1. Authentifiez-vous et obtenez un jeton d'accès valide.

Avant d'appeler un endpoint Zoho Desk, votre intégration doit disposer d'un jeton d'accès OAuth 2.0 valide. Si votre jeton a expiré, le système utilisera votre jeton de rafraîchissement stocké pour en demander un nouveau automatiquement — le mécanisme de rafraîchissement échange le refreshtoken contre l'URL du jeton en utilisant votre clientid et votre clientsecret, puis stocke l'accesstoken mis à jour ainsi que son horodatage d'expiration pour les appels futurs. ^[8]

Étape 2. Initialisez le client API Zoho Desk.

Instanciez un ZohoDeskClient avec votre domaine API, votre jeton d'accès actuel et votre identifiant d'organisation (orgid). Encapsulez-le dans une instance ZohoDeskApi. Si votre orgid n'est pas encore stocké, le client peut le découvrir automatiquement en appelant l'endpoint des organisations et en conservant le premier résultat. ^[7]

Étape 3. Récupérez le minuteur complet du ticket.

Appellez l'endpoint GET /api/v1/tickets/{ticketId}/timer, en remplaçant {ticketId} par l'identifiant réel du ticket. En Python, cela ressemble à ceci :

result = api.get_ticket_timer(ticketId="your_ticket_id")

La méthode envoie une requête GET vers /api/v1/tickets/{ticketId}/timer et retourne l'enregistrement du minuteur associé à ce ticket. Un paramètre optionnel p peut transporter des arguments de chaîne de requête supplémentaires si nécessaire. ^[1]

Étape 4. (Alternative) Récupérez uniquement le minuteur actif.

Si vous souhaitez uniquement obtenir un minuteur en cours d'exécution — par exemple pour afficher un indicateur de temps écoulé en direct — utilisez plutôt l'endpoint du minuteur actif :

result = api.get_active_timer_for_a(ticketId="your_ticket_id")

Cela envoie une requête GET vers /api/v1/tickets/{ticketId}/activeTimer et retourne les données exclusivement pour le minuteur qui est actuellement en cours d'exécution. ^[2]

Étape 5. Traitez la réponse.

Les deux endpoints retournent un dictionnaire. Inspectez le résultat pour les champs du minuteur tels que la durée, le statut et les détails de l'agent. Si le ticket n'a pas de minuteur actif lorsque vous appelez l'endpoint activeTimer, attendez-vous à un payload de données vide ou nul plutôt qu'une erreur.

---

Erreurs courantes

• orgid manquant ou obsolète : Zoho Desk exige que l'identifiant d'organisation soit transmis en tant qu'en-tête ou paramètre à chaque requête. Si orgid est vide, le client tentera une découverte automatique, mais cela ajoute de la latence. Persistez toujours l'org_id après le premier appel réussi. ^[7]

• Jetons d'accès expirés : Les jetons expirent généralement après 3 600 secondes. Si vous recevez une erreur d'authentification, vérifiez que votre logique de rafraîchissement de jeton met correctement à jour à la fois l'accesstoken et le tokenexpires_at dans votre stockage de données. ^[8]

• Confusion entre les deux endpoints de minuteur : GET .../timer retourne l'enregistrement complet du minuteur (y compris les données historiques), tandis que GET .../activeTimer retourne uniquement ce qui est en cours d'exécution. ^[1][2] Utiliser le mauvais peut entraîner des réponses vides qui ressemblent à des erreurs.

• Mise à jour ou réinitialisation accidentelle : Si vous avez besoin d'un accès en lecture seule, veillez à ne pas appeler accidentellement PATCH /api/v1/tickets/{ticketId}/timer (qui modifie le minuteur) ^[4] ou POST /api/v1/tickets/{ticketId}/timer/reset (qui le réinitialise entièrement). ^[6] Gardez votre méthode HTTP strictement en GET pour la récupération.

---

Ce qu'il faut vérifier

• Confirmez que le ticketId est valide — vérifiez qu'il existe dans votre portail Zoho Desk avant d'effectuer l'appel API, car un identifiant invalide retournera une erreur « introuvable » plutôt que des données de minuteur.
• Vérifiez vos scopes OAuth — assurez-vous que le jeton d'accès a été accordé avec le scope de lecture du suivi du temps Desk ; des scopes manquants produiront une erreur de permissions même avec un jeton valide. ^[5]
• Inspectez la structure de la réponse — confirmez que le dictionnaire retourné contient les champs de minuteur attendus avant de transmettre les données en aval, car un ticket inactif peut retourner un objet minuteur minimal ou vide. ^[1][2]