Comment lister les tickets par compte dans Zoho Desk

Lister les tickets associés à un compte spécifique dans Zoho Desk est simple dès lors que vous disposez du bon identifiant de compte et des bons périmètres OAuth. Ce guide présente l'endpoint exact et les étapes de configuration utilisés par notre équipe.

Pourquoi c'est important

Lors de la gestion du support entreprise, vous avez souvent besoin de consulter tous les tickets ouverts ou historiques liés à une seule société plutôt qu'à un contact individuel. Récupérer les tickets par compte offre aux responsables du support une vue consolidée de l'ensemble de l'historique d'assistance d'une organisation cliente, ce qui accélère considérablement les décisions d'escalade et les révisions de SLA.

Étape par étape

Étape 1. Vérifiez que vos périmètres OAuth incluent l'accès aux tickets et aux comptes Desk.

Avant d'effectuer tout appel API, vérifiez que votre token OAuth Zoho Desk connecté a été accordé au minimum avec les périmètres Desk.tickets.READ et Desk.contacts.READ. Sans ceux-ci, la requête sera rejetée au niveau de la couche d'autorisation. Notre équipe recommande également d'inclure Desk.tickets.ALL afin que les opérations d'écriture soient disponibles si nécessaire ultérieurement. ^[2]

Étape 2. Identifiez l'identifiant du compte que vous souhaitez interroger.

Accédez à votre portail Zoho Desk et ouvrez la section Comptes. Ouvrez l'enregistrement du compte concerné et copiez l'identifiant numérique depuis l'URL ou le panneau de détail de l'enregistrement. Il s'agit de la valeur account_id que vous transmettrez à l'endpoint. Si vous travaillez de manière programmatique, vous pouvez également le récupérer en accédant à la liste des comptes via le chemin /accounts de votre portail. ^[1]

Étape 3. Appelez l'endpoint de listage des tickets par compte.

Envoyez une requête GET vers le chemin suivant, en remplaçant l'identifiant de compte par le vôtre :

GET /api/v1/accounts/{account_id}/tickets

L'opération est nommée listticketsby_account. Elle accepte deux paramètres :

• account_id — l'identifiant numérique du compte (obligatoire, inclus dans le chemin de l'URL)
• p — un dictionnaire optionnel de paramètres de requête supplémentaires tels que la pagination ou les filtres

Un appel Python minimal ressemble à ceci :

def list_tickets_by_account(self, account_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/accounts/{account_id}/tickets", p, None)

^[3]

Étape 4. Assurez-vous que votre client Desk dispose d'un orgId valide.

Zoho Desk exige un identifiant d'organisation (orgId) pour chaque requête API. Si votre intégration n'a pas encore enregistré cette valeur, le client peut la découvrir automatiquement en appelant l'endpoint des organisations lors de la première utilisation. L'identifiant découvert est ensuite persisté afin que les appels suivants — y compris listticketsby_account — transmettent automatiquement le bon en-tête. ^[5][8]

Étape 5. Analysez et affichez la liste de tickets retournée.

La réponse sera un objet JSON contenant les enregistrements de tickets pour ce compte. Les champs clés à présenter aux utilisateurs finaux incluent le sujet du ticket, le statut, l'agent assigné et la date de création. Omettez les champs d'identifiant internes dans tout affichage destiné aux utilisateurs afin de garder le résultat lisible. ^[6]

Étape 6. Construisez un lien direct vers le portail pour chaque ticket (optionnel).

Si vous souhaitez fournir aux agents un lien cliquable vers chaque ticket, construisez l'URL selon le modèle suivant :

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

Remplacez {dc} par le suffixe de votre centre de données (par ex., com, eu), {portal} par le nom de votre portail ou l'identifiant de l'organisation, et {TicketId} par l'identifiant issu de la réponse API. ^[4]

---

Erreurs courantes

• En-tête orgId manquant. Si le client Desk est initialisé sans identifiant d'organisation, toutes les requêtes — y compris les recherches de tickets par compte — échoueront. Assurez-vous que le processus de découverte automatique a été exécuté au moins une fois et que l'identifiant a été persisté. ^[5][8]
• Périmètres insuffisants. La récupération des tickets nécessite au minimum Desk.tickets.READ. Si votre token a été émis uniquement avec Desk.basic.READ, l'endpoint retournera une erreur d'autorisation. Réautorisez avec l'ensemble complet des périmètres. ^[2]
• Mauvais centre de données. L'URL de base doit correspondre au centre de données où votre portail Zoho Desk est hébergé. Utiliser desk.zoho.com pour un portail hébergé en Europe échouera ; utilisez plutôt desk.zoho.eu. ^[4]

---

Points à vérifier

• Confirmez que l'account_id dans votre requête correspond à un compte existant dans Zoho Desk — un identifiant incorrect retournera un résultat vide ou une erreur 404 plutôt qu'un message d'erreur explicite.
• Vérifiez que le token OAuth utilisé dispose bien des périmètres Desk.tickets.READ et Desk.contacts.READ avant de passer en production. ^[2]
• Après le premier appel réussi, vérifiez que le deskorgid a été enregistré dans votre enregistrement de connexion afin que les requêtes futures n'aient pas besoin de le redécouvrir. ^[8]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, soumettez toujours un ticket directement auprès de Zoho.*