Comment lister les pièces jointes d'un ticket dans Zoho Desk

Lister toutes les pièces jointes d'un ticket 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 à travers l'appel exact et la configuration nécessaire — par Beam Help, votre support expert indépendant pour Zoho (et non le support officiel Zoho).

Pourquoi c'est important

Lors de la création d'intégrations, d'automatisations ou de workflows d'audit, vous avez souvent besoin de récupérer par programmation tous les fichiers joints à un ticket de support. Que vous synchronisiez des pièces jointes vers un système de gestion documentaire externe, que vous vérifiiez que les fichiers requis ont bien été téléversés, ou que vous les affichiez simplement dans un portail personnalisé, savoir appeler correctement l'endpoint de liste des pièces jointes vous fait gagner un temps précieux en débogage.

Étape par étape

Étape 1. Vérifiez vos scopes OAuth.

Avant d'effectuer tout appel API, assurez-vous que votre application connectée a bien reçu les autorisations nécessaires au niveau du ticket. Au minimum, votre token OAuth doit inclure Desk.tickets.READ — et idéalement Desk.tickets.ALL — pour récupérer les données du ticket, y compris les pièces jointes. ^[8]

Étape 2. Identifiez l'ID du ticket.

Vous avez besoin du ticketId (ou ticket_id) unique du ticket dont vous souhaitez lister les pièces jointes. Il s'agit de l'identifiant interne de Zoho Desk, et non du numéro de ticket lisible affiché dans l'interface. Vous pouvez l'obtenir à partir d'une réponse préalable de recherche ou de création de ticket. ^[2]

Étape 3. Envoyez une requête GET vers l'endpoint des pièces jointes.

Effectuez un GET HTTP vers le chemin suivant, en remplaçant l'identifiant de ticket par le vôtre :

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

Cette opération — appelée listticketattachments — retourne la collection de fichiers associés à ce ticket. ^[2] Une opération équivalente nommée list_attachments utilise la même méthode HTTP et la même structure de chemin, confirmant qu'il s'agit bien de la route canonique. ^[3]

En Python, en utilisant un wrapper client préconfiguré, l'appel ressemble à ceci :

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

Le paramètre optionnel p peut transporter des arguments de chaîne de requête tels que des contrôles de pagination. ^[2]

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

L'endpoint accepte un paramètre p pour la pagination. Si un ticket comporte de nombreuses pièces jointes, passez les valeurs de page ou de décalage appropriées dans ce dictionnaire pour récupérer les pages de résultats suivantes. [^2, ^3]

Étape 5. Accédez à une pièce jointe spécifique (optionnel).

Si vous avez besoin des métadonnées complètes d'un fichier particulier après les avoir listés, utilisez l'endpoint de pièce jointe unique en ajoutant l'attachmentId au chemin :

GET /api/v1/tickets/{ticketId}/attachments/{attachmentId}

Cette opération getticketattachment retourne des informations détaillées sur ce fichier individuel. ^[5]

Étape 6. Récupérez les pièces jointes d'un brouillon de transition (avancé, optionnel).

Si votre workflow utilise des transitions de ticket et que vous avez besoin des pièces jointes associées à un brouillon de transition spécifique plutôt qu'au ticket lui-même, un endpoint distinct existe :

GET /api/v1/tickets/{ticketId}/transitions/{transitionId}/attachments

Il s'agit d'une opération distincte qui ne doit être utilisée que lorsque vous avez spécifiquement besoin des données de pièces jointes au niveau de la transition. ^[7]

Erreurs courantes

• Scope OAuth manquant ou insuffisant. Si votre token ne contient que Desk.tickets.WRITE ou Desk.tickets.CREATE mais pas Desk.tickets.READ ni Desk.tickets.ALL, l'API rejettera la requête. Vérifiez toujours la liste complète des scopes dans votre configuration OAuth. ^[8]

• Confusion entre numéro de ticket et ID de ticket. Le ticketId dans le chemin URL est l'identifiant interne généré par le système. Utiliser le numéro de ticket affiché (par ex. « TKT-1042 ») entraînera une erreur 404 ou un enregistrement invalide. Récupérez l'ID correct à partir d'une réponse API préalable.

• Oubli d'ajouter des pièces jointes avant de les lister. Si vous effectuez des tests et que la liste retournée est vide, vérifiez que des fichiers ont bien été téléversés. Les pièces jointes sont ajoutées via un POST vers le même chemin /api/v1/tickets/{ticketId}/attachments. [^4, ^6]

• Pièces jointes de transition vs. pièces jointes de ticket. L'endpoint de brouillon de transition (/transitions/{transitionId}/attachments) n'est pas interchangeable avec l'endpoint principal des pièces jointes du ticket. Appeler le mauvais endpoint retournera un ensemble de résultats vide ou sans rapport. ^[7]

Points à vérifier

• Vérification des scopes : Confirmez que Desk.tickets.READ ou Desk.tickets.ALL apparaît dans la liste des scopes de votre token OAuth actif avant d'effectuer l'appel. ^[8]
• ID de ticket correct : Vérifiez que le ticketId que vous transmettez est bien l'ID système interne retourné par l'API Zoho Desk, et non le numéro de référence lisible affiché dans le portail de support. ^[2]
• Complétude de la réponse : Si vous attendez plusieurs pièces jointes mais n'en voyez qu'une partie, vérifiez si des paramètres de pagination doivent être fournis via l'argument p pour récupérer toutes les pages. ^[3]