Comment lister les activités d'un ticket dans Zoho Desk

Lister les activités d'un ticket dans Zoho Desk est simple dès lors que vous disposez du bon endpoint et des bons scopes OAuth — une seule requête GET sur la sous-ressource activities renvoie le journal d'activité complet de n'importe quel ticket.

Pourquoi c'est important

Chaque ticket de support accumule un historique de changements de statut, d'affectations d'agents et d'autres événements système. Récupérer cet historique par programmation vous permet d'auditer l'historique des tickets, de créer des tableaux de bord personnalisés ou d'alimenter des workflows en aval avec des données d'activité. Si vous intégrez Zoho Desk avec un système externe, cet endpoint est la méthode canonique pour extraire ces informations sans avoir à scraper l'interface.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth incluent l'accès aux tickets.

Avant d'effectuer tout appel API, vérifiez que votre application connectée s'est vu accorder le scope Desk.tickets.READ (au minimum). Un accès plus large tel que Desk.tickets.ALL satisfait également cette exigence. Ces scopes doivent être déclarés lors de l'enregistrement de votre client OAuth et de l'autorisation de la connexion. ^[2]

Étape 2. Récupérez votre identifiant d'organisation.

L'API de Zoho Desk requiert un en-tête orgId sur chaque requête. Si vous n'avez pas encore enregistré cette valeur, appelez l'endpoint des organisations pour la récupérer. La première organisation renvoyée dans le tableau de réponse peut être utilisée comme orgId de travail, et vous devriez la persister afin de ne pas avoir à la rechercher à chaque appel. ^[8]

Étape 3. Identifiez l'identifiant du ticket cible.

Vous avez besoin du ticketId numérique du ticket dont vous souhaitez lister les activités. Vous pouvez l'obtenir à partir d'un appel de recherche ou de consultation de ticket préalable, ou directement depuis l'URL de l'interface agent de Zoho Desk, qui suit le modèle https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. ^[3]

Étape 4. Appelez l'endpoint de liste des activités du ticket.

Émettez une requête HTTP GET vers :

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

Remplacez {ticketId} par l'identifiant réel du ticket obtenu à l'étape 3. La requête accepte un paramètre optionnel p pour la pagination ou le filtrage. Incluez votre jeton d'accès dans l'en-tête Authorization et votre orgId dans l'en-tête orgId. ^[4]

Voici un exemple minimal en Python :

# Assuming `desk_api` is an initialised ZohoDeskApi instance
activities = desk_api.list_ticket_activities(ticketId="98765", p=None)
print(activities)

La méthode déclenche en interne GET /api/v1/tickets/98765/activities et renvoie la réponse analysée. ^[4]

Étape 5. Gérez la pagination si nécessaire.

Le paramètre p accepte des arguments de pagination. Si le ticket possède un long historique, passez les valeurs de page ou de limite appropriées dans ce dictionnaire pour parcourir tous les résultats. ^[4]

Étape 6. (Optionnel) Faites le lien avec les tâches.

Les activités et les tâches sont des ressources distinctes dans Zoho Desk. Si vous avez également besoin des enregistrements de tâches associés au ticket, utilisez l'endpoint dédié :

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

Celui-ci renvoie des objets de tâche plutôt que le journal d'activité ; gardez donc les deux appels séparés selon les besoins de votre intégration. ^[7]

Erreurs courantes

• En-tête orgId manquant. Zoho Desk rejette les requêtes qui n'incluent pas un identifiant d'organisation valide. Si votre orgId enregistré est vide, déclenchez le flux de découverte automatique via l'endpoint des organisations avant de réessayer. ^[8]
• Scopes insuffisants. Demander des activités avec uniquement Desk.basic.READ entraînera une erreur d'autorisation. Assurez-vous que Desk.tickets.READ ou Desk.tickets.ALL est présent dans votre chaîne de scopes. ^[2]
• Confusion entre activités et tâches. Les sous-ressources /activities et /tasks ne sont pas interchangeables. Les activités capturent des événements d'audit générés par le système ; les tâches sont des éléments d'action créés par les utilisateurs. Appeler le mauvais endpoint renverra un ensemble de résultats vide ou non pertinent. ^[4][7]
• Jetons d'accès expirés. Les jetons d'accès Zoho ont une durée de vie limitée. Votre intégration doit implémenter un flux de renouvellement de jeton qui échange le jeton de rafraîchissement enregistré contre un nouveau jeton d'accès chaque fois qu'une réponse 401 est reçue. ^[8]

Points à vérifier

• Liste des scopes : Confirmez que Desk.tickets.READ (ou Desk.tickets.ALL) apparaît dans la chaîne de scopes OAuth utilisée lors de l'autorisation. ^[2]
• Identifiant de ticket correct : Vérifiez que le ticketId dans votre requête correspond à un ticket réel dans votre organisation Zoho Desk — une discordance renverra une erreur 404 ou un tableau d'activités vide. ^[4]
• Persistance de l'identifiant d'organisation : Après le premier appel de découverte d'organisation réussi, confirmez que l'orgId est sauvegardé afin que les requêtes suivantes n'engendrent pas un aller-retour supplémentaire. ^[8]

---

*Beam Help fournit une assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référez-vous toujours à la documentation de l'API Zoho Desk pour les dernières spécifications des endpoints.*