Comment récupérer les règles d'affectation dans Zoho

La récupération des règles d'affectation dans Zoho CRM s'effectue via une seule requête GET authentifiée vers l'endpoint /settings/assignment_rules, en passant le module cible en paramètre.

Pourquoi c'est important

Les règles d'affectation contrôlent la façon dont les enregistrements entrants — prospects, contacts, affaires, et plus encore — sont automatiquement distribués à votre équipe commerciale. Si vous construisez une intégration, auditez votre configuration CRM ou synchronisez des règles vers un système externe, vous devrez récupérer ces règles par programmation. Cela est également utile pour diagnostiquer pourquoi des enregistrements ne sont pas acheminés comme prévu. Pour rappel, Beam Help est un support expert indépendant pour Zoho et ne constitue pas le support officiel de Zoho.

---

Étape par étape

Étape 1. Enregistrez votre application et obtenez des identifiants OAuth en visitant la Zoho API Console, en créant une application de type Server-based Application, et en notant votre Client ID et votre Client Secret. Définissez votre URI de redirection (par exemple, http://localhost:8080/api/auth_callback) et assurez-vous d'inclure le scope ZohoCRM.settings.ALL parmi vos scopes sélectionnés. ^[8]

Étape 2. Générez une URL d'autorisation OAuth en construisant une requête avec vos paramètres clientid, redirecturi, scope, responsetype et accesstype. Le paramètre access_type doit être défini sur offline et prompt sur consent afin qu'un refresh token soit émis en même temps que l'access token. ^[2]

Étape 3. Échangez le code d'autorisation retourné par Zoho contre un access token et un refresh token. Envoyez une requête POST vers l'endpoint de token de Zoho avec granttype: authorizationcode, votre clientid, clientsecret, redirecturi et la valeur code. Stockez de manière sécurisée les valeurs accesstoken, refreshtoken, apidomain et tokenexpiresat obtenues pour une utilisation ultérieure. ^[2]

Étape 4. Lorsque votre access token expire, utilisez le refresh token stocké pour en obtenir un nouveau. Envoyez une requête POST avec granttype: refreshtoken ainsi que votre clientid et clientsecret. Mettez à jour vos valeurs accesstoken et tokenexpires_at après chaque rafraîchissement réussi afin que les appels suivants restent authentifiés. ^[3]

Étape 5. Avec un access token valide en main, appelez l'endpoint des règles d'affectation. Émettez une requête GET vers :

GET /settings/assignment_rules?module=<ModuleName>

Le paramètre module (désigné par m dans l'implémentation sous-jacente) spécifie les règles d'affectation du module Zoho CRM que vous souhaitez récupérer — par exemple, Leads, Contacts ou Deals. ^[1]

En Python, cet appel ressemble à :

def get_assignment_rules(self, m: str):
    return self.c.request("GET", "/settings/assignment_rules", {"module": m})

L'objet client (self.c) doit déjà détenir un access token valide et rafraîchi avant d'effectuer cet appel. ^[1]

Étape 6. Gérez la réponse. Un appel réussi retourne les règles d'affectation configurées pour le module spécifié. Si le token a expiré ou si le scope est insuffisant, vous recevrez une erreur d'authentification — dans ce cas, déclenchez le flux de rafraîchissement du token décrit à l'étape 4 et réessayez. ^[3]

---

Erreurs courantes

• Scope manquant. Si ZohoCRM.settings.ALL n'est pas inclus dans votre configuration de scope OAuth, l'API rejettera la requête. Vérifiez vos scopes enregistrés dans la Zoho API Console et dans votre configuration d'environnement. ^[8]

• Access token expiré. Les access tokens Zoho ont une durée de vie limitée (généralement 3600 secondes). Si tokenexpiresat est dépassé et que vous n'avez pas effectué de rafraîchissement, l'appel échouera. Vérifiez toujours l'expiration avant d'effectuer une requête et rafraîchissez de manière proactive. [^2, ^3]

• Mauvais centre de données. Zoho opère sur plusieurs centres de données (com, eu, in, com.au, jp). La valeur api_domain retournée lors de l'échange de token doit être utilisée comme URL de base pour tous les appels API — ne codez pas en dur https://www.zohoapis.com si votre organisation se trouve sur un autre DC. [^5, ^8]

• Sensibilité à la casse du nom de module. Le paramètre module doit correspondre exactement au nom d'API interne du module Zoho CRM. Utilisez le nom d'API (par exemple, Leads et non leads) pour éviter une erreur « module introuvable ». ^[1]

---

Ce qu'il faut vérifier

• Le scope est présent : Confirmez que ZohoCRM.settings.ALL apparaît dans vos scopes OAuth enregistrés et dans votre configuration .env avant d'effectuer l'appel. ^[8]
• Le token est à jour : Vérifiez que votre valeur tokenexpiresat stockée est dans le futur ; si ce n'est pas le cas, exécutez le flux de rafraîchissement avant d'appeler l'endpoint. ^[3]
• URL de base correcte : Assurez-vous d'utiliser la valeur api_domain retournée lors de l'échange de token comme racine de vos requêtes API, et non un domaine codé en dur. ^[5]