Connecter des applications à l'API
Créez des clés API, autorisez des applications comme Zapier, et contrôlez ce à quoi elles peuvent accéder.
Pour les utilisateurs avancés
Cette page couvre le côté développeur d'ITB : les clés API et les connexions d'applications OAuth. Si vous voulez simplement transmettre des données à d'autres outils quand des événements se produisent, voir d'abord Webhooks.
Il existe deux façons pour une application externe d'accéder à votre compte via l'API externe Go Toolbelt :
- Clés API — vous créez une clé et la collez dans votre propre script ou un outil qui en demande une. Idéal pour les intégrations serveur à serveur et les logiciels personnalisés.
- OAuth — des applications comme Zapier vous envoient vers un écran de consentement ITB où vous approuvez l'accès en un clic. Aucune gestion de clé nécessaire.
Avant de commencer
- Les clés API et les webhooks se trouvent dans ParamètresIntégrations.
- Une clé API agit sur les données de votre propre compte. Elle accorde uniquement les permissions que vous choisissez à sa création, et la quasi-totalité des permissions sont en lecture seule (l'exception est la gestion des webhooks).
- Vous pouvez avoir jusqu'à 10 clés API actives à la fois.
Créer une clé API
Ouvrez la carte Clés API
Allez dans ParamètresIntégrations. La carte Clés API se trouve en haut.
Nommez la clé et choisissez les permissions
Cliquez sur Créer une clé API. Donnez à la clé un nom qui vous indique à quoi elle sert (par ex. « Intégration Zapier »), puis cochez les permissions nécessaires. Commandes (lecture) et Contacts (lecture) sont présélectionnées ; voir le tableau des permissions ci-dessous pour la liste complète.
Copiez la clé
Cliquez sur Créer la clé. Votre nouvelle clé apparaît une seule fois — copiez-la avec le bouton de copie et conservez-la en lieu sûr.
Copiez votre clé maintenant
La clé n'est affichée qu'une seule fois. Si vous la perdez, révoquez-la et créez-en une nouvelle — il n'existe aucun moyen de la revoir.
Ce que vous devriez voir
La nouvelle clé apparaît dans la liste des clés API avec son nom, ses badges de permissions et sa date de création. Une fois qu'une application commence à l'utiliser, une date Dernière utilisation apparaît aussi.
Si vous êtes le développeur : envoyez la clé dans l'en-tête X-API-Key sur les requêtes vers https://api.gotoolbelt.com/v1/.... La documentation interactive des points de terminaison se trouve sur api.gotoolbelt.com/docs (également accessible depuis la carte Clés API).
Révoquer une clé API
Trouvez la clé dans la liste des clés API et cliquez sur le bouton corbeille à côté.
Confirmez avec Révoquer. Toutes les intégrations utilisant cette clé cessent de fonctionner immédiatement.
Autoriser une application avec OAuth
Certaines applications (Zapier, Make, et d'autres partenaires enregistrés) se connectent via OAuth plutôt qu'avec une clé API. De votre côté, le flux se déroule ainsi :
Dans l'application externe, choisissez de connecter votre compte ITB / Go Toolbelt. L'application vous envoie vers un écran de consentement ITB (on vous demandera de vous connecter d'abord si ce n'est pas déjà fait).
L'écran de consentement affiche le nom de l'application, le compte avec lequel vous êtes connecté, et exactement ce que l'application pourra faire — par exemple « Voir vos Orders et les détails des commandes ».
Cliquez sur Autoriser l'accès pour approuver, ou Refuser pour annuler. Dans les deux cas, vous êtes renvoyé vers l'application.
Une application ne peut jamais recevoir plus de permissions que celles pour lesquelles elle a été enregistrée — la même liste que le tableau des permissions ci-dessous.
Vous ne pouvez pas enregistrer votre propre application OAuth
Les applications OAuth sont enregistrées par l'équipe ITB, pas depuis les paramètres de votre compte. Si vous construisez une intégration personnalisée pour vous-même, utilisez plutôt une clé API.
Connecter Zapier ou Make
Zapier et Make se connectent via le flux OAuth ci-dessus — recherchez l'application ITB / Go Toolbelt dans leur répertoire d'applications et cliquez sur connecter. Quand vous configurez un déclencheur Zap, Zapier crée automatiquement l'abonnement webhook correspondant sur votre compte, donc il n'y a rien à configurer vous-même dans Webhooks.
Déclencheurs Zapier disponibles : Order créée, approuvée, terminée, replanifiée et statut modifié, ainsi que facture payée et Report publié. Les charges utiles exactes sont documentées dans la référence des événements webhook.
Référence des permissions
Voici les permissions (scopes) qu'une clé API ou une application OAuth peut détenir :
| Permission | Scope | Ce qu'elle permet |
|---|---|---|
| Commandes (lecture) | orders:read | Voir les Orders et leurs détails |
| Contacts (lecture) | contacts:read | Voir les contacts |
| Factures et facturation (lecture) | billing:read | Voir les factures et transactions |
| Calendrier (lecture) | calendar:read | Voir les événements du calendrier et les disponibilités |
| Modèles (lecture) | templates:read | Voir les modèles de Report |
| Profil de l'entreprise (lecture) | company:read | Voir le profil de votre entreprise |
| Membres d'équipe (lecture) | team:read | Voir les membres de l'équipe |
| Notifications (lecture) | notifications:read | Voir les paramètres de notification |
| Webhooks (lecture) | webhooks:read | Voir les configurations des points de terminaison webhook |
| Webhooks (gestion) | webhooks:write | Créer, modifier et supprimer des points de terminaison webhook |
Toutes les permissions sauf Webhooks (gestion) sont en lecture seule — une clé ou une application connectée ne peut jamais créer, modifier ou supprimer vos Orders, contacts ou factures via l'API.
En cas de problème
- Une intégration a soudainement arrêté de fonctionner — vérifiez si sa clé API a été révoquée (la révocation est immédiate), et que la clé possède toutes les permissions dont l'intégration a besoin. Une requête à laquelle il manque une permission est refusée avec une erreur « missing required scope ».
- Erreurs « Invalid API key » — la clé a été mal saisie ou révoquée. Les clés ne peuvent pas être revues après leur création ; créez-en une nouvelle.
- Le bouton Créer la clé ne fait rien — vous avez besoin d'un nom et d'au moins une permission cochée ; vous avez peut-être aussi atteint la limite de 10 clés (révoquez d'abord une ancienne clé).
Sur le même sujet
- Événements webhook — chaque événement et la charge utile envoyée par l'API
- Webhooks — recevez des données d'événement en temps réel sur votre propre point de terminaison
- Intégrations — tout ce qui se trouve dans l'onglet Intégrations