Comment récupérer les mises en page dans Zoho CRM

La récupération des mises en page dans Zoho CRM s'effectue le plus souvent via l'API Zoho CRM, qui vous permet d'extraire les métadonnées de mise en page — notamment les arrangements de champs et les structures de sections — pour n'importe quel module de votre compte. Chez Beam Help (support expert indépendant pour Zoho, et non le support officiel de Zoho), nous vous présentons ci-dessous les principales approches.

Pourquoi c'est important

Lorsque vous créez des intégrations, des interfaces personnalisées ou des automatisations, vous avez souvent besoin de connaître précisément la structure de la mise en page d'un module avant de pouvoir afficher ou valider correctement les données. Les mises en page définissent quels champs apparaissent, dans quel ordre et sous quelles sections — leur récupération par programmation est donc une étape fondamentale pour tout projet de développement sérieux sur Zoho CRM. Cela est également pertinent lorsque vous souhaitez auditer les différences de mise en page entre les profils ou synchroniser les modifications de mise en page vers un système externe. ^[3]

---

Étape par étape

Étape 1. Vérifiez que votre édition Zoho CRM prend en charge l'accès à l'API. Les API GraphQL, par exemple, ne sont pas disponibles dans les versions d'essai de Zoho CRM, assurez-vous donc que votre compte est sur un plan payant avant de tenter la récupération de métadonnées. ^[3]

Étape 2. Déterminez quelle interface API correspond à votre cas d'usage. Zoho CRM propose à la fois des points de terminaison de type REST et une API GraphQL. L'API GraphQL est particulièrement bien adaptée à la récupération de mises en page et de métadonnées, car elle expose un type racine Meta dédié qui couvre les modules, les utilisateurs, les profils, les rôles et les métadonnées associées en une seule requête. ^[3]

Étape 3. Authentifiez votre application via OAuth 2.0 pour obtenir un jeton d'accès valide. Tous les appels à l'API Zoho CRM nécessitent un jeton bearer limité aux permissions CRM appropriées. Consultez la documentation développeur de Zoho CRM pour connaître les portées OAuth correctes pour l'accès aux métadonnées.

Étape 4. Pour récupérer les métadonnées de mise en page via l'API GraphQL, envoyez une requête ciblant le type Meta. Le type Meta prend en charge la récupération depuis Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles et Widgets. Certains de ces types prennent également en charge le filtrage et la pagination, ce qui est utile lorsque vous n'avez besoin des mises en page que pour un module spécifique. ^[3]

Une requête GraphQL minimale ciblant les métadonnées de module ressemble à ceci :

query {
  Meta {
    Modules {
      _data {
        api_name
      }
    }
  }
}

Étendez le bloc _data avec les champs spécifiques aux mises en page dont votre intégration a besoin (tels que l'identifiant de mise en page, le nom ou les profils associés). ^[3]

Étape 5. Si vous travaillez dans un widget basé sur un navigateur ou une application côté client, envisagez d'utiliser le SDK JavaScript de Zoho CRM plutôt que des appels HTTP bruts. Le SDK offre une manière structurée d'effectuer des appels API depuis le contexte de l'interface de Zoho CRM, et des exemples de code pour récupérer les données de module sont disponibles dans le dépôt GitHub du SDK. ^[5]

Étape 6. Une fois les données de mise en page récupérées, comparez-les avec ce que vous voyez dans l'interface Zoho CRM en accédant à Configuration → Modules et champs. C'est dans cette zone que la personnalisation des modules et des mises en page est gérée, et cela constitue une vérification utile pour s'assurer que la réponse de l'API correspond à la configuration en production. ^{[1] [2]}

Étape 7. Si votre projet implique des mises en page basées sur Canvas (vues de détail d'enregistrement personnalisées), sachez que Canvas prend désormais en charge les vues pour les pages de création d'enregistrements en plus des vues de détail. Les vues Canvas peuvent également être exportées et importées entre des comptes CRM à l'aide d'une clé unique, valable pour une durée limitée. Si vous devez répliquer des mises en page entre organisations, ce mécanisme d'export/import peut compléter votre flux de travail de récupération via l'API. ^[8]

---

Erreurs courantes

• Restrictions des comptes d'essai. Les requêtes de métadonnées GraphQL sur un compte Zoho CRM en version d'essai échoueront. Passez à une édition payante avant de tester. ^[3]
• Incompatibilité de portées. Si votre jeton OAuth ne dispose pas de la portée de métadonnées CRM correcte, l'API retournera une erreur d'autorisation plutôt que les données de mise en page. Vérifiez toujours que les portées de votre jeton correspondent au point de terminaison que vous appelez.
• Confusion entre GraphQL et REST. Le type Meta et ses sous-types (dont Modules) sont spécifiques à l'API GraphQL. Si vous utilisez l'API REST, la structure des points de terminaison et le format de réponse diffèrent considérablement. Confondre les deux est une source courante d'erreurs inattendues. ^[3]
• Les mises en page Canvas sont distinctes. Les mises en page standard et les vues Canvas sont des constructions distinctes dans Zoho CRM. Les métadonnées API de la mise en page standard d'un module n'incluront pas automatiquement les détails du modèle Canvas. ^[8]

---

Ce qu'il faut vérifier

• Vérifiez que la réponse de l'API inclut les valeurs api_name des modules attendus et qu'elles correspondent aux noms de modules visibles sous Configuration → Modules et champs dans votre compte CRM. ^{[1] [3]}
• Assurez-vous que la pagination est gérée si votre CRM comporte un grand nombre de modules ou de mises en page — le type GraphQL Meta prend en charge la pagination pour certains sous-types, et les réponses tronquées constituent un échec silencieux courant. ^[3]
• Testez avec le SDK JavaScript si votre intégration s'exécute dans un widget Zoho CRM, afin de garantir que le contexte d'authentification correct est utilisé plutôt qu'un jeton OAuth géré manuellement. ^[5]