Comment effectuer une recherche dans tous les modules de Zoho Desk

La recherche dans tous les modules de Zoho Desk s'effectue via un seul endpoint d'API qui interroge les tickets, les contacts, les comptes, les tâches et bien plus encore en un seul appel — à condition que votre jeton OAuth dispose du scope de recherche approprié.

Pourquoi c'est important

Lorsque des agents de support ou des intégrations doivent localiser un enregistrement sans savoir dans quel module il se trouve, une recherche module par module est lente et sujette aux erreurs. Zoho Desk expose une opération de recherche inter-modules dédiée afin que vous puissiez récupérer les enregistrements correspondants dans chaque zone pertinente de votre helpdesk en un seul aller-retour. Cela est particulièrement utile dans les workflows automatisés, les chatbots ou les portails personnalisés construits sur l'API de Zoho Desk.

Étape par étape

Étape 1. Vérifiez que votre application OAuth inclut le scope Desk.search.READ. Sans celui-ci, l'endpoint de recherche retournera une erreur d'autorisation. Ce scope s'ajoute aux autres scopes Desk tels que Desk.tickets.READ, Desk.contacts.READ et Desk.articles.READ — qui peuvent également être nécessaires selon les modules dont vous souhaitez obtenir des résultats. ^[1]

Étape 2. Demandez (ou actualisez) un jeton d'accès OAuth incluant Desk.search.READ dans ses scopes accordés. Si vous construisez une intégration multi-application qui touche également Zoho CRM, combinez les scopes Desk avec vos scopes CRM dans une seule demande d'autorisation afin de n'avoir besoin que d'un seul jeton. ^[1][3]

Étape 3. Émettez une requête HTTP GET vers l'endpoint de l'API Zoho Desk /api/v1/search, en transmettant vos paramètres de requête dans la demande. L'opération est identifiée en interne sous le nom searchacrossmodules. ^[2]

GET https://desk.zoho.com/api/v1/search
Authorization: Zoho-oauthtoken <your_access_token>

Étape 4. Fournissez votre terme de recherche et les éventuels filtres optionnels sous forme de paramètres de chaîne de requête (représentés par le dictionnaire p dans le wrapper d'API). Au minimum, vous transmettrez généralement un paramètre word ou searchStr contenant le texte que vous souhaitez trouver. ^[2]

Étape 5. Analysez la réponse JSON. Les résultats sont regroupés par module ; votre code doit donc itérer sur les clés de l'objet retourné (par exemple, tickets, contacts, comptes) pour présenter les enregistrements pertinents à votre utilisateur ou au système en aval. ^[2]

Étape 6. Si vous intégrez cette fonctionnalité dans un assistant conversationnel ou une interface de chat, l'outil peut être invoqué dynamiquement lorsqu'un utilisateur pose une question faisant référence à ses données Desk. La couche assistant appelle searchacrossmodules, puis formate les résultats en une réponse lisible par un humain. ^[4][7]

Erreurs courantes

• Scope manquant lors de la génération du jeton. Le scope Desk.search.READ doit être présent lors de la *première création* du jeton OAuth. L'ajouter à votre configuration après coup n'a aucun effet tant que l'utilisateur ne réautorise pas l'accès. Vérifiez votre liste de scopes avant de passer en production. ^[1][3]

• URL de base du centre de données incorrect. Zoho Desk est hébergé sur plusieurs centres de données (com, eu, in, com.au, etc.). Assurez-vous que l'URL de base que vous appelez correspond au centre de données où le portail a été créé, sinon vous recevrez une redirection ou une erreur 404. ^[7]

• Conflits de scopes dans les intégrations combinées. Si votre application se connecte également à Zoho CRM, la chaîne de scopes combinée doit être construite avec soin — les scopes Desk et CRM sont concaténés ensemble. Une erreur de formatage (par exemple, une virgule manquante ou un espace en fin de chaîne) peut supprimer silencieusement des scopes du jeton. ^[1][3]

• Erreurs d'API remontées comme erreurs d'outil. Si Zoho rejette la requête (par exemple, en raison d'un jeton expiré ou d'un paramètre mal formé), la réponse contiendra un champ error plutôt que des résultats. Mettez en place une logique de gestion des erreurs qui détecte cela et invite l'utilisateur à corriger ou relance la requête avec des paramètres corrigés. ^[6]

Ce qu'il faut vérifier

• Le scope est présent dans le jeton actif — décodez votre jeton d'accès ou inspectez l'autorisation OAuth pour confirmer que Desk.search.READ apparaît dans la liste des scopes avant d'effectuer le premier appel. ^[1]
• Le chemin de l'endpoint et l'URL du centre de données sont corrects — vérifiez que votre URL de base correspond au centre de données du portail et que le chemin est exactement /api/v1/search. ^[2][7]
• La réponse contient des résultats pour les modules attendus — exécutez une requête de test pour un enregistrement connu et confirmez que le module attendu (par exemple, tickets ou contacts) apparaît dans la charge utile de la réponse. ^[2]

---

*Beam Help est une ressource d'assistance experte indépendante pour les produits Zoho et ne constitue pas le support officiel de Zoho. Référez-vous toujours à la documentation de l'API Zoho Desk pour les dernières spécifications de scopes et d'endpoints.*