La récupération des pipelines dans Zoho CRM est simple une fois votre connexion OAuth établie — vous pouvez interroger l'API des modules CRM pour extraire directement les données de pipeline (étapes des affaires) depuis votre compte.
Pourquoi c'est important
Les équipes commerciales s'appuient sur les pipelines pour suivre les affaires à chaque étape de l'entonnoir de vente. Si vous construisez une intégration, automatisez des rapports ou utilisez un outil comme le Zoho AI Pilot Engine de Beam Help, vous devrez récupérer les données de pipeline et de module par programmation. Comprendre les scopes et le flux API corrects vous garantit des données précises et en temps réel, plutôt que des instantanés obsolètes.
Étape par étape
Étape 1. Configurez vos identifiants API Zoho en vous rendant sur la Zoho API Console et en créant une Application basée sur un serveur. Notez votre Client ID et votre Client Secret — vous aurez besoin des deux pour authentifier toute requête API.[1]
Étape 2. Lors de l'enregistrement de votre application, veillez à inclure le scope ZohoCRM.modules.ALL ainsi que ZohoCRM.settings.ALL et ZohoCRM.users.ALL. Le scope modules est celui qui accorde l'accès aux données de pipeline et d'étapes des affaires dans Zoho CRM.[1]
Étape 3. Définissez votre URI de redirection pour qu'elle corresponde exactement à ce qui est enregistré dans l'API Console. Si vous travaillez en local, il s'agit généralement de http://localhost:8080/api/auth_callback. Une différence ici provoquera une erreur de redirection OAuth et bloquera l'échange de jeton.[1]
Étape 4. Stockez vos identifiants de manière sécurisée dans un fichier .env à la racine du projet. Les variables minimales requises sont ZOHOCLIENTID, ZOHOCLIENTSECRET, et votre paramètre de centre de données (ZOHO_DC), qui est com par défaut mais peut être défini sur eu, in, com.au ou jp selon l'emplacement d'hébergement de votre compte Zoho.[1]
Étape 5. Établissez la connexion OAuth. Une fois votre serveur démarré, cliquez sur Connect Zoho CRM dans l'interface et complétez le flux d'autorisation. Le système stocke votre jeton d'accès et votre jeton de rafraîchissement afin que les requêtes suivantes soient traitées automatiquement.[2]
Étape 6. La couche de connexion rafraîchit automatiquement votre jeton d'accès lorsqu'il arrive à expiration dans moins de 120 secondes, de sorte que les requêtes de pipeline de longue durée n'échoueront pas en cours d'exécution avec une erreur 401. Cette opération est gérée de manière transparente — vous n'avez pas besoin de gérer la rotation des jetons manuellement.[6]
Étape 7. Pour récupérer les données de pipeline, formulez une requête en langage naturel telle que *« montrez-moi toutes les affaires »* ou *« listez les opportunités ouvertes »*. En interne, cela correspond à un appel search_records sur le module Deals, qui contient les étapes du pipeline pour chaque enregistrement.[7]
Étape 8. Si vous souhaitez obtenir un décompte des enregistrements à chaque étape du pipeline, vous pouvez demander *« combien d'affaires ai-je »* — cela est acheminé vers l'outil getrecordcount avec le module Deals comme paramètre, vous donnant rapidement le volume du pipeline.[7]
Étape 9. Pour les liens directs vers les enregistrements, le modèle d'URL CRM suit https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. Remplacez le code de votre centre de données et le nom du module concerné (par ex. Deals) pour créer des liens profonds vers des enregistrements de pipeline spécifiques.[5]
Erreurs courantes
- URI de redirection incorrecte. L'URI de redirection dans votre
.envet dans la Zoho API Console doit être identique caractère par caractère. Même une différence de barre oblique finale fera échouer le callback OAuth.[1] - Scope de module manquant. Omettre
ZohoCRM.modules.ALLde votre liste de scopes signifie que les endpoints de pipeline et d'étapes des affaires retourneront des erreurs de permission. Incluez toujours les trois scopes recommandés lors de l'enregistrement de l'application.[1] - Mauvais centre de données. Si votre compte Zoho est sur le centre de données EU ou Inde et que
ZOHODCest laissé surcom, les appels API atteindront le mauvais endpoint et retourneront des échecs d'authentification. DéfinissezZOHODCpour qu'il corresponde à la région de votre compte.[1] - État de base de données obsolète. Si vous rencontrez des erreurs inattendues après avoir modifié vos identifiants ou réautorisé l'application, supprimer le fichier SQLite local (
data/zpilot.sqlite) et redémarrer le serveur force un état propre.[2]
Ce qu'il faut vérifier
- Confirmez que
ZohoCRM.modules.ALLetZohoCRM.settings.ALLsont tous deux répertoriés parmi les scopes approuvés de votre application dans la Zoho API Console.[1] - Vérifiez que
ZOHO_DCdans votre.envcorrespond au centre de données affiché dans l'URL de votre compte Zoho CRM (par ex.eupourcrm.zoho.eu).[1] - Après la connexion, testez le chemin de rafraîchissement du jeton en attendant un état proche de l'expiration ou en vérifiant que la table
zohoconnectionsest mise à jour avec un nouveauaccesstokenettokenexpiresat.[6]
---
*Beam Help est un service d'assistance expert indépendant pour Zoho — nous ne sommes pas le support officiel de Zoho, et ces conseils sont basés sur notre propre expérience d'implémentation.*