Comment récupérer les enregistrements d'une vue dans Zoho Desk

Récupérer les enregistrements d'une vue spécifique dans Zoho Desk est simple dès lors que vous disposez du bon identifiant de vue et des bons périmètres OAuth. Voici tout ce que vous devez savoir pour extraire les enregistrements d'une vue via l'API Zoho Desk.

Pourquoi c'est important

Zoho Desk organise les tickets, les contacts et d'autres entités en vues — des filtres enregistrés qui regroupent les enregistrements selon des critères tels que le statut, le responsable ou la priorité. Si vous souhaitez récupérer par programmation les enregistrements appartenant à l'une de ces vues (à des fins de reporting, d'automatisation ou d'intégration), vous devez appeler le point de terminaison dédié aux enregistrements de vue plutôt qu'un point de terminaison de liste générique. Cela est également utile lorsque vous souhaitez reproduire ce qu'un agent voit dans sa file d'attente Desk au sein d'un outil tiers ou d'un tableau de bord.

Étape par étape

Étape 1. Vérifiez que vos périmètres OAuth incluent l'accès en lecture à Desk.

Avant d'effectuer tout appel API, vérifiez que votre jeton OAuth Zoho Desk connecté a été accordé au minimum avec Desk.tickets.READ (ou le périmètre de module pertinent, tel que Desk.contacts.READ). Une intégration complète inclut généralement aussi Desk.basic.READ afin que l'API puisse résoudre les métadonnées d'organisation et de département. Sans les périmètres corrects, la requête retournera une erreur d'autorisation. ^[2]

Étape 2. Récupérez votre identifiant d'organisation.

Chaque appel à l'API Zoho Desk doit être limité à une organisation. Si vous n'avez pas encore enregistré l'orgId, appelez d'abord le point de terminaison des organisations. Parcourez le tableau data retourné, récupérez le champ id du premier élément et conservez-le pour une réutilisation ultérieure. Une fois découvert, transmettez cette valeur en tant qu'en-tête orgId sur toutes les requêtes suivantes. ^[4][6]

Étape 3. Identifiez l'identifiant de la vue cible.

Accédez à Zoho Desk dans votre navigateur, ouvrez la vue que vous souhaitez interroger et notez l'identifiant numérique dans l'URL — ou récupérez-le par programmation depuis le point de terminaison de la liste des vues. Vous transmettrez cette valeur en tant que paramètre de chemin view_id à l'étape suivante. ^[3]

Étape 4. Appelez GET /api/v1/views/{view_id}/records.

Émettez une requête GET authentifiée vers le point de terminaison ci-dessous, en remplaçant par votre identifiant de vue réel :

GET /api/v1/views/{view_id}/records

Le nom de l'opération est getviewrecords. Les paramètres pris en charge sont :

| Paramètre | Description |

|-----------|-------------|

| view_id | L'identifiant numérique de la vue (paramètre de chemin) |

| p | Dictionnaire optionnel de pagination ou de filtre transmis en tant que paramètres de requête |

Un appel Python minimal ressemble à ceci :

result = desk_api.get_view_records(view_id="123456", p={"limit": 50})

Le client émet la requête GET et retourne la réponse JSON analysée contenant les enregistrements correspondants. ^[3]

Étape 5. (Optionnel) Récupérez uniquement le nombre d'enregistrements.

Si vous avez seulement besoin de connaître le nombre d'enregistrements présents dans une vue — par exemple, pour afficher un compteur ou décider de paginer — utilisez la variante de comptage du même point de terminaison :

GET /api/v1/views/{view_id}/records/count

L'opération est getviewrecordscount et accepte les mêmes paramètres viewid et p. ^[7]

Étape 6. Construisez des liens directs vers les enregistrements retournés.

Une fois que vous disposez de la réponse, vous pouvez construire des URL navigables dans le navigateur pour chaque enregistrement. Pour les tickets, le modèle est :

https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}

Pour les contacts et les comptes, le chemin de base suit {deskrecordsroot}/contacts ou {deskrecordsroot}/accounts respectivement. Si aucun slug de portail n'est disponible, l'identifiant d'organisation est utilisé à sa place. ^[1][5]

Erreurs courantes

• En-tête orgId manquant. Zoho Desk exige l'identifiant d'organisation sur chaque requête. Si le deskorgid enregistré est vide ou obsolète, l'API rejettera les appels. Le modèle de découverte automatique (récupération des organisations à la première utilisation et persistance du résultat) évite que cela échoue silencieusement. ^[4][6]
• Combinaisons de périmètres incorrectes. Demander Desk.tickets.ALL ne couvre pas automatiquement les contacts ou les tâches. Chaque module nécessite son propre périmètre (Desk.contacts.READ, Desk.tasks.READ, etc.). Vérifiez la liste complète des périmètres si vous recevez des erreurs 403 sur des types d'enregistrements spécifiques. ^[2]
• Incompatibilité de centre de données. Zoho héberge les données dans plusieurs régions (.com, .eu, .in, etc.). Assurez-vous que l'URL de base correspond au centre de données où le compte a été créé — par exemple https://desk.zoho.eu pour les comptes européens — sinon les requêtes échoueront ou seront redirigées de manière inattendue. ^[5]

Ce qu'il faut vérifier

• Les périmètres sont présents et actifs — confirmez que Desk.tickets.READ (et tout autre périmètre de module dont vous avez besoin) apparaît dans la liste des périmètres accordés au jeton avant la mise en production. ^[2]
• Le view_id est valide pour votre organisation — les identifiants de vue sont spécifiques à l'organisation ; un identifiant de vue d'un portail Zoho Desk ne fonctionnera pas dans un autre. ^[3]
• La pagination est gérée — si le paramètre p prend en charge une limite ou un décalage de page, vérifiez que votre code parcourt toutes les pages afin qu'aucun enregistrement ne soit silencieusement ignoré. ^[3][7]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Pour les problèmes de facturation ou liés à votre compte, contactez directement Zoho.*