La récupération d'un ticket unique dans Zoho Desk via l'API nécessite une connexion OAuth valide, le scope approprié et l'identifiant unique du ticket — une fois ces trois éléments réunis, l'appel est simple.
Pourquoi c'est important
Lorsque vous devez afficher, auditer ou traiter un ticket d'assistance spécifique — plutôt que de parcourir une liste paginée — le récupérer par son ID est l'approche la plus efficace. C'est le schéma utilisé chaque fois qu'un utilisateur fait référence directement à un ticket, par exemple « obtenir le ticket 12345 ». [5] Cela évite les transferts de données inutiles et maintient votre intégration rapide et prévisible.
Étape par étape
Étape 1. Vérifiez que vos scopes OAuth incluent l'accès en lecture aux tickets.
Avant d'effectuer tout appel API, vérifiez que votre application connectée a été autorisée avec au minimum le scope Desk.tickets.READ. Un scope plus large Desk.tickets.ALL couvre également cette opération. [2] Sans l'un de ces scopes, l'API Zoho Desk rejettera la requête avec une erreur d'autorisation.
Étape 2. Obtenez un jeton d'accès valide pour l'utilisateur.
Votre intégration doit récupérer la connexion stockée pour l'utilisateur concerné et vérifier si le jeton d'accès est toujours valide. Les jetons doivent être renouvelés de manière proactive — une bonne règle est de les renouveler environ 120 secondes avant leur expiration afin d'éviter les erreurs 401 en cours de requête. [7] Si le jeton a expiré, utilisez le jeton de rafraîchissement stocké pour obtenir un nouveau jeton d'accès depuis l'endpoint OAuth de Zoho, puis persistez le jeton mis à jour et son nouvel horodatage d'expiration dans votre magasin de données. [7]
Étape 3. Initialisez le client API Zoho Desk.
Une fois un jeton d'accès actif en main, instanciez un ZohoDeskClient en utilisant le domaine API de l'utilisateur, le jeton d'accès et l'identifiant d'organisation (orgid). Encapsulez ce client dans une instance ZohoDeskApi. [3] Le orgid est requis pour chaque appel à l'API Zoho Desk — s'il n'est pas déjà stocké pour l'utilisateur, vous pouvez le découvrir en appelant l'endpoint des organisations et en persistant le champ id du premier résultat. [3]
Étape 4. Appelez l'outil getaticket avec l'ID du ticket.
Déclenchez l'opération de récupération du ticket en passant l'identifiant numérique du ticket cible comme paramètre ticketid. Dans un contexte planificateur/assistant, cela correspond à l'outil nommé getaticket avec un objet params tel que {"ticketid": "12345"}. [5] Le client API attachera automatiquement l'en-tête orgId et l'en-tête Authorization: Bearer <token>. [3]
Étape 5. Traitez la réponse et mettez en avant les champs clés.
Une fois la réponse reçue, présentez les champs pertinents à l'utilisateur final. Les champs recommandés à afficher incluent le sujet du ticket, le statut, l'agent/propriétaire assigné et les coordonnées du contact. [8] Ignorez les valeurs vides et les identifiants système internes pour garder le résultat lisible. [8]
Étape 6. Fournissez un lien de navigation de secours si l'enregistrement ne peut pas être résolu.
Si l'API ne renvoie aucune donnée ou retourne une erreur, redirigez vers un lien direct pointant vers la vue liste des tickets au chemin /tickets dans la racine de votre portail Desk. [1] Cela offre à l'utilisateur une sortie manuelle sans impasse.
Pièges courants
org_idmanquant : Zoho Desk exige l'identifiant d'organisation pour chaque requête. Si cette valeur est vide ou constituée d'espaces, le client échouera silencieusement ou retournera une erreur 400. Nettoyez toujours la valeur stockée et déclenchez la découverte automatique si elle est vide. [3]- Jeton d'accès périmé : Si votre logique de renouvellement de jeton ne s'exécute pas avant l'expiration du jeton, vous recevrez des réponses 401. Intégrez la marge de renouvellement anticipé (environ 120 secondes avant expiration) pour éviter cela. [7]
- Scope insuffisant : Demander un ticket avec uniquement
Desk.basic.READdans votre ensemble de scopes ne fonctionnera pas. Assurez-vous queDesk.tickets.READouDesk.tickets.ALLest explicitement inclus dans votre autorisation OAuth. [2] apptypeincorrect : Si votre intégration prend en charge à la fois Zoho CRM et Zoho Desk, assurez-vous de passerapptype = "desk"lors de l'initialisation du client API — utiliser le client CRM contre les endpoints Desk produira des erreurs inattendues. [3]
Ce qu'il faut vérifier
- Liste des scopes : Confirmez que
Desk.tickets.READ(ouDesk.tickets.ALL) apparaît dans les scopes autorisés de votre client OAuth. [2] - Identifiant d'organisation stocké : Vérifiez qu'un
deskorgidnon vide est persisté pour l'utilisateur dans votre table de connexions avant d'effectuer l'appel. [3] - Fraîcheur du jeton : Vérifiez que la valeur
tokenexpiresatstockée est dans le futur (avec une marge d'au moins 120 secondes) ou que votre logique de renouvellement l'a déjà mise à jour. [7]
---
*Beam Help fournit des conseils d'experts indépendants sur les produits Zoho. Nous ne sommes pas le support officiel de Zoho — pour les questions de facturation ou de compte, contactez Zoho directement.*