Comment lister tous les tickets dans Zoho Desk

Lister tous les tickets dans Zoho Desk est simple via l'API REST — une seule requête GET vers l'endpoint tickets renvoie votre liste complète de tickets, à condition que votre token OAuth dispose des scopes appropriés.

Pourquoi c'est important

Lorsque vous avez besoin d'une vue programmatique de tous les tickets d'assistance de votre portail Zoho Desk — pour des rapports, un traitement en masse ou des travaux d'intégration — vous devez appeler l'endpoint de liste dédié plutôt que de vous fier aux exports manuels depuis l'interface. Configurer correctement les scopes d'authentification et l'ID d'organisation dès le départ permet d'économiser un temps de débogage considérable. Ce guide est produit par Beam Help, support expert indépendant pour Zoho (et non le support officiel de Zoho).

Étape par étape

Étape 1. Assurez-vous que votre token OAuth inclut les scopes Zoho Desk nécessaires avant d'effectuer tout appel API. Vous avez besoin au minimum de Desk.tickets.READ ; pour une capacité complète de création/mise à jour/suppression, vous devrez également inclure Desk.tickets.ALL, Desk.tickets.WRITE, Desk.tickets.CREATE, Desk.tickets.UPDATE et Desk.tickets.DELETE. ^[2]

Étape 2. Vérifiez que l'ID d'organisation Desk (orgId) est disponible. Lorsqu'un client API Zoho Desk est initialisé, le système tente de découvrir automatiquement l'ID d'organisation en appelant l'endpoint des organisations si celui-ci n'a pas déjà été enregistré. L'ID découvert est ensuite persisté et joint aux requêtes suivantes sous forme d'en-tête orgId. Si vous effectuez cette configuration manuellement, récupérez votre ID d'organisation depuis le panneau d'administration Zoho Desk ou via l'endpoint des organisations, puis stockez-le pour le réutiliser. ^[8]

Étape 3. Envoyez la requête HTTP suivante pour lister tous les tickets :

GET /api/v1/tickets

Passez les éventuels paramètres de chaîne de requête dans la requête (représentés par p dans l'implémentation client) pour filtrer ou paginer les résultats — par exemple, le numéro de page ou l'ordre de tri. Le nom de l'opération pour cet appel est listalltickets. ^[4]

Étape 4. Analysez la réponse. L'API renvoie les enregistrements de tickets dans une charge utile structurée. Lors de l'affichage des résultats aux utilisateurs, concentrez-vous sur les champs clés tels que le sujet du ticket, le statut, l'agent assigné et le nom du contact — ignorer les identifiants internes et les valeurs vides rend la sortie plus lisible. ^[5]

Étape 5. Pour accéder directement à un ticket spécifique dans l'interface web Zoho Desk, construisez une URL de lien profond en utilisant 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, in), {portal} par le nom de votre portail, et {TicketId} par l'ID du ticket issu de la réponse API. Si vous avez uniquement besoin de la vue générale de la liste des tickets plutôt que d'un enregistrement spécifique, l'URL de repli suit le modèle {deskrecordsroot}/tickets. ^{[3] [1]}

Étape 6. Pour les workflows conversationnels ou pilotés par un assistant, l'outil approprié à invoquer pour une demande de liste générale (par ex. « montrez-moi tous les tickets ») est listalltickets, tandis que les requêtes filtrées telles que « afficher les tickets ouverts » doivent être acheminées vers search_tickets avec un paramètre de statut approprié. ^[6]

Erreurs courantes

• En-tête orgId manquant. Zoho Desk exige l'ID d'organisation sur chaque requête API. S'il est absent ou incorrect, les appels échoueront avec une erreur d'autorisation ou d'introuvable. Vérifiez toujours que l'ID d'organisation est bien injecté dans le client avant d'effectuer des appels de tickets. ^[8]
• Scopes OAuth insuffisants. Demander des tickets avec uniquement Desk.basic.READ ne fonctionnera pas — vous devez explicitement inclure Desk.tickets.READ ou Desk.tickets.ALL dans votre chaîne de scopes. Les scopes sont séparés par des virgules et doivent être déclarés au moment de la génération du token. ^[2]
• Mauvais domaine de centre de données. Si votre compte Zoho est sur le centre de données EU ou IN, l'URL de base change de https://desk.zoho.com à https://desk.zoho.eu ou https://desk.zoho.in respectivement. Utiliser le mauvais domaine entraînera des échecs d'authentification. ^[3]
• Confusion entre liste et recherche. Un simple GET /api/v1/tickets récupère tous les tickets, mais si vous avez besoin de résultats filtrés (par statut, assigné, plage de dates, etc.), vous devez utiliser l'endpoint de recherche à la place. Confondre ces deux approches peut renvoyer plus de données que prévu ou manquer des enregistrements. ^{[4] [6]}

Points à vérifier

• Scopes confirmés : Vérifiez que Desk.tickets.READ (au minimum) apparaît dans la liste des scopes de votre token OAuth actif avant d'appeler l'endpoint. ^[2]
• ID d'organisation présent : Confirmez que la valeur orgId est correctement stockée et envoyée avec chaque requête — vérifiez votre enregistrement de connexion ou journalisez les en-têtes sortants. ^[8]
• URL de base correcte pour votre région : Assurez-vous que le domaine API correspond à votre centre de données Zoho (zoho.com, zoho.eu, zoho.in, etc.) pour éviter des échecs de routage silencieux. ^[3]