Comment récupérer les services dans Zoho

La récupération des services Zoho via la couche API nécessite une connexion OAuth valide, un jeton d'accès actif et le bon type d'application — une seule erreur sur ces éléments et chaque appel en aval retournera silencieusement None.

Pourquoi c'est important

Lorsque vous créez des automatisations ou des intégrations sur Zoho CRM ou Zoho Desk, chaque appel d'outil doit d'abord résoudre une instance API fonctionnelle pour l'utilisateur authentifié. Si la recherche de connexion échoue, ou si le jeton a expiré sans être renouvelé, aucune donnée de service ne sera retournée. Comprendre la chaîne de récupération complète — de la recherche en base de données au renouvellement du jeton jusqu'à l'instanciation de l'API — vous permet de diagnostiquer rapidement les pannes et de créer des intégrations plus robustes. En tant que support expert indépendant pour Zoho (et non le support officiel de Zoho), Beam Help documente ce flux afin que votre équipe puisse le maintenir en toute confiance.

Étape par étape

Étape 1. Vérifiez que vos variables d'environnement sont en place avant toute tentative de connexion. Vous avez au minimum besoin de ZOHOCLIENTID, ZOHOCLIENTSECRET et OPENROUTERAPIKEY définis dans un fichier .env à la racine du projet. Vous pouvez également définir ZOHO_DC pour cibler un centre de données spécifique (par exemple eu, in, com.au ou jp ; la valeur par défaut est com). ^[8]

Étape 2. Assurez-vous que le serveur est en cours d'exécution avant toute tentative de récupération. Démarrez-le avec :

python3 server.py

Vous pouvez confirmer qu'il est en écoute en exécutant lsof -i :8080. ^[8]

Étape 3. Récupérez la connexion Zoho stockée pour un utilisateur donné en appelant getzohoconnection(userid). Cette fonction interroge la table zohoconnections pour trouver le user_id correspondant. Si aucune ligne n'est trouvée, la fonction retourne None et aucune récupération ultérieure n'est possible. ^[3]

Étape 4. La fonction de connexion gère automatiquement l'expiration du jeton. Elle compare l'heure actuelle à tokenexpiresat, en appliquant une marge de renouvellement anticipé de 120 secondes pour réduire les erreurs 401 en cours de requête. Lorsqu'un renouvellement est nécessaire, elle appelle ZohoOAuth.refreshtokens() avec le refreshtoken stocké, puis écrit le nouvel accesstoken et le tokenexpires_at mis à jour dans la base de données avant de retourner l'objet de connexion renouvelé. ^[3]

Étape 5. Transmettez la connexion résolue à getzohoapi(userid, apptype), en spécifiant "crm" ou "desk" comme apptype. Cette fonction appelle getzoho_connection en interne, donc si la connexion est manquante, elle retourne immédiatement (None, None). ^[1]

Étape 6. Pour Zoho Desk en particulier, la fonction nécessite également un orgid. Elle lit deskorgid depuis l'enregistrement de connexion. Si ce champ est vide, elle découvre automatiquement l'organisation en appelant api.getall_organizations(), puis extrait l'id du premier élément de la liste data retournée et le persiste pour les appels futurs. ^[1]

Étape 7. Pour Zoho CRM, vous pouvez vérifier que la connexion fonctionne en contrôlant que le crmorgid stocké est présent dans la table zohoconnections. Le harnais de test effectue cette vérification en récupérant la ligne la plus récente et en transmettant crmorg_id à une étape de validation d'organisation sandbox. ^[5]

Étape 8. Une fois que vous disposez d'une instance API active, les appels d'outils sont distribués via executetoolwithrepair(), qui accepte l'objet api, l'apptype, une chaîne de caractères tool (nom de l'outil) et un dictionnaire params. La couche de streaming émet un événement de statut — "Calling Zoho tool: <toolname>..." — avant chaque exécution afin que vous puissiez observer la progression en temps réel. ^[2]

Étape 9. Si vous devez récupérer des informations sur l'utilisateur ou l'organisation indépendamment d'un appel d'outil, utilisez ZohoOAuth.getuserinfo(accesstoken). Cette fonction interroge https://accounts.zoho.<DC>/oauth/user/info avec un en-tête de jeton Bearer et retourne des champs incluant ZUID (identifiant utilisateur), Email et des identifiants d'organisation. Notez que les noms de champs varient selon le centre de données — la fonction essaie orgid, organization_id et ZGID dans cet ordre avant de se rabattre sur l'identifiant utilisateur. ^[4]

Pièges courants

• orgid manquant pour les appels Desk. Si deskorg_id n'est pas stocké et que l'appel de découverte automatique échoue également, le client API Desk sera initialisé avec une chaîne vide, ce qui entraînera l'échec silencieux de toutes les requêtes Desk ultérieures. Vérifiez toujours que l'ID d'organisation est persisté après la première connexion réussie. ^[1]
• Le renouvellement du jeton ne retourne pas d'accesstoken. La fermeture tokenrefresher vérifie la présence de la clé "accesstoken" dans la réponse de renouvellement ; si elle est absente, le renouvellement retourne None et l'instance API utilisera un jeton périmé. Cela signifie généralement que le refreshtoken lui-même a expiré et que l'utilisateur doit se reconnecter via le flux OAuth. ^[1]
• Incompatibilité de centre de données. La variable d'environnement ZOHO_DC doit correspondre à la région où le compte Zoho a été créé. Une incompatibilité entraîne l'envoi des appels OAuth et API vers le mauvais point de terminaison, produisant des erreurs d'authentification même avec des identifiants valides. ^{[4] [8]}
• Authentification des outils navigateur. Si vous utilisez des outils basés sur le navigateur (par exemple browsernavigateandscreenshot), la session navigateur est authentifiée séparément de la session API. Une session navigateur expirée retourne une erreur actionrequired invitant à effectuer un appel POST /api/browser/login plutôt qu'un renouvellement de jeton standard. ^[6]

Ce qu'il faut vérifier

• Confirmez qu'une ligne existe dans zohoconnections pour le userid cible et que tokenexpiresat est un horodatage Unix futur valide. ^[3]
• Vérifiez que deskorgid (pour Desk) ou crmorgid (pour CRM) est renseigné dans l'enregistrement de connexion afin que l'instance API s'initialise avec le bon contexte d'organisation. ^{[1] [5]}
• Après tout changement d'environnement, redémarrez le serveur (pkill -f "python3 server.py"; sleep 1; python3 server.py) et relancez une vérification de connexion pour vous assurer que les nouvelles variables sont chargées. ^[8]