Il arrive que quelqu’un veuille relier quelque chose à Stippa. Un créateur de sites qui veut refaire le formulaire de réservation à votre image, un comptable avec un script qui récupère le chiffre d’affaires, ou un service comme Zapier qui envoie un message dès qu’un rendez-vous arrive. Cette personne vous demande alors une clé API.
Cette page est pour vous, pas pour ce développeur. Vous n’avez pas besoin de savoir comment cela marche techniquement pour prendre la bonne décision. Ce dont le développeur a besoin se trouve dans la documentation développeur, qui est en anglais.
Qu’est-ce qu’une clé API ?
Un texte long et secret qui commence par stp_live_. Celui qui l’a peut faire au nom de votre
salon exactement ce que vous avez coché à la création, et rien d’autre.
Trois choses comptent plus que la technique :
- Une clé appartient à votre salon. Elle ne peut jamais atteindre les données d’un autre salon, même par accident.
- Une clé n’est pas un identifiant de connexion. Aucun mot de passe n’y est attaché et personne n’entre dans l’application avec. Elle ne sert qu’à la liaison elle-même.
- Une clé est un secret, comme la clé du salon. Celui qui l’a peut s’en servir. C’est précisément pour cela que le reste de cette page existe.
Quand en ai-je besoin ?
Seulement quand quelqu’un vous en demande une. Pour l’usage normal de Stippa, vous n’avez jamais besoin de clé API : le widget de réservation, le calendrier, les e-mails et le profil public fonctionnent tous sans.
Les cas typiques où cela se pose :
- Votre créateur de sites veut intégrer complètement la réservation dans votre site, plutôt que d’utiliser le widget standard.
- Quelqu’un veut verser vos rendez-vous automatiquement dans un tableur ou un logiciel de comptabilité.
- Vous voulez une notification dans Slack, Teams ou Zapier dès qu’une réservation arrive.
De quelle offre ai-je besoin ?
| Ce que vous voulez | À partir de |
|---|---|
| Lire des données : rendez-vous, clients, prestations, disponibilité | Groei |
| Faire créer ou modifier des données, et les webhooks | Pro |
Si vous revenez à une offre inférieure, la clé continue d’exister. Seuls les droits que votre offre ne donne plus cessent de fonctionner. Si vous remontez plus tard, la liaison repart tout de suite, sans que personne n’ait à régler quoi que ce soit.
Créer une clé
Les clés se trouvent dans l’application Dev, présente dans le sélecteur d’applications en haut à gauche dès que vous avez activé le module API access.
Activez le module
Allez dans Administration > Modules et activez API access. L’application Dev apparaît ensuite dans le sélecteur.
Allez dans Dev > Clés
Cliquez sur Nouvelle clé.
Donnez-lui un nom que vous comprendrez encore dans un an
Pas « test » ni « clé 2 », mais « Site Jansen Webdesign » ou « Liaison comptabilité ». Si vous devez un jour révoquer quelque chose, le nom est la seule chose qui vous dit quelle clé appartient à qui.
Ne cochez que ce qui est nécessaire
Des combinaisons prêtes à l’emploi vous sont proposées. Dans le doute, prenez Lecture seule : elle ne peut rien modifier. Ajouter des droits plus tard n’est pas possible, créer une deuxième clé si, et c’est l’ordre le plus sûr.
Copiez la clé tout de suite
Vous voyez la clé complète une seule fois, juste après la création. Ensuite, Stippa n’en garde qu’une forme chiffrée et nous ne pouvons plus vous la montrer non plus. Si vous l’avez perdue, révoquez-la et créez-en une nouvelle.
Transmettre une clé sans risque
L’envoyer une fois par e-mail puis l’oublier est la façon dont cela tourne mal le plus souvent : une boîte mail reste consultable des années, se partage et suit son propriétaire chez l’employeur suivant.
- Transmettez-la par un canal qui efface, ou par le gestionnaire de mots de passe que le développeur utilise de toute façon.
- Ne la mettez jamais dans un message public, un ticket ou un document partagé.
- Créez une clé par partenaire. Deux entreprises avec la même clé, c’est casser les deux liaisons le jour où vous devez en révoquer une.
- Demandez une date de fin si la mission est temporaire. Vous pouvez faire expirer une clé, et plus personne n’a besoin d’y penser ensuite.
Révoquer une clé
Allez dans Dev > Clés et choisissez Révoquer sur la clé concernée. Cela prend effet tout de suite : la requête suivante faite avec cette clé est refusée. Une révocation ne se défait pas, la liaison devra donc recevoir une nouvelle clé.
Révoquez en tout cas :
- quand la collaboration avec le prestataire ou l’agence s’arrête ;
- quand la clé s’est retrouvée quelque part où elle n’a rien à faire ;
- quand vous ne savez plus à quoi une clé sert. Une clé que personne ne sait rattacher à quelque chose ne devrait pas rester active.
Si vous hésitez sur une clé encore utilisée, regardez d’abord dans Dev > Journal. Vous y voyez, requête par requête, ce qui est arrivé et si cela a fonctionné. Une clé qui n’y figure plus depuis des mois peut être révoquée sans crainte.
Les webhooks, dans l’autre sens
Une clé laisse quelqu’un venir chercher des données chez vous. Un webhook fait l’inverse : Stippa envoie un message à une adresse web dès qu’il se passe quelque chose, par exemple quand un rendez-vous est pris ou annulé. C’est ce dont une liaison avec Slack ou Zapier a besoin. Les webhooks sont compris dans l’abonnement Pro et se trouvent dans Dev > Webhooks.
Une adresse de webhook mérite le même soin qu’une clé. À chaque événement, Stippa envoie à cette adresse les données correspondantes, noms, adresses e-mail et numéros de téléphone de vos clients compris. Celui qui peut régler l’adresse peut donc détourner ce flux ailleurs. Ne reprenez une adresse que de quelqu’un en qui vous avez confiance, et vérifiez la liste quand vous ne savez plus qui a réglé quoi.
Si une adresse reste injoignable, Stippa réessaie un certain nombre de fois puis désactive le point de réception tout seul, pour ne pas envoyer sans fin vers une adresse morte. Vous le voyez sous forme de message au-dessus de la liste, avec un bouton pour le réactiver dès que le destinataire refonctionne.
Questions fréquentes
Peut-on se connecter à Stippa avec ma clé ? Non. Une clé ne sert qu’à la liaison et ne donne accès ni à l’application, ni à votre compte, ni à votre abonnement.
Une clé peut-elle atteindre les données d’un autre salon ? Non. La clé détermine elle-même de quel salon il s’agit ; il n’existe aucun réglage qui permettrait d’en désigner un autre.
Je ne vois pas l’application Dev. Le module API access est désactivé, votre abonnement est Starter, ou vous êtes employé. L’application est visible pour les propriétaires et les administrateurs.
Mon développeur demande de la documentation. Envoyez-le vers la documentation développeur. Elle est en anglais et contient tout ce dont il a besoin, exemples compris.