La récupération d'une pièce jointe d'un ticket dans Zoho Desk via l'API nécessite deux identifiants — l'ID du ticket et l'ID de la pièce jointe — ainsi qu'une simple requête GET vers le point de terminaison des pièces jointes.
Pourquoi c'est important
Lors de la création d'intégrations ou d'automatisations autour de Zoho Desk, vous avez souvent besoin de récupérer par programmation les fichiers joints aux tickets d'assistance — par exemple, pour les archiver, les transmettre à un autre système ou en inspecter le contenu. Connaître le bon point de terminaison et l'ordre des opérations (lister d'abord, puis récupérer) permet de gagner un temps précieux en débogage et de maintenir la fiabilité de votre intégration.
Étape par étape
Étape 1. Récupérez l'ID de votre ticket.
Avant d'effectuer toute requête relative aux pièces jointes, confirmez le ticketId du ticket sur lequel vous travaillez. Il s'agit de l'identifiant unique que Zoho Desk attribue à chaque ticket d'assistance et qui est requis dans chaque appel API lié aux pièces jointes.[1]
Étape 2. Listez toutes les pièces jointes du ticket.
Si vous ne connaissez pas encore l'attachmentId, envoyez d'abord une requête GET vers le point de terminaison de liste :
GET /api/v1/tickets/{ticketId}/attachmentsPassez le ticketId en tant que paramètre de chemin. Un dictionnaire de paramètres de requête optionnel (p) peut être fourni pour la pagination ou le filtrage.[3] En Python, cela ressemble à :
attachments = client.list_ticket_attachments(ticketId="123456")La réponse inclura les métadonnées de chaque pièce jointe, notamment son attachmentId, dont vous aurez besoin à l'étape suivante.[3]
Étape 3. Récupérez la pièce jointe spécifique.
Une fois que vous disposez des deux identifiants, appelez le point de terminaison de pièce jointe unique :
GET /api/v1/tickets/{ticketId}/attachments/{attachmentId}Remplacez {ticketId} et {attachmentId} par les valeurs réelles. Le paramètre optionnel p peut transporter toutes les options de requête supplémentaires dont votre intégration a besoin.[1] En Python :
attachment = client.get_ticket_attachment(
ticketId="123456",
attachmentId="789"
)L'objet de réponse contient les détails de la pièce jointe pour ce fichier spécifique.[1]
Étape 4. (Optionnel) Récupérez les pièces jointes liées à un brouillon de transition.
Si le fichier dont vous avez besoin est associé à une transition de workflow plutôt qu'au corps du ticket lui-même, utilisez un point de terminaison différent qui nécessite également un transitionId :
GET /api/v1/tickets/{ticketId}/transitions/{transitionId}/attachmentsFournissez les trois paramètres de chemin — ticketId, transitionId, et optionnellement p — pour récupérer les pièces jointes appartenant à ce brouillon de transition.[4]
Étape 5. (Optionnel) Téléversez ou supprimez des pièces jointes selon vos besoins.
Pour être complet, notre équipe note que le même chemin /api/v1/tickets/{ticketId}/attachments prend en charge les requêtes POST pour ajouter un nouveau fichier (avec un payload data) et les requêtes DELETE vers le sous-chemin /{attachmentId} pour supprimer un fichier existant.[6][8] Ces opérations suivent les mêmes conventions d'ID décrites ci-dessus.
Erreurs courantes
- Ordre des ID incorrect. Le chemin place toujours
ticketIdavantattachmentId. Les inverser entraînera l'échec de la requête ou une réponse 404.[1] - Ignorer l'étape de liste. Tenter d'appeler le point de terminaison de pièce jointe unique sans avoir d'abord confirmé l'
attachmentIdcorrect via le point de terminaison de liste est une source d'erreurs fréquente. Listez toujours en premier si vous n'êtes pas sûr.[3] - Pièces jointes de transition vs. pièces jointes de ticket. Les fichiers joints lors d'un brouillon de transition de workflow se trouvent sous le chemin
/transitions/{transitionId}/attachments, et non sous le chemin standard des pièces jointes du ticket. Utiliser le mauvais point de terminaison renverra un résultat vide ou inattendu.[4] - Confusion entre téléversement et récupération. Le point de terminaison POST à
/api/v1/tickets/{ticket_id}/attachmentssert à téléverser de nouveaux fichiers, et non à télécharger des fichiers existants. Utilisez GET pour la récupération.[7]
Ce qu'il faut vérifier
- Les deux ID sont présents et corrects — confirmez que
ticketIdetattachmentIdsont valides avant d'appeler le point de terminaison GET.[1] - La portée de la pièce jointe est correcte — vérifiez si le fichier appartient au corps du ticket ou à un brouillon de transition, et utilisez le point de terminaison approprié en conséquence.[3][4]
- Vos identifiants API disposent des autorisations nécessaires — assurez-vous que le jeton OAuth ou la clé API utilisé par votre intégration dispose d'un accès en lecture aux pièces jointes des tickets Zoho Desk avant de déboguer les erreurs de réponse.[1]
---
*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Consultez toujours la documentation officielle de Zoho pour les dernières modifications des points de terminaison.*