La création d'une requête dans le Developer Hub de Zoho CRM vous permet de définir des opérations de récupération de données réutilisables et filtrables sur des modules CRM, des bases de données externes ou des API REST tierces — le tout depuis une interface de configuration unique.
Pourquoi c'est important
Lorsque vous devez extraire par programmation des sous-ensembles spécifiques de données CRM — par exemple, toutes les affaires ouvertes liées à un contact particulier — coder en dur les appels API dans chaque intégration devient rapidement ingérable. La fonctionnalité Queries de Zoho CRM vous offre une requête nommée et versionnée que vous pouvez référencer dans des fonctions, des widgets et des scripts client sans dupliquer la logique. [1] En tant qu'équipe d'experts indépendants (Beam Help — et non le support officiel de Zoho), nous trouvons cette fonctionnalité particulièrement utile lors de la création de tableaux de bord ou d'automatisations qui dépendent d'ensembles d'enregistrements filtrés et cohérents.
---
Étape par étape
Étape 1. Accédez à Configuration → Developer Hub → Queries. La fenêtre Queries s'ouvre et liste toutes les requêtes déjà définies dans votre organisation. [1]
Étape 2. Cliquez sur Add Query pour ouvrir la boîte de dialogue de création. [1]
Étape 3. Dans la fenêtre contextuelle Create Query, renseignez un Query Name lisible par l'utilisateur et un API Name (utilisé pour référencer la requête par programmation), puis cliquez sur Next. [1]
Étape 4. Dans la section Configuration, le type de source par défaut est Zoho CRM Module. Si vous avez besoin d'une source différente — comme un endpoint d'API REST, une base de données relationnelle auto-hébergée (MySQL, Microsoft SQL, PostgreSQL) ou une base de données cloud (Amazon RDS, Google Cloud Platform, Microsoft Azure) — cliquez sur Change pour changer le type de source. [1][7]
Étape 5. Sélectionnez le module CRM que vous souhaitez interroger. Notez que les sous-formulaires sont également pris en charge comme cibles interrogeables, vous donnant un accès granulaire aux données de ligne dans les enregistrements. [1]
Étape 6. Si le module choisi contient des champs de liaison, vous pouvez récupérer des données associées en sélectionnant jusqu'à deux modules associés dans la liste déroulante Related Module. [1]
Étape 7. Choisissez les champs spécifiques que vous souhaitez retourner dans la liste déroulante Fields. Vous pouvez sélectionner un maximum de 50 champs par requête. [1]
Étape 8. Configurez la section Criteria. Vous disposez de trois options : [1]
- None — retourne tous les enregistrements sans aucun filtrage appliqué.
- Record ID — filtre la réponse sur un seul enregistrement par son identifiant unique.
- Criteria — applique une logique conditionnelle sur un ou plusieurs champs. Vous pouvez combiner des conditions à l'aide des opérateurs AND / OR et utiliser des comparateurs adaptés à chaque type de champ.
Étape 9. Pour chaque critère, décidez si vous souhaitez fournir une valeur statique (fixée au moment de la création de la requête) ou une valeur dynamique. Choisir dynamique signifie que la valeur réelle est transmise au moment de l'exécution — par exemple, lorsque la requête est invoquée depuis une fonction ou un widget — rendant la requête réutilisable dans différents enregistrements ou contextes. [1]
Étape 10. Enregistrez la requête. Elle apparaîtra désormais dans la liste Queries et pourra être référencée par son nom d'API depuis les fonctions Zoho CRM, les Client Scripts, les Widgets ou les appels SDK côté serveur. [1][8]
---
Erreurs courantes
- Limite de modules associés : Vous ne pouvez inclure des données que de deux modules associés par liaison au maximum dans une seule requête. Tenter d'en ajouter davantage ne sera pas autorisé dans l'interface de configuration. [1]
- Plafond du nombre de champs : La sélection de plus de 50 champs dans une seule requête n'est pas autorisée. Si vous avez besoin de plus de champs, envisagez de répartir la logique sur deux requêtes distinctes. [1]
- Sources de bases de données externes — liste blanche d'adresses IP : Lorsque vous utilisez une base de données MySQL, PostgreSQL ou Microsoft SQL auto-hébergée comme source de requête, vous devez ajouter les adresses IP de Zoho CRM à la liste blanche de votre serveur relais, et ajouter l'hôte aux Trusted Domains s'il n'est pas exprimé sous forme d'adresse IP brute. Ignorer cette étape entraînera des échecs de connexion. [7]
- SSL et configuration avancée : Pour les bases de données standard et cloud, les options telles que le délai de connexion, le fuseau horaire et l'application du SSL se trouvent sous Advanced Configuration dans la configuration de la source — facile à négliger si vous parcourez l'assistant rapidement. [7]
- Valeurs dynamiques vs. statiques : Une erreur courante consiste à définir une valeur comme statique lors des tests et à oublier de la passer en dynamique avant le déploiement. Un critère statique filtrera toujours sur la même valeur codée en dur, ce qui est rarement le comportement souhaité dans les workflows de production. [1]
---
Ce qu'il faut vérifier
- La requête retourne les enregistrements attendus : Après l'enregistrement, utilisez l'option de test/aperçu intégrée pour confirmer que la logique des critères produit le bon ensemble de résultats filtrés avant de connecter la requête à une automatisation.
- L'API Name est unique et correctement référencé : Vérifiez que le nom d'API que vous avez attribué correspond exactement à ce qui est référencé dans les fonctions, les Client Scripts ou les appels SDK qui utilisent cette requête. [1][8]
- Connectivité de la source (pour les sources externes) : Si votre requête cible une API REST externe ou une base de données, confirmez que la connexion est active et que les adresses IP de Zoho CRM sont sur liste blanche sur l'hôte distant avant la mise en production. [7]