Comment récupérer des enregistrements dans Zoho CRM

L'API GraphQL de Zoho CRM vous permet de récupérer à la fois les données d'enregistrements et les métadonnées de vos modules CRM en une seule requête flexible — ce qui en fait une alternative puissante aux appels REST traditionnels lorsque vous devez interroger plusieurs modules simultanément.

Pourquoi c'est important

Lors de la création d'intégrations, de tableaux de bord ou de widgets personnalisés, les développeurs ont souvent besoin de récupérer des données de plusieurs modules Zoho CRM en même temps. L'API GraphQL répond à ce besoin en vous permettant de combiner des requêtes Records et Meta en une seule demande, réduisant ainsi les allers-retours et vous donnant un contrôle précis sur les champs retournés. ^[1] Cela est particulièrement utile pour les équipes qui créent des outils de reporting ou synchronisent des données CRM avec des systèmes externes.

Étape par étape

Étape 1. Vérifiez que votre édition Zoho CRM prend en charge GraphQL. L'API GraphQL n'est pas disponible sur les versions d'essai de Zoho CRM, vous devez donc disposer d'un abonnement payant avant de continuer. ^[1]

Étape 2. Authentifiez votre client API. Vous aurez besoin d'un jeton d'accès OAuth 2.0 valide avec les droits Zoho CRM avant d'envoyer toute requête GraphQL. Une fois votre jeton obtenu, définissez-le comme jeton Bearer dans l'en-tête Authorization de votre requête HTTP. ^[1]

Étape 3. Comprenez les deux types de requêtes racines à votre disposition. Le schéma GraphQL expose un type Query racine avec deux branches principales : ^[1]

• Records — récupère les lignes de données réelles depuis n'importe quel module CRM accessible à votre profil. Le filtrage et la pagination sont pris en charge pour tous les modules.
• Meta — récupère les données structurelles/de configuration depuis des sources telles que Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles et Widgets. Certaines de ces sources prennent également en charge le filtrage et la pagination.

Étape 4. Construisez votre requête GraphQL. Voici un exemple qui récupère AccountName depuis le module Accounts, LastName depuis Leads, apiname depuis Roles et lastname depuis Users — le tout en une seule requête : ^[1]

query {
    Records {
        Accounts {
            _data {
                Account_Name {
                    value
                }
            }
        }
        Leads {
            _data {
                Last_Name {
                    value
                }
            }
        }
    }
    Meta {
        Roles {
            _data {
                api_name
            }
        }
        Users {
            _data {
                last_name
            }
        }
    }
}

Notez que les valeurs des champs d'enregistrement sont accessibles via la clé value imbriquée sous chaque nom de champ, tandis que certains champs de métadonnées (comme api_name) sont accessibles directement. ^[1]

Étape 5. Envoyez la requête à l'endpoint GraphQL de Zoho CRM en utilisant votre client HTTP préféré (par exemple, curl, Postman ou un SDK côté serveur). Incluez votre jeton OAuth dans l'en-tête de la requête et définissez le Content-Type sur application/json. ^[1]

Étape 6. Analysez la réponse. L'API retourne un objet JSON structuré reflétant la forme de votre requête. Les enregistrements apparaissent dans des tableaux _data au sein de chaque nœud de module, et les champs de métadonnées apparaissent sous leurs nœuds de type respectifs. ^[1]

Erreurs courantes

• Restriction des comptes d'essai. Toute tentative d'utilisation de l'API GraphQL sur un essai Zoho CRM entraînera une erreur. Vous devez d'abord passer à une édition payante. ^[1]
• Accès basé sur le profil. La requête Records n'expose que les modules et les champs que votre profil CRM est autorisé à consulter. Si un module apparaît vide ou est absent de la réponse, vérifiez les permissions au niveau des champs et des modules dans votre profil Zoho CRM. ^[1]
• Sensibilité à la casse des noms de champs. Les requêtes GraphQL dans Zoho CRM sont sensibles à la casse. Par exemple, LastName et lastname font référence à des champs différents dans des contextes différents (Records vs. Meta). Vérifiez attentivement les noms API exacts de vos champs avant d'effectuer une requête. ^[1]
• Pagination pour les grands ensembles de données. Bien que le filtrage et la pagination soient pris en charge pour tous les modules Records et certains types Meta, l'omission des arguments de pagination sur des modules volumineux peut entraîner des réponses tronquées. Implémentez toujours la pagination lors de l'interrogation de modules contenant un grand nombre d'enregistrements. ^[1]

Points à vérifier

• Édition et statut d'essai — vérifiez que votre organisation dispose d'un abonnement Zoho CRM payant, car GraphQL est bloqué sur les comptes d'essai. ^[1]
• Portée du jeton OAuth — confirmez que votre jeton d'accès inclut les bonnes portées CRM ; un jeton avec des droits insuffisants entraînera des échecs d'authentification même si la syntaxe de la requête est correcte. ^[1]
• Noms API des champs — comparez les noms de champs utilisés dans votre requête avec les noms API réels de votre configuration CRM (disponibles sous Configuration → Modules et champs) pour éviter des réponses vides ou des erreurs. ^[1]

---

*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 liés à la plateforme, consultez toujours la documentation officielle ou les canaux de support de Zoho.*