Comment récupérer les paramètres d'automatisation dans Zoho

La récupération des paramètres d'automatisation dans Zoho CRM s'effectue via une seule requête GET authentifiée vers le point de terminaison /settings/automation, avec un filtrage optionnel par module. Voici tout ce que notre équipe chez Beam Help — support expert indépendant pour Zoho, et non le support officiel de Zoho — a documenté pour effectuer cet appel de manière fiable.

Pourquoi c'est important

Lorsque vous devez auditer, répliquer ou dépanner des règles de workflow et une logique d'automatisation dans Zoho CRM, vous avez besoin d'un moyen programmatique pour extraire la configuration actuelle. Le point de terminaison /settings/automation vous offre exactement cela, en renvoyant les paramètres d'automatisation de votre organisation — ou d'un module spécifique si vous affinez la requête. Cela est particulièrement utile lors de la création d'outils d'administration, de l'exécution de contrôles de conformité ou de la migration de paramètres entre environnements.

Étape par étape

Étape 1. Vérifiez qu'une connexion OAuth valide existe.

Avant qu'un appel API puisse aboutir, votre intégration doit disposer d'un jeton d'accès actif pour l'utilisateur cible. L'enregistrement de connexion est recherché dans votre store local par user_id, et si le jeton arrive à expiration dans moins de 120 secondes, il est automatiquement renouvelé avant l'envoi de la requête — cette fenêtre de renouvellement proactif est conçue pour éviter les erreurs 401 en cours de requête. ^[5]

Étape 2. Obtenez une instance du client API Zoho CRM.

Appellez getzohoapi(userid, apptype="crm") pour recevoir un objet API entièrement initialisé. En interne, cette fonction récupère la connexion stockée, configure un callback tokenrefresher qui va chercher un nouveau accesstoken auprès du point de terminaison de jeton de Zoho lorsque nécessaire, et retourne une instance ZohoCrmApi prête à effectuer des appels. ^[1]

Le tokenrefresher fonctionne en lisant le dernier refreshtoken depuis la base de données, en le soumettant à l'URL de jeton de Zoho avec votre clientid et votre clientsecret, puis en persistant le nouveau accesstoken et tokenexpiresat dans la table zohoconnections. ^{[1] [2]}

Étape 3. Appelez le point de terminaison des paramètres d'automatisation.

Avec votre objet API en main, invoquez la méthode get_automation :

result = api.get_automation()          # all modules
result = api.get_automation(m="Leads") # scoped to a specific module

En coulisses, cela émet une requête GET vers /settings/automation, en ajoutant {"module": m} comme paramètre de requête uniquement lorsqu'un nom de module est fourni. ^[3]

L'identifiant de l'opération est get_automation et la méthode HTTP est GET /settings/automation. ^[3]

Étape 4. Traitez la réponse.

La méthode retourne ce que l'API REST de Zoho CRM renvoie — généralement un objet JSON contenant vos règles d'automatisation. Vérifiez les clés de premier niveau pour détecter d'éventuelles erreurs avant de traiter les données. Si le jeton avait expiré silencieusement, le callback token_refresher se déclenche automatiquement et le client réessaie, de sorte que les échecs d'authentification transitoires sont gérés sans code supplémentaire de votre côté. ^{[1] [5]}

Étape 5. (Optionnel) Limitez la portée par module.

Passez le nom du module CRM comme argument m — par exemple "Leads", "Contacts" ou "Deals" — pour limiter la réponse aux règles d'automatisation appartenant uniquement à ce module. Omettre l'argument renvoie les paramètres de tous les modules. ^[3]

Erreurs courantes

• Enregistrement de connexion manquant ou expiré. Si getzohoconnection retourne None parce qu'aucune ligne n'existe dans zohoconnections pour le userid donné, getzohoapi retournera également None et tout appel API ultérieur échouera avec une erreur d'attribut. Vérifiez toujours que le flux OAuth s'est terminé avec succès et qu'une ligne de connexion a été persistée avant de tenter la récupération des paramètres. ^{[1] [5]}

• Mauvais apptype. Le point de terminaison des paramètres d'automatisation se trouve dans Zoho CRM, donc apptype doit être "crm". Passer "desk" oriente le client vers ZohoDeskApi à la place, qui cible un ensemble de points de terminaison complètement différent et n'exposera pas les paramètres d'automatisation CRM. ^[1]

• Boucle de renouvellement de jeton sur un mauvais refreshtoken. Si ZohoOAuth.refreshtokens retourne un payload sans clé access_token — par exemple lorsque le jeton de renouvellement a été révoqué — le refresher retourne None et l'appel échouera. La solution consiste à relancer le flux d'autorisation OAuth pour obtenir une nouvelle paire de jetons. ^{[2] [5]}

• Incompatibilité de port lors de l'OAuth initial. L'URI de redirection OAuth est enregistrée pour http://localhost:8080/api/authcallback. Exécuter le serveur sur un autre port entraînera l'échec du callback d'autorisation, ce qui signifie qu'aucun jeton ne sera jamais stocké et que chaque appel API en aval — y compris getautomation — n'aura rien sur quoi travailler. ^[4]

Ce qu'il faut vérifier

• Confirmez qu'un jeton valide est stocké — interrogez zohoconnections pour le userid cible et vérifiez que tokenexpiresat est dans le futur, ou que le chemin de renouvellement est fonctionnel.
• Vérifiez la structure de la réponse du point de terminaison — assurez-vous que le JSON retourné contient les clés de règles d'automatisation attendues et qu'il ne s'agit pas d'un objet d'erreur (par ex. {"code": "INVALID_TOKEN", ...}).
• Confirmez l'orthographe du nom du module — si vous avez passé le paramètre m, vérifiez le nom API du module (sensible à la casse) par rapport à votre liste de modules Zoho CRM pour éviter une réponse vide ou erronée. ^[3]