La récupération des utilisateurs dans Zoho CRM via OAuth nécessite un jeton d'accès valide et un appel à l'endpoint user-info de Zoho Accounts — voici exactement comment ce flux fonctionne, de la configuration des identifiants jusqu'à l'analyse de la réponse.
Pourquoi c'est important
Lorsque vous créez des intégrations ou des outils internes basés sur Zoho CRM, vous devez souvent identifier *qui* est authentifié — son identifiant utilisateur, son adresse e-mail et les détails de son organisation — avant d'effectuer tout appel à l'API CRM. Une erreur à ce stade entraîne des erreurs 401, des incohérences d'identifiants d'organisation et une logique multi-tenant défaillante. Comprendre l'intégralité du flux de callback OAuth et de récupération des informations utilisateur permet d'économiser un temps de débogage considérable.
> Beam Help est un support expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho.
---
Étape par étape
Étape 1. Enregistrez votre application dans la console API Zoho et collectez les identifiants nécessaires. Accédez à la console API, créez une application basée sur un serveur, définissez votre URI de redirection (par ex. http://localhost:8080/api/auth_callback), et notez votre Client ID et votre Client Secret. Lors de la sélection des scopes OAuth, incluez au minimum ZohoCRM.users.ALL, ZohoCRM.modules.ALL et ZohoCRM.settings.ALL. [7]
Étape 2. Configurez votre environnement. Créez un fichier .env à la racine du projet et renseignez-y ZOHOCLIENTID, ZOHOCLIENTSECRET, et optionnellement ZOHO_DC (valeurs acceptées : com, eu, in, com.au, jp — par défaut com). La valeur du centre de données détermine quel endpoint régional est appelé dans les étapes suivantes. [7]
Étape 3. Gérez le callback OAuth dans votre serveur. Lorsque Zoho redirige vers votre route de callback, extrayez le paramètre code de la chaîne de requête. Transmettez ce code à votre gestionnaire OAuth (ZohoOAuth.handleoauthcallback(code)), qui l'échange contre un jeton d'accès et un jeton de rafraîchissement. Si la réponse ne contient pas de clé access_token, signalez l'erreur immédiatement plutôt que de continuer. [6]
Étape 4. Appelez l'endpoint user-info de Zoho Accounts pour récupérer les informations de l'utilisateur authentifié. Construisez l'URL comme suit :
https://accounts.zoho.<DC>/oauth/user/infoEnvoyez une requête GET avec un en-tête Authorization: Bearer <access_token>. La réponse JSON contient les champs nécessaires pour identifier l'utilisateur. [1]
Étape 5. Analysez la réponse avec soin — les noms de champs varient selon le centre de données. Extrayez l'identifiant utilisateur depuis ZUID, et l'adresse e-mail depuis Email. Pour l'identifiant d'organisation, essayez d'abord orgid, puis organizationid, puis ZGID ; si aucun n'est présent (organisations à utilisateur unique), utilisez la valeur de ZUID comme solution de repli. Pour le nom de l'organisation, vérifiez companyname, puis organizationname, puis Company_Name ; si tous sont absents, déduisez un nom de repli à partir de la partie domaine de l'adresse e-mail. [1]
Étape 6. Persistez l'utilisateur et l'organisation. Utilisez le zohouserid pour rechercher un enregistrement utilisateur existant ; créez-en un s'il n'existe pas. Séparément, appelez getorcreateorganization avec les valeurs zohoorgid et orgname, puis liez l'utilisateur à cette organisation via updateuserorg. Stockez le orgid dans la session aux côtés de userid pour prendre en charge les scénarios multi-tenant. [6]
Étape 7. Stockez les jetons de connexion. Enregistrez le accesstoken, le refreshtoken, l'apidomain, le tokenexpiresat et le dc dans votre table zohoconnections, indexée par user_id. Si un enregistrement de connexion existe déjà pour cet utilisateur, mettez-le à jour ; sinon, insérez une nouvelle ligne. [8]
Étape 8. Pour les requêtes suivantes, récupérez la connexion stockée et rafraîchissez proactivement le jeton d'accès s'il expire dans moins de 120 secondes. Après un rafraîchissement réussi, mettez à jour le accesstoken et le tokenexpires_at dans la base de données avant de procéder à tout appel à l'API Zoho CRM. [2]
Étape 9. Pour vérifier à tout moment le statut de l'utilisateur actuellement authentifié, interrogez votre table users par session["userid"] et votre table zohoconnections par user_id. Retournez connected: true uniquement lorsqu'une ligne de connexion existe, accompagnée de l'adresse e-mail stockée. [4]
---
Erreurs courantes
- Mauvais centre de données. Si
ZOHODCest défini surcommais que vos utilisateurs sont sur le centre de données EU ou IN, l'URL user-info retournera une erreur ou une réponse vide. Déduisez toujours le DC depuis l'apidomainretourné dans le callback OAuth (repérez le segment aprèszohoapis.) et persistez-le. [8] - Champs d'identifiant d'organisation manquants. Le nom du champ d'identifiant d'organisation n'est pas cohérent entre les centres de données Zoho. Ne pas essayer les trois variantes (
orgid,organizationid,ZGID) avant de recourir à une solution de repli entraînera une logique de création d'organisation utilisant silencieusement le mauvais identifiant. [1] - Expiration du jeton en cours de requête. Les jetons d'accès expirent après environ 3600 secondes. Sans rafraîchissement proactif (la marge tampon de 120 secondes), les opérations longues rencontreront des erreurs 401 en cours d'exécution. [2]
- Cas limite des organisations à utilisateur unique. Pour les comptes sans organisation formelle, aucun des champs d'identifiant d'organisation ne sera peut-être renseigné. La solution de repli sûre consiste à utiliser le
ZUIDcomme identifiant d'organisation afin que la logique de création d'organisation en aval ne échoue pas. [1]
---
Ce qu'il faut vérifier
- Les scopes sont corrects : Confirmez que
ZohoCRM.users.ALLest inclus dans la liste des scopes de votre application enregistrée ; des scopes manquants restreignent silencieusement ce que l'endpoint user-info retourne. [7] - Le DC est correctement persisté : Après le callback OAuth, vérifiez que la colonne
dcdanszoho_connectionscorrespond au domaine régional réel du compte Zoho de l'utilisateur authentifié. [8] - Le rafraîchissement du jeton fonctionne : Après avoir stocké une connexion, simulez un scénario de quasi-expiration et confirmez que
getzohoconnectionretourne unaccess_tokenvalide et rafraîchi plutôt qu'un jeton expiré. [2]