Comment lister les tâches par ticket dans Zoho Desk

Lister les tâches associées à un ticket spécifique dans Zoho Desk est simple dès lors que vous connaissez le bon endpoint API et que vous disposez des scopes OAuth appropriés. Cet article vous guide pas à pas tout au long du processus.

---

*Beam Help — assistance experte indépendante pour Zoho. Nous ne sommes pas le support officiel de Zoho.*

---

Pourquoi c'est important

Lors de la gestion des workflows de support, les tâches sont souvent attachées directement aux tickets pour suivre les actions de suivi, les assignations internes ou les étapes d'escalade. Pouvoir récupérer par programmation toutes les tâches d'un ticket donné vous permet de créer des tableaux de bord, d'automatiser des rappels ou d'auditer les charges de travail sans avoir à naviguer manuellement dans l'interface Zoho Desk. Si vous intégrez Zoho Desk dans un outillage plus large, il s'agit de l'une des opérations de lecture les plus fréquemment nécessaires.

---

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut les scopes Desk corrects avant d'effectuer toute requête. Au minimum, votre token doit couvrir Desk.tasks.READ — bien qu'une couverture plus large telle que Desk.tasks.ALL soit également acceptable. Vous aurez également besoin de Desk.tickets.READ pour accéder au contexte du ticket parent. ^[3]

Étape 2. Identifiez le ticket_id du ticket dont vous souhaitez récupérer les tâches. Il s'agit de l'identifiant numérique que Zoho Desk attribue à chaque enregistrement de ticket. Vous pouvez le trouver dans l'URL du ticket dans le portail agent Desk, qui suit le modèle https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. ^[4]

Étape 3. Envoyez une requête GET vers l'endpoint suivant, en substituant votre identifiant de ticket réel :

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

Cette opération est identifiée en interne sous le nom listtasksbyticket. L'endpoint accepte deux paramètres : ticketid (obligatoire, l'identifiant unique du ticket) et p (optionnel, un dictionnaire pour la pagination ou des paramètres de requête supplémentaires). ^[2]

Étape 4. En Python, l'appel se présente comme suit :

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

Passez l'identifiant du ticket sous forme de chaîne de caractères, et fournissez les options de pagination ou de filtrage via le dictionnaire p. Si vous n'avez pas besoin de paramètres supplémentaires, passer None convient parfaitement. ^[2]

Étape 5. Analysez la réponse. L'API retournera une liste d'objets de tâches associés à ce ticket. Présentez les champs clés — tels que le sujet de la tâche, le responsable, la date d'échéance et le statut — à quiconque ou à tout système consommant les données. ^[8]

---

Erreurs courantes

• Scopes de tâches manquants. Si votre token OAuth a été généré sans Desk.tasks.READ ni Desk.tasks.ALL, l'API retournera une erreur d'autorisation. Vérifiez vos scopes enregistrés dans la console API Zoho et régénérez le token si nécessaire. ^[3]

• Format d'identifiant de ticket incorrect. Le paramètre ticket_id doit être passé sous forme de chaîne de caractères, et non d'entier. Passer un entier brut peut entraîner l'échec de la requête ou retourner des résultats inattendus. ^[2]

• Organisation ou portail non résolu. L'API Desk résout les requêtes par rapport à une organisation spécifique. Si votre connexion n'a pas encore découvert ou enregistré un deskorgid, les requêtes peuvent échouer silencieusement ou être acheminées vers le mauvais portail. Assurez-vous que votre enregistrement de connexion dispose d'un deskorgid valide avant d'appeler les endpoints liés aux tickets. ^[7]

• Pagination non gérée. Si un ticket comporte de nombreuses tâches, les résultats peuvent être paginés. Utilisez le paramètre p pour passer des tokens de page ou des valeurs de décalage afin de récupérer l'ensemble complet plutôt que la première page uniquement. ^[2]

---

Points à vérifier

• Scopes présents : Vérifiez que Desk.tasks.READ (ou Desk.tasks.ALL) et Desk.tickets.READ apparaissent dans la liste des scopes de votre token OAuth actif. ^[3]
• Chemin d'endpoint correct : Confirmez que l'URL de la requête pointe vers /api/v1/tickets/{ticket_id}/tasks avec un identifiant de ticket numérique réel substitué. ^[2]
• La réponse contient des enregistrements de tâches : Le payload retourné doit inclure une liste d'objets de tâches ; une liste vide peut signifier que le ticket ne possède genuinement aucune tâche, tandis qu'une réponse d'erreur indique un problème de scope ou d'identifiant. ^[2]