Comment récupérer les pièces jointes des enregistrements dans Zoho

La récupération des pièces jointes depuis les enregistrements dans Zoho CRM et Zoho Desk est simple dès lors que vous connaissez les bons endpoints d'API et les modèles d'URL à utiliser. Ce guide vous accompagne pas à pas dans le processus.

Pourquoi c'est important

Les pièces jointes — telles que les contrats, les images ou les documents justificatifs — sont souvent stockées directement dans les enregistrements CRM ou Desk. Si vous construisez une intégration, automatisez la récupération de documents ou auditez les fichiers liés à des comptes, vous avez besoin d'un moyen fiable pour les récupérer par programmation. Connaître le bon endpoint pour chaque type d'enregistrement permet de gagner un temps précieux lors du débogage et d'éviter les erreurs courantes liées aux identifiants d'enregistrement et aux chemins de module.

> Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Identifiez le type d'enregistrement et son identifiant.

Avant d'effectuer tout appel API, confirmez si vous travaillez avec un module CRM (par exemple, Contacts, Leads, Accounts) ou une entité Zoho Desk (par exemple, un Account ou un Ticket). Vous aurez également besoin de l'identifiant unique de l'enregistrement — il s'agit de {accountId}, {attachmentId}, ou de l'identifiant équivalent qui apparaît dans l'URL de l'enregistrement. Pour les enregistrements CRM, l'URL directe suit le modèle https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, où {dc} est le suffixe de votre centre de données (par exemple, com, eu, in). ^[1]

Étape 2. Listez toutes les pièces jointes d'un enregistrement Account dans Desk.

Pour récupérer toutes les pièces jointes associées à un Account Desk spécifique, envoyez une requête GET vers l'endpoint suivant, en remplaçant l'identifiant réel du compte :

GET /api/v1/accounts/{accountId}/attachments

Cette opération (listaccountattachments) accepte accountId comme paramètre de chemin obligatoire, ainsi qu'un paramètre optionnel p pour la pagination ou le filtrage. ^[8]

Étape 3. Récupérez une pièce jointe spécifique depuis un Account Desk.

Une fois que vous disposez de la liste des pièces jointes et que vous connaissez l'attachmentId dont vous avez besoin, récupérez ce fichier individuel en utilisant :

GET /api/v1/accounts/{accountId}/attachments/{attachmentId}

Cette opération (getaccountattachment) requiert à la fois accountId et attachmentId comme paramètres de chemin, avec un paramètre optionnel p disponible. ^[5]

Étape 4. Accédez à la documentation générale sur les pièces jointes.

Si vous avez besoin de consulter le schéma général des pièces jointes ou d'explorer les métadonnées liées aux pièces jointes pour différents types d'enregistrements, l'endpoint de documentation est :

GET /api/v1/_doc/attachments

Cette opération get_attachments accepte un paramètre optionnel p et retourne la documentation de référence sur les pièces jointes. ^[7]

Étape 5. Construisez des liens directs vers les enregistrements.

Après avoir récupéré les données des pièces jointes, vous souhaiterez peut-être afficher des liens cliquables vers les enregistrements parents dans votre interface ou vos journaux. Pour les enregistrements CRM, construisez le lien sous la forme https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Pour les enregistrements Desk, le modèle est https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}. Adaptez le segment {dc} en fonction du centre de données de votre organisation. ^[1]

Étape 6. Traitez la réponse API et affichez les liens.

Lorsque votre outil ou intégration retourne des résultats, vérifiez le contenu de la réponse pour y trouver les données des pièces jointes. Si votre système génère automatiquement des liens vers les enregistrements, ceux-ci sont généralement ajoutés dans une section « Ouvrir dans Zoho » au format 🔗 {name}: {url} pour faciliter la navigation. ^{[2] [4]}

---

Erreurs courantes

• Mauvais suffixe de centre de données. La valeur {dc} dans votre URL de base doit correspondre à l'emplacement d'hébergement de votre organisation Zoho. Utiliser com alors que votre organisation est sur eu entraînera des échecs d'authentification ou des erreurs 404. Confirmez toujours votre centre de données avant de construire des URL. ^[1]

• Confusion entre les endpoints CRM et Desk. Les endpoints de pièces jointes présentés ci-dessus (/api/v1/accounts/{accountId}/attachments) sont des endpoints Zoho Desk, et non Zoho CRM. Envoyer des requêtes de style Desk vers une URL de base CRM — ou inversement — échouera. Confirmez quel produit contient l'enregistrement avant de choisir votre endpoint. ^{[5] [8]}

• accountId manquant ou incorrect. Les endpoints de liste et de pièce jointe individuelle requièrent tous deux un accountId valide. Passer un identifiant d'enregistrement CRM à un endpoint Desk, ou omettre l'identifiant entièrement, retournera une erreur. Récupérez toujours l'identifiant directement depuis l'enregistrement du système cible. ^{[5] [8]}

• Oubli des paramètres de pagination. Le paramètre optionnel p sur les endpoints de liste contrôle la pagination. Si un compte possède de nombreuses pièces jointes, l'absence de gestion de la pagination peut faire en sorte que vous ne receviez que la première page de résultats. ^[8]

---

Ce qu'il faut vérifier

• Confirmez que l'URL de base et le centre de données (com, eu, in, etc.) correspondent à la région de votre organisation Zoho avant d'effectuer tout appel API. ^[1]
• Vérifiez que accountId et attachmentId proviennent bien de Zoho Desk, et non d'un enregistrement CRM, lorsque vous utilisez les endpoints de pièces jointes Desk. ^{[5] [8]}
• Vérifiez le contenu de la réponse pour détecter une clé error — si elle est présente, lisez le message pour diagnostiquer les problèmes de permissions, les identifiants invalides ou les requêtes malformées avant de réessayer. ^[6]