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

Lister les pièces jointes d'un ticket dans Zoho Desk est simple via l'API REST : envoyez une requête GET vers la sous-ressource des pièces jointes de n'importe quel ticket, et la plateforme retourne tous les fichiers associés à cet enregistrement.

Pourquoi c'est important

Lors de la création d'intégrations, d'automatisations ou de workflows d'audit, vous avez souvent besoin d'inspecter chaque fichier qu'un client a soumis avec sa demande d'assistance. Récupérer la liste des pièces jointes par programmation vous permet de les dupliquer vers un stockage externe, de valider les téléversements ou de les afficher dans un portail personnalisé — sans qu'un agent ait besoin d'ouvrir le ticket manuellement.

Étape par étape

Étape 1. Vérifiez que vos scopes OAuth sont en place.

Avant d'effectuer tout appel API, vérifiez que votre application connectée a bien reçu le scope Desk.tickets.READ (au minimum) ou le scope plus large Desk.tickets.ALL. Sans ceux-ci, la requête sera rejetée au niveau de la couche d'autorisation. ^[8]

Étape 2. Identifiez l'ID du ticket.

Chaque ticket Zoho Desk possède un ticketId numérique unique. Vous pouvez l'obtenir à partir d'un appel précédent à la liste des tickets, depuis l'URL du ticket dans l'interface Desk, ou depuis un payload de webhook. Conservez cette valeur — c'est le paramètre de chemin clé pour l'étape suivante.

Étape 3. Envoyez la requête de liste des pièces jointes.

Effectuez un GET HTTP vers l'endpoint suivant, en remplaçant l'identifiant réel du ticket :

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

L'objet de paramètre de requête optionnel p peut contenir des arguments de pagination ou de filtrage pris en charge par l'API Zoho Desk. ^[2][3]

Une implémentation minimale en Python 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
    )

La méthode passe None comme corps de requête (correct pour un GET) et transmet les éventuels paramètres de requête via p. ^[2]

Étape 4. Analysez la réponse.

L'API retourne une collection d'objets de pièces jointes. Chaque objet inclut généralement des métadonnées telles que le nom du fichier, sa taille et un identifiant de référence que vous pouvez utiliser pour des opérations ultérieures.

Étape 5. Récupérez une seule pièce jointe si nécessaire.

Si vous n'avez besoin que des détails d'un fichier spécifique, utilisez la variante à ressource unique en ajoutant l'attachmentId au chemin :

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

Cela est utile lorsque vous connaissez déjà l'identifiant à partir d'un appel de liste précédent et souhaitez éviter de traiter l'intégralité de la collection. ^[5]

Étape 6. (Optionnel) Récupérez les pièces jointes liées à un brouillon de transition.

Si votre workflow utilise des transitions de ticket (par exemple, des étapes d'approbation), les pièces jointes peuvent également être limitées à une transition spécifique. Utilisez l'endpoint dédié :

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

Cela est distinct de la liste principale des pièces jointes et ne s'applique que lorsqu'un brouillon de transition est en cours. ^[7]

Erreurs courantes

• Scope manquant ou incorrect. Le scope Desk.tickets.READ doit être présent dans votre token OAuth. Si vous obtenez une réponse 401 ou 403, vérifiez à nouveau les scopes configurés pour votre client et régénérez le token d'accès. ^[8]
• Confusion entre ticketId et le numéro de ticket lisible par l'humain. Le paramètre de chemin doit être l'ID numérique interne, et non la référence de style #1234 affichée dans l'interface. L'utilisation du numéro d'affichage retournera une erreur 404.
• Oubli de la pagination. Si un ticket comporte de nombreuses pièces jointes, la réponse peut être paginée. Passez le paramètre de page approprié via le dictionnaire p pour récupérer les pages suivantes. ^[2][3]
• Téléversement vs. listage. Le même chemin (/api/v1/tickets/{ticketId}/attachments) est utilisé à la fois pour lister (GET) et téléverser (POST). Assurez-vous que votre intégration utilise le bon verbe HTTP ; un POST vers cet endpoint créera une nouvelle pièce jointe plutôt que de retourner les pièces jointes existantes. ^[4][6]

Points à vérifier

• Vérification du scope : Confirmez que Desk.tickets.READ ou Desk.tickets.ALL apparaît dans le token OAuth actif avant la mise en production. ^[8]
• Structure de la réponse : Journalisez la réponse brute du premier appel pour confirmer que les champs de métadonnées des pièces jointes (nom, taille, ID) correspondent à ce qu'attend votre code en aval. ^[2][5]
• Source de l'ID du ticket : Tracez l'origine de votre ticketId et vérifiez qu'il s'agit bien de l'ID système interne, et non d'une référence d'affichage, afin d'éviter des erreurs 404 silencieuses.

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho — nous ne sommes pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, référez-vous toujours à la documentation officielle de l'API Zoho Desk.*