Comment effectuer une recherche dans un module spécifique de Zoho Desk

Effectuer une recherche dans un module spécifique de Zoho Desk via l'API est simple : vous appelez un endpoint dédié qui limite les résultats à un seul module, plutôt que d'analyser l'ensemble des modules en même temps.

Pourquoi c'est important

Lorsque votre instance Zoho Desk contient des milliers de tickets, contacts, tâches ou articles, une recherche globale peut renvoyer des résultats bruités et difficiles à filtrer. Limiter votre requête à un seul module — par exemple, tickets ou contacts — allège les réponses et simplifie considérablement le traitement en aval. Cela est particulièrement utile lors de la création d'intégrations, d'automatisations ou de workflows assistés par IA sur l'API de Zoho Desk. Pour rappel, Beam Help est un support expert indépendant pour Zoho et n'est pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Vérifiez que votre token OAuth inclut le scope Desk.search.READ. Sans lui, l'endpoint de recherche renverra une erreur d'autorisation. Ce scope figure aux côtés des autres scopes Desk tels que Desk.tickets.READ et Desk.contacts.READ dans votre configuration OAuth. ^[2]

Étape 2. Identifiez le module dans lequel vous souhaitez effectuer la recherche. Les valeurs courantes incluent tickets, contacts, tasks, events et articles — tous disposant de scopes de lecture/écriture correspondants dans la liste des scopes OAuth de Desk. ^[2]

Étape 3. Effectuez une requête GET vers l'endpoint de recherche limité au module :

GET /api/v1/{module}/search

Remplacez {module} par le nom du module en minuscules que vous avez identifié à l'étape 2 (par exemple, tickets ou contacts). Transmettez vos paramètres de recherche sous forme de valeurs de chaîne de requête dans le dictionnaire/objet p. ^[1]

Étape 4. En Python, l'appel ressemble à ceci :

results = desk_api.search_in_module(module="tickets", p={"word": "billing issue"})

La méthode searchinmodule émet une requête GET vers /api/v1/{module}/search et transmet tous les paramètres que vous fournissez en tant qu'arguments de requête. ^[1]

Étape 5. Si vous avez besoin de résultats couvrant *tous* les modules simultanément, utilisez plutôt l'endpoint de recherche globale :

GET /api/v1/search

Cette opération searchacrossmodules accepte le même dictionnaire de paramètres p mais ne nécessite pas de nom de module dans le chemin. ^[6] Utilisez l'endpoint spécifique au module (étape 3) chaque fois que vous souhaitez restreindre la portée.

Étape 6. Pour initialiser correctement le client API Zoho Desk, assurez-vous que votre objet de connexion contient un deskorgid valide. Le client est construit avec votre domaine API, votre token d'accès et votre ID d'organisation ; si l'ID d'organisation est absent, le système tentera de le découvrir automatiquement en appelant l'endpoint des organisations lors de la première utilisation. ^[7]

---

Erreurs courantes

• Scope Desk.search.READ manquant. Il s'agit d'une entrée de scope distincte, facile à oublier lors de la copie de listes de scopes. Vérifiez bien qu'il apparaît à la fin de votre configuration des scopes Desk. [^2,3]
• Casse ou orthographe incorrecte du nom de module. Le segment de chemin {module} doit correspondre exactement à la valeur attendue par l'API Zoho Desk (par exemple, tickets, et non Tickets ou ticket). Un nom de module non reconnu renverra généralement une erreur 404 ou un ensemble de résultats vide. ^[1]
• Absence d'ID d'organisation sur le client. Si deskorgid est vide lors de l'instanciation du client, le premier appel API déclenche une recherche automatique de l'organisation. Cela ajoute de la latence et peut échouer si le token ne dispose pas de Desk.basic.READ. Assurez-vous que Desk.basic.READ est inclus dans vos scopes. [^2,7]
• Confusion entre recherche dans un module et recherche globale. L'endpoint spécifique au module (/api/v1/{module}/search) et l'endpoint global (/api/v1/search) sont des opérations distinctes. Appeler l'endpoint global en attendant des résultats filtrés par module ne fonctionnera pas comme prévu. [^1,6]

---

Points à vérifier

• Liste des scopes : Vérifiez que Desk.search.READ et le scope du module concerné (par exemple, Desk.tickets.READ) sont tous deux présents dans votre configuration OAuth avant d'effectuer tout appel de recherche. ^[2]
• Chemin de l'endpoint : Confirmez que le paramètre {module} dans /api/v1/{module}/search est remplacé par le nom de module correct en minuscules, conformément aux conventions de l'API Zoho Desk. ^[1]
• Persistance de l'ID d'organisation : Après le premier appel API réussi, vérifiez que deskorgid a été enregistré dans votre enregistrement de connexion afin que les requêtes suivantes n'engendrent pas le surcoût de la découverte automatique. ^[7]