Créer un client API Zoho pour Zefty (centres de données États-Unis et Canada)

Connecter Zefty à Zoho Books prend environ dix minutes, et la majeure partie se passe dans la console API de Zoho plutôt que dans Zefty. C'est là que vous créez un petit « client » qui permet à Zefty de lire vos factures et vos fournisseurs et d'inscrire les paiements en retour, sans jamais voir votre mot de passe Zoho. Ce guide couvre tout le processus, y compris la question qui fait trébucher le plus de gens : dans quel centre de données, .com ou .ca, se trouve votre compte Zoho.

Ce que vous créez, et pourquoi

Zoho Books n'accepte pas de nom d'utilisateur et de mot de passe provenant d'un logiciel tiers. Il utilise plutôt OAuth : vous enregistrez une application dans la console API de Zoho, Zoho vous remet un Client ID et un Client Secret, et vous approuvez une liste précise de permissions, une seule fois. Par la suite, Zefty conserve un jeton qu'il renouvelle automatiquement. Vous pouvez révoquer ce jeton à tout moment depuis votre compte Zoho, et Zefty n'enregistre jamais de mot de passe.

Les permissions demandées par Zefty sont volontairement restreintes :

Rien dans cette liste ne permet à Zefty de modifier des factures, de supprimer des enregistrements ou de toucher à vos clients.

Avant de commencer : dans quel centre de données Zoho êtes-vous ?

Zoho exploite des centres de données distincts, et chacun a sa propre console API. Si vous créez le client dans le mauvais, le Client ID ne fonctionnera pas, même si toutes les autres étapes semblent correctes.

Le moyen le plus rapide de le savoir : ouvrez Zoho Books et regardez la barre d'adresse.

• books.zoho.com signifie que votre compte est dans le centre de données américain (mondial). Utilisez https://api-console.zoho.com/. C'est de loin le cas le plus fréquent, y compris pour les entreprises canadiennes.
• books.zoho.ca signifie que votre compte est dans le centre de données canadien. Utilisez https://api-console.zoho.ca/. Cela concerne certains comptes Zoho propres au Canada.

Zefty pose la même question sur son écran de configuration, sous l'étiquette Domaine API Zoho / Pays, avec les choix États-Unis (zoho.com) et Canada (zohocloud.ca). La console utilisée et le choix fait dans Zefty doivent correspondre.

Étape 1 : trouver l'ID de votre organisation Zoho Books

1. Connectez-vous à Zoho Books.
2. Cliquez sur l'icône d'engrenage Paramètres.
3. Ouvrez Profil de l'organisation.
4. Copiez l'ID de l'organisation affiché en haut de la page.

Gardez-le sous la main. Zefty en a besoin en plus des identifiants du client, parce qu'un même compte Zoho peut posséder plusieurs organisations Books.

Étape 2 : ouvrir la bonne console API

Dans un nouvel onglet, rendez-vous à https://api-console.zoho.com/ ou à https://api-console.zoho.ca/, selon la vérification ci-dessus. Connectez-vous avec le compte Zoho propriétaire de l'organisation Books, ou avec un compte administrateur de celle-ci.

Étape 3 : créer une application de type « Server-based Applications »

1. Cliquez sur Add Client (sur certains comptes, le bouton se lit Create New Client ou Get Started).
2. Choisissez le type de client Server-based Applications. Ne prenez pas « Self Client », « Web-based » ni « Mobile » : seul le type serveur prend en charge le flux de redirection utilisé par Zefty.
3. Remplissez les trois champs exactement ainsi :
   • Client Name : Zefty
   • Homepage URL : https://zefty.ca/
   • Authorized Redirect URL : https://zefty.ca/authorize
4. Cliquez sur Create.

L'URL de redirection est la valeur qui doit être parfaite au caractère près. Si elle diffère de https://zefty.ca/authorize de quelque façon, y compris une barre oblique finale ou http au lieu de https, Zoho refusera de vous renvoyer vers Zefty après l'approbation des permissions.

Étape 4 : copier le Client ID et le Client Secret

Après la création, Zoho affiche la page Client Details. Elle présente deux valeurs :

• Client ID : une longue chaîne alphanumérique qui identifie l'application. Copiez-la en entier.
• Client Secret : une chaîne plus longue qui doit rester confidentielle. Copiez-la aussi en entier.

Revenez à la page de configuration de Zefty et collez-les dans Zoho Client ID et Zoho Client Secret. Veillez à ne pas inclure d'espace au début ou à la fin : un espace copié par mégarde est la deuxième cause la plus fréquente d'échec de connexion, après le mauvais centre de données.

Étape 5 : autoriser Zoho Books

Une fois la région, l'ID de l'organisation, le Client ID et le Client Secret saisis, cliquez sur Autoriser Zoho Books. Vous êtes dirigé vers la page de consentement de Zoho, qui liste les permissions décrites plus haut. Cliquez sur Accept.

Zoho vous redirige vers https://zefty.ca/authorize, Zefty échange le code à usage unique contre des jetons, et la première synchronisation démarre d'elle-même : les fournisseurs d'abord, puis les factures. Selon le nombre de factures, prévoyez jusqu'à quinze minutes. Par la suite, Zefty synchronise chaque nuit à 2 h et chaque fois que vous cliquez sur Synchroniser avec Zoho.

Si l'autorisation échoue : supprimer l'application et recommencer

Il arrive que le flux soit interrompu : un onglet fermé trop tôt, une mauvaise région choisie, un problème de réseau ou un secret mal copié. Dans ce cas, corriger le champ et cliquer de nouveau sur Autoriser ne suffit pas. Zoho ne permet à la poignée de main d'autorisation d'aboutir qu'une seule fois par application. Une application qui a subi un échec continuera d'échouer.

La récupération est courte :

1. Retournez dans la console API utilisée (api-console.zoho.com ou api-console.zoho.ca).
2. Repérez le client Zefty que vous avez créé.
3. Cliquez sur l'icône Delete pour le supprimer.
4. Créez une nouvelle application « Server-based Applications » avec les trois mêmes valeurs (nom, URL de la page d'accueil, URL de redirection).
5. Copiez le nouveau Client ID et le nouveau Client Secret dans Zefty, puis cliquez de nouveau sur Autoriser.

Comme les identifiants sont neufs, la poignée de main repart à zéro. Si elle échoue une deuxième fois, la cause est presque toujours le choix du centre de données : revérifiez l'URL de Zoho Books.

À savoir une fois connecté

• Les champs API se verrouillent après la configuration. La région, l'ID de l'organisation, le Client ID et le Client Secret apparaissent ensuite en lecture seule dans Configuration de Zoho. Pour connecter une autre organisation Zoho Books, ajoutez une nouvelle organisation dans Zefty depuis le menu de l'organisation.
• Le consentement peut être révoqué. Dans les applications connectées de votre compte Zoho, vous pouvez retirer Zefty à tout moment. Zefty cesse alors de synchroniser jusqu'à une nouvelle autorisation.
• Le client vous appartient. Il vit dans votre compte Zoho, pas dans celui de Zefty. Personne d'autre ne peut l'utiliser, et vous pouvez l'inspecter ou le supprimer quand vous le voulez.

À retenir

• Vérifiez d'abord l'URL de Zoho Books : .com signifie la console américaine, .ca la console canadienne. Le choix dans Zefty doit correspondre.
• Créez une application Server-based Applications nommée Zefty avec l'URL de redirection https://zefty.ca/authorize, exactement.
• Zefty demande un accès en lecture aux factures, aux contacts et à la banque, et un accès en lecture et création aux paiements fournisseurs. Rien de plus.
• Si l'autorisation échoue, supprimez l'application dans la console API et recréez-la. Zoho ne laisse chaque application compléter la poignée de main qu'une seule fois.
• La première synchronisation démarre automatiquement dès l'acceptation des permissions.

Pour voir ce qui se passe une fois la connexion établie, de la synchronisation nocturne au paiement inscrit dans Zoho Books, consultez la page sur l'intégration Zoho Books. Si vous bloquez à une étape, notre équipe de soutien peut vous guider dans la console, en français ou en anglais.