Comment récupérer l'historique d'un ticket dans Zoho Desk

La récupération de l'historique d'un ticket dans Zoho Desk s'effectue via un endpoint API dédié qui renvoie un journal chronologique de toutes les modifications apportées à un ticket donné. Chez Beam Help — support expert indépendant pour Zoho (et non le support officiel de Zoho) — nous vous guidons pas à pas pour effectuer cet appel et vous assurer que tout est bien en place au préalable.

Pourquoi c'est important

Lorsqu'un ticket de support passe entre plusieurs agents, fait l'objet de changements de statut ou de mises à jour de priorité, vous avez besoin d'une piste d'audit fiable pour comprendre ce qui s'est passé et à quel moment. L'endpoint d'historique de ticket vous fournit cet enregistrement complet de manière programmatique, ce qui le rend utile pour les rapports, les contrôles de conformité ou le débogage d'états de tickets inattendus. Si vous construisez une intégration ou une automatisation sur Zoho Desk, c'est souvent l'une des premières données que vous souhaiterez exposer.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth sont correctement configurés.

Avant d'effectuer tout appel API, votre application connectée doit disposer des autorisations appropriées. Pour l'historique des tickets en particulier, vous avez besoin au minimum du scope Desk.tickets.READ autorisé sur votre client OAuth. Un accès plus large peut être accordé avec Desk.tickets.ALL, qui couvre les opérations de lecture, écriture, création, mise à jour et suppression sur les tickets. ^[2]

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

Votre intégration s'authentifie via OAuth 2.0. Si votre jeton d'accès actuel a expiré, vous devez le renouveler en envoyant une requête POST à l'endpoint de jeton Zoho avec votre clientid, clientsecret et refreshtoken en utilisant granttype: refreshtoken. Une réponse réussie renvoie un nouvel accesstoken accompagné d'une valeur expiresin (généralement 3600 secondes) que vous devez stocker avec un horodatage tokenexpires_at calculé afin de savoir quand effectuer le prochain renouvellement. ^[8]

Étape 3. Identifiez l'identifiant de votre organisation (org_id).

Les appels à l'API Zoho Desk nécessitent un en-tête orgId pour acheminer les requêtes vers le bon portail. Si vous ne l'avez pas encore enregistré, vous pouvez le découvrir en appelant l'endpoint des organisations et en lisant le champ id du premier élément du tableau data renvoyé. Une fois récupéré, persistez-le afin de ne pas avoir à le rechercher à chaque requête. ^[4]

Étape 4. Appelez l'endpoint d'historique du ticket.

Envoyez une requête GET authentifiée vers le chemin suivant, en remplaçant l'identifiant réel du ticket :

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

Le nom de l'opération pour cet appel est gettickethistory. Vous passez le ticket_id en tant que paramètre de chemin. Un paramètre optionnel p peut être fourni sous forme de dictionnaire de requête à des fins de pagination ou de filtrage. ^[3]

Voici un exemple minimal en Python :

# Assuming `client` is an initialised ZohoDeskClient
history = client.request("GET", f"/api/v1/tickets/{ticket_id}/history", p, None)

Où p est soit None, soit un dictionnaire de paramètres de requête supplémentaires. ^[3]

Étape 5. Accédez au ticket dans l'interface Zoho Desk (vérification optionnelle).

Si vous souhaitez comparer la réponse de l'API avec ce qui est visible dans le navigateur, le modèle d'URL directe pour une page de détail de ticket suit cette structure :

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{ticket_id}

Remplacez {dc} par le suffixe de votre centre de données (par ex., com, eu, in), {portal} par le nom de votre portail ou l'identifiant de votre organisation, et {ticket_id} par l'identifiant numérique du ticket. ^[7]

Erreurs courantes

• orgId manquant ou incorrect : Si l'org_id est vide ou erroné, l'API ne pourra pas acheminer votre requête vers le bon portail Desk. Vérifiez toujours qu'il est enregistré et non vide avant d'effectuer des appels liés aux tickets. ^[4]
• Scopes OAuth insuffisants : Demander l'historique avec uniquement des scopes d'écriture ou de création entraînera une erreur d'autorisation. Assurez-vous que Desk.tickets.READ ou Desk.tickets.ALL est explicitement inclus dans votre chaîne de scopes. ^[2]
• Jeton d'accès expiré : Les jetons expirent après environ une heure. Si vous recevez une erreur d'authentification, vérifiez votre valeur tokenexpiresat et déclenchez un renouvellement avant de réessayer. ^[8]
• Mauvais domaine de centre de données : Zoho opère sur plusieurs centres de données régionaux. Si votre compte se trouve sur le centre de données EU ou IN, l'URL de base de votre API et l'URL du jeton OAuth doivent utiliser le suffixe régional correspondant, et non le domaine .com par défaut. ^[7]

Ce qu'il faut vérifier

• Confirmez que Desk.tickets.READ (ou Desk.tickets.ALL) apparaît dans votre liste de scopes OAuth autorisés avant d'effectuer l'appel. ^[2]
• Vérifiez qu'un accesstoken valide et non expiré ainsi qu'un deskorg_id non vide sont tous deux présents dans votre enregistrement de connexion avant d'appeler l'endpoint d'historique. ^[4]
• Comparez au moins une entrée d'historique de la réponse API avec le journal d'activité du ticket dans l'interface agent de Zoho Desk pour confirmer que les données sont correctement renvoyées. ^[7]