Avec Zoho, la première chose à ne pas manquer n’est pas un identifiant — c’est la géographie. Zoho exploite des centres de données indépendants (.com, .eu, .in, .com.au, .jp et .zohocloud.ca), chacun avec ses propres serveurs d’authentification et sa propre copie de votre organisation. Une autorisation émise dans une région n’a aucune valeur dans une autre : Anexus vous demande donc votre centre de données avant toute redirection.
Deuxième chose à savoir avant de commencer : Zoho appelle ses types d’enregistrements des modules — Leads, Contacts, Comptes, Transactions. Anexus écrit dans le module Contacts, et le modèle de permissions de Zoho fonctionne module par module — d’où un écran de consentement inhabituellement précis.
Trouvez d’abord votre centre de données
Ouvrez Zoho CRM dans un navigateur et lisez la barre d’adresse. Le suffixe du domaine correspond à votre centre de données. Rien d’autre dans cet article ne fonctionnera tant que ce choix ne correspond pas.
| Votre URL Zoho se termine par… | Centre de données à choisir | Région |
|---|---|---|
.zoho.com | US | États-Unis |
.zoho.eu | EU | Europe |
.zoho.in | IN | Inde |
.zoho.com.au | AU | Australie |
.zoho.jp | JP | Japon |
.zohocloud.ca | CA | Canada |
Le centre de données est fixé à la création de l’organisation — se connecter ailleurs ne la déplace pas, et Zoho ne déménage une organisation d’une région à l’autre que sur demande auprès du soutien technique. Si vous vous connectez à la mauvaise région, Zoho vous dira simplement que le compte n’existe pas là-bas.
Équipes canadiennes : le centre de données CA de Zoho existe pour que les données CRM restent hébergées au Canada. Si votre organisation y a été créée, vos URL se terminent par zohocloud.ca, et CA est la seule option qui autorisera la connexion.
Avant de commencer
- Un compte Zoho CRM sur une édition qui expose l’API — l’édition gratuite comprise.
- Votre centre de données, selon le tableau ci-dessus.
- L’utilisateur Zoho qui se connectera et approuvera la connexion. Décidez qui ce sera avant de commencer, car l’autorisation est accordée en son nom.
- Le profil Zoho de cet utilisateur doit avoir les droits de création et de modification sur le module Contacts. Les profils Administrateur et Standard les possèdent ; un profil personnalisé restreint, pas forcément.
Connecter Anexus à Zoho CRM
Dans Anexus, ouvrez Paramètres → Intégrations CRM et repérez la carte Zoho CRM.
Dans le petit menu déroulant à côté du bouton Connecter, sélectionnez votre centre de données (US, EU, IN, AU, JP ou CA).
Cliquez sur Se connecter avec Zoho CRM. Vous arrivez sur la page de connexion Zoho de cette région.
Connectez-vous avec l’utilisateur choisi ci-dessus. Un compte Zoho peut appartenir à plusieurs organisations CRM — vérifiez le nom de l’organisation avant de continuer, car l’autorisation est liée à l’organisation où vous êtes connecté.
Zoho affiche son écran de consentement avec les deux portées ci-dessous. Cliquez sur Accepter.
Zoho vous redirige vers Anexus et la carte Zoho bascule à l’état vert « Connecté ».
Les deux portées de l’écran de consentement
Les portées Zoho nomment le module et l’opération : l’écran de consentement vous indique donc exactement jusqu’où une application peut aller. Anexus en demande deux :
- ZohoCRM.modules.contacts.ALL — lecture et écriture sur le seul module Contacts. Leads, Comptes et Transactions ne font pas partie de l’autorisation.
- ZohoCRM.users.READ — lecture de votre propre fiche utilisateur Zoho, utilisée pour afficher le nom du compte sur la carte connectée.
Si votre organisation Zoho restreint les applications tierces, un administrateur doit approuver Anexus une fois avant que quiconque puisse franchir cet écran.
Où arrive un contact capté dans Zoho
Chaque contact capté devient — ou met à jour — un enregistrement du module Contacts, et non du module Leads. Cette distinction compte davantage dans Zoho qu’ailleurs : les règles d’attribution des leads et le processus de conversion qui transforme un Lead en Contact, Compte et Transaction appartiennent au module Leads, et un enregistrement écrit directement dans Contacts ne passe jamais par eux. Les équipes qui trient à partir des Leads ajoutent plutôt une vue Contacts ou un flux de travail sur le module Contacts.
Anexus utilise le point de terminaison upsert de Zoho : si la même personne remplit deux fois votre formulaire d’échange, le Contact existant est mis à jour plutôt que dupliqué.
Correspondance des champs
Tous les champs ci-dessous aboutissent dans le module Contacts. Le nom d’API est celui que vous verriez dans les outils pour développeurs de Zoho ou dans une exportation.
| Champ Anexus | Libellé du champ Zoho | Nom d’API | Particularité Zoho |
|---|---|---|---|
| Prénom | First Name | First_Name | Facultatif dans Zoho. |
| Nom de famille | Last Name | Last_Name | Le seul champ système obligatoire d’un Contact Zoho. Il prend la valeur « Unknown » si la personne n’en a pas fourni, sinon Zoho rejette l’enregistrement. |
| Courriel | Email | Un contact capté sans adresse courriel valide n’est jamais envoyé à un CRM. | |
| Téléphone | Phone | Phone | Zoho garde Téléphone et Mobile comme deux champs distincts ; la valeur va dans Téléphone. |
| Fonction | Title | Title | Dans Zoho, « Title » désigne la fonction — la civilité se trouve dans le champ distinct « Salutation ». |
| Entreprise | Account Name | Account_Name | Un champ de recherche vers le module Comptes, et non une zone de texte libre. |
« Account Name » est la ligne qui ne se comporte pas comme les autres. Sur un Contact Zoho, il s’agit d’un champ de recherche pointant vers un enregistrement du module Comptes plutôt que d’une zone de texte libre — un fonctionnement propre à Zoho.
Les contacts captés avant la connexion ne partent pas d’eux-mêmes. Utilisez Synchroniser les contacts passés sur la carte Zoho pour les envoyer.
Limites Zoho à connaître avant de synchroniser un gros lot de contacts passés
- Zoho mesure l’utilisation de l’API à l’échelle de l’organisation, sous forme d’allocation quotidienne calculée d’après votre édition et votre nombre d’utilisateurs — et non par intégration. Anexus partage cette allocation avec tous les autres outils branchés sur la même organisation Zoho.
- Les points de terminaison d’enregistrements de Zoho acceptent au maximum 100 enregistrements par appel : synchroniser quelques milliers de contacts passés est donc forcément une longue série d’appels plutôt qu’un seul envoi.
- Il existe aussi un plafond d’appels API simultanés par organisation. Si vous dépassez l’une ou l’autre limite, Zoho répond
TOO_MANY_REQUESTS; les contacts concernés restent en attente jusqu’à ce que vous cliquiez de nouveau sur Synchroniser les contacts passés. - Les jetons d’accès Zoho durent environ une heure et sont renouvelés en arrière-plan à partir du jeton de rafraîchissement. Vous n’avez jamais à y toucher.
En cas de problème
« Invalid Client » sur l’écran de consentement Zoho
De loin l’échec le plus fréquent avec Zoho, et c’est toujours le centre de données. Anexus est enregistrée comme un client distinct dans chaque région Zoho : un identifiant client connu des serveurs américains ne signifie rien pour les serveurs européens. Déconnectez-vous, choisissez le centre de données correspondant à votre URL Zoho, et recommencez.
Connecté, mais rien n’apparaît dans Contacts
Un compte Zoho peut appartenir à plusieurs organisations CRM, et l’autorisation est liée à celle où vous étiez connecté. Comparez le nom de l’organisation affiché dans le menu de compte Zoho avec celle que vous consultez, et reconnectez-vous depuis la bonne si elles diffèrent. Avant de conclure que rien n’est arrivé, cherchez aussi l’adresse courriel de la personne dans Zoho : un upsert qui trouve un Contact existant le met à jour sur place, sans ajouter de nouvelle ligne en tête de liste.
MANDATORY_NOT_FOUND, ou des Contacts qui arrivent avec des champs vides
Les mises en page Zoho permettent à un administrateur de rendre des champs personnalisés obligatoires. La synchronisation n’envoie que les champs standard décrits plus haut : un champ personnalisé obligatoire reste donc vide sur le Contact enregistré ou, lorsque Zoho l’impose au niveau de l’API, l’enregistrement est rejeté avec MANDATORY_NOT_FOUND. Demandez à votre administrateur de rendre ces champs facultatifs dans la mise en page Contacts, de leur donner des valeurs par défaut, ou remplissez-les après coup.
Zoho répond NO_PERMISSION
Les portées sont accordées au niveau de l’application, mais Zoho applique aussi le profil de l’utilisateur qui a autorisé à chaque appel d’API, et renvoie NO_PERMISSION lorsque ce profil n’autorise pas l’opération. Demandez à un administrateur d’accorder à ce profil les droits de création et de modification sur le module Contacts, ou reconnectez-vous avec un utilisateur qui les possède déjà.
INVALID_TOKEN après des mois de bon fonctionnement
Les jetons de rafraîchissement Zoho expirent pour des raisons précises : un administrateur a révoqué Anexus dans la liste des applications connectées, l’utilisateur qui avait autorisé a été désactivé ou retiré de l’organisation, ou l’organisation a été migrée vers un autre centre de données. Zoho plafonne aussi le nombre de jetons de rafraîchissement qu’une application peut détenir par utilisateur : se reconnecter sans cesse sans se déconnecter d’abord peut donc retirer discrètement le plus ancien. Dans tous les cas, la solution est la même — Déconnecter dans Anexus, puis reconnecter.
TOO_MANY_REQUESTS pendant la synchronisation des contacts passés
Votre organisation a épuisé son allocation d’API quotidienne ou atteint le plafond de simultanéité — souvent parce qu’une autre intégration la partage. Rien n’est perdu : les contacts refusés restent en attente. Patientez un moment, puis cliquez de nouveau sur Synchroniser les contacts passés pour réessayer. Zoho affiche la consommation d’API de l’organisation dans la configuration, dans sa section développeur/API, si vous voulez voir ce qui la consomme.
Se déconnecter et révoquer du côté de Zoho
Cliquez sur Déconnecter dans Anexus. Les Contacts déjà créés ou mis à jour restent dans Zoho — rien n’est supprimé de votre module Contacts.
Pour aussi invalider le jeton de rafraîchissement du côté de Zoho, connectez-vous à votre compte Zoho sur le domaine de votre région — la règle du centre de données s’applique ici aussi — cliquez sur votre profil et ouvrez Mon compte → Jetons d’authentification actifs (Zoho renomme cette page de temps à autre : cherchez les applications connectées ou autorisées). Trouvez Anexus Connect et cliquez sur Révoquer. C’est cette révocation qui supprime réellement l’autorisation ; la déconnexion dans Anexus nous empêche seulement de l’utiliser.