Comment récupérer les champs dans Zoho

Récupérer les champs dans Zoho CRM nécessite d'appeler le bon endpoint API avec une authentification valide et le bon contexte de module ou de mise en page — voici comment procéder de manière fiable.

Pourquoi c'est important

Lors de la création d'intégrations, d'automatisations ou de rapports personnalisés, vous devez savoir exactement quels champs existent dans un module ou une mise en page Zoho CRM donné. Sans les noms API de champs corrects, les requêtes et les filtres échoueront avec des erreurs « colonne invalide ». Comprendre comment récupérer les champs par programmation vous aide également à éviter de coder en dur des noms de champs qui peuvent différer d'une organisation à l'autre.

Étape par étape

Étape 1. Assurez-vous que votre connexion OAuth est établie et que les tokens sont valides.

Avant tout appel API, votre intégration doit disposer d'un token d'accès valide pour l'organisation Zoho CRM cible. La connexion est stockée avec les valeurs refreshtoken, accesstoken, apidomain et tokenexpires_at. Si le token d'accès a expiré, un flux de rafraîchissement du token en récupère automatiquement un nouveau à l'aide du refresh token stocké, puis persiste le token mis à jour dans l'enregistrement de connexion. ^[3]

Étape 2. Identifiez le bon centre de données pour votre organisation.

Zoho CRM est hébergé sur plusieurs centres de données. L'URL de base pour le CRM suit le modèle https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, où {dc} est le suffixe du centre de données (par exemple, com, eu, in, com.au). Le centre de données est généralement déduit de l'api_domain retourné lors de l'OAuth — plus précisément la partie après zohoapis. dans cette chaîne de domaine. ^[1][5]

Étape 3. Déterminez si vous avez besoin des champs au niveau du module ou au niveau de la mise en page.

Zoho CRM distingue les champs attachés à l'ensemble d'un module et les champs limités à une mise en page spécifique au sein de ce module. Si vous avez besoin de champs spécifiques à une mise en page, vous devez d'abord connaître le layoutId de la mise en page ciblée. Les identifiants de mise en page peuvent être récupérés depuis l'endpoint des mises en page avant de procéder à l'appel des champs.

Étape 4. Appelez l'endpoint des champs pour la mise en page concernée.

Pour récupérer les champs limités à une mise en page particulière, effectuez une requête GET vers /api/v1/layouts/{layoutId}/fields, en substituant l'identifiant de mise en page réel. Un dictionnaire de paramètres de requête optionnel (p) peut être transmis pour filtrer ou paginer les résultats. ^[4]

Voici un exemple Python minimal de cet appel :

def get_layout_fields(self, layoutId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/layouts/{layoutId}/fields", p, None)

^[4]

Étape 5. Confirmez que les scopes OAuth requis sont en place.

Le token OAuth utilisé doit inclure les scopes Zoho CRM appropriés. Les scopes nécessaires pour un accès CRM étendu incluent notamment ZohoCRM.modules.ALL et ZohoCRM.org.ALL. Sans ces scopes, l'API retournera une erreur 401 ou une erreur de permission. ^[8]

Étape 6. Gérez les erreurs de manière appropriée.

Si l'API retourne un message « colonne invalide », cela signifie généralement que le nom API du champ fourni dans une requête ultérieure ne correspond pas à ce qui a été retourné par l'endpoint des champs. Si un statut 401 est retourné, le token d'accès a été rejeté et l'utilisateur doit reconnecter son compte Zoho. ^[6]

---

Erreurs courantes

• Mauvais centre de données : Utiliser crm.zoho.com alors que votre organisation est sur crm.zoho.eu entraînera des échecs d'authentification ou des réponses vides. Déduisez toujours le centre de données depuis l'api_domain stocké lors de l'OAuth. ^[5]
• layoutId manquant : L'endpoint /api/v1/layouts/{layoutId}/fields nécessite un identifiant de mise en page valide. Passer un identifiant vide ou incorrect fera échouer la requête. ^[4]
• Tokens expirés : Si le token d'accès a expiré et que le flux de rafraîchissement échoue (par exemple, parce que le refresh token a été révoqué), l'instance API retournera None et aucun champ ne sera récupéré. Vérifiez toujours que le rafraîchisseur de token retourne un token d'accès valide avant de continuer. ^[3]
• Scopes insuffisants : Si l'autorisation OAuth n'incluait pas ZohoCRM.modules.ALL ou l'équivalent, les appels de récupération des champs seront rejetés. Vérifiez les scopes configurés et réautorisez si nécessaire. ^[8]
• « Colonne invalide » sur les requêtes suivantes : Après avoir récupéré les champs, utilisez le nom API exact (et non le libellé d'affichage) lors de la construction de filtres ou de requêtes COQL. Une discordance déclenche une erreur « nom de colonne invalide ». ^[6]

---

Ce qu'il faut vérifier

• Validité du token : Confirmez que l'access_token stocké est à jour et que le rafraîchisseur de token peut en obtenir un nouveau avec succès si nécessaire. ^[3]
• Identifiant de mise en page correct : Vérifiez que le layoutId que vous transmettez à /api/v1/layouts/{layoutId}/fields correspond à une mise en page réelle dans le module cible. ^[4]
• Couverture des scopes : Vérifiez que votre autorisation OAuth inclut ZohoCRM.modules.ALL (ou le scope minimum requis) afin que l'endpoint des champs soit accessible. ^[8]

---

*Beam Help fournit une assistance experte indépendante pour Zoho — nous ne sommes pas le support officiel de Zoho. Pour les problèmes au niveau de la plateforme, référez-vous toujours à la documentation officielle de l'API Zoho CRM.*