Comment récupérer le statut d'un ticket dans Zoho Desk

Récupérer le statut actuel d'un ticket dans Zoho Desk est simple une fois votre connexion OAuth en place — une seule requête GET vers l'endpoint de statut du ticket retourne les informations dont vous avez besoin.

Pourquoi c'est important

Les équipes de support et les workflows d'automatisation ont fréquemment besoin de vérifier si un ticket est ouvert, en attente, escaladé ou résolu avant de décider de la prochaine action. L'accès programmatique au statut des tickets vous permet de créer des tableaux de bord, de déclencher des notifications ou de conditionner des processus en aval sans parcourir manuellement l'interface Zoho Desk. En tant qu'expert indépendant pour Zoho (et non le support officiel de Zoho), Beam Help vous guide à travers les étapes exactes ci-dessous.

Étape par étape

Étape 1. Assurez-vous que vos scopes OAuth incluent l'accès en lecture aux tickets.

Avant qu'un appel API puisse réussir, votre application connectée doit être autorisée avec les scopes OAuth Zoho Desk appropriés. Vous avez au minimum besoin de Desk.tickets.READ ; les intégrations plus larges incluent généralement aussi Desk.tickets.ALL pour couvrir les opérations d'écriture ultérieures. Ces scopes doivent être demandés lors du flux d'autorisation OAuth et stockés avec votre jeton d'accès. ^[2]

Étape 2. Obtenez un jeton d'accès valide (et actualisez-le lorsqu'il expire).

Votre intégration doit conserver un refreshtoken issu de l'autorisation OAuth initiale. Lorsque l'accesstoken a expiré, appelez l'endpoint de jeton Zoho en utilisant le jeton de rafraîchissement pour en obtenir un nouveau. La réponse actualisée contiendra un nouvel accesstoken et une valeur expiresin (généralement 3600 secondes) que vous devez persister afin de savoir quand actualiser à nouveau. ^[8]

Étape 3. Identifiez l'ID d'organisation de votre Zoho Desk.

Chaque appel à l'API Zoho Desk nécessite un en-tête orgId. Si vous ne l'avez pas encore stocké, appelez l'endpoint des organisations après avoir initialisé votre client Desk. La réponse retourne un tableau data ; prenez le champ id du premier élément comme identifiant d'organisation et persistez-le afin de ne pas avoir à le rechercher à chaque requête. ^[6]

Étape 4. Appelez l'endpoint de statut du ticket.

Envoyez une requête GET authentifiée vers :

GET /api/v1/tickets/{ticket_id}/status

Remplacez {ticket_id} par l'identifiant numérique ou textuel du ticket que vous souhaitez inspecter. Passez éventuellement des paramètres de requête dans le dictionnaire p si vous avez besoin de filtrer ou de paginer la réponse. Le modèle d'appel en Python ressemble à ceci : ^[3]

status = desk_api.get_ticket_status(ticket_id="123456")

Le corps de la réponse contiendra les détails du statut actuel de ce ticket. ^[3]

Étape 5. (Optionnel) Mettez à jour le statut si nécessaire.

Si votre workflow nécessite de modifier le statut après l'avoir lu, utilisez l'endpoint PATCH associé à la place :

PATCH /api/v1/tickets/{ticket_id}/status

Passez les nouvelles valeurs de statut souhaitées dans le dictionnaire data. Il s'agit d'une opération distincte de la lecture et elle nécessite Desk.tickets.UPDATE ou Desk.tickets.ALL dans vos scopes. ^{[7] [2]}

---

Erreurs courantes

• En-tête orgId manquant. Zoho Desk rejette les requêtes qui n'incluent pas un ID d'organisation valide. Si vous obtenez une réponse 400 ou 403, vérifiez que l'ID d'organisation a bien été récupéré et attaché à chaque requête. ^[6]
• Jeton d'accès expiré non actualisé. Si votre logique de rafraîchissement de jeton ne vérifie pas tokenexpiresat avant chaque appel, vous recevrez des erreurs 401. Comparez toujours l'horodatage actuel avec l'expiration stockée et actualisez de manière proactive. ^[8]
• Scopes insuffisants. Demander uniquement Desk.tickets.WRITE sans Desk.tickets.READ bloquera l'appel GET. Assurez-vous que Desk.tickets.READ (ou Desk.tickets.ALL) est présent dans votre liste de scopes autorisés. ^[2]
• Mauvais type d'entité dans les liens de secours. Si votre couche d'interface construit des liens de navigation et que le type d'entité n'est pas explicitement "ticket", le lien de secours peut rediriger les utilisateurs vers la page d'accueil générique de Desk plutôt que vers la liste des tickets — vérifiez les valeurs du type d'entité dans toute logique de construction de liens. ^[1]

---

Ce qu'il faut vérifier

• Les scopes sont actifs : Confirmez que Desk.tickets.READ apparaît dans la liste des scopes accordés pour votre client OAuth avant d'effectuer le premier appel. ^[2]
• Le jeton est à jour : Vérifiez que tokenexpiresat est dans le futur et que votre routine de rafraîchissement met à jour à la fois accesstoken et tokenexpires_at dans le stockage persistant après chaque actualisation. ^[8]
• ID de ticket correct : Confirmez que le ticket_id que vous transmettez correspond à un ticket existant dans votre organisation ; un ID incorrect retournera une erreur 404 plutôt qu'un objet de statut. ^[3]