Avec l'API et les webhooks, vous connectez votre salon à d'autres logiciels, comme votre logiciel de comptabilité, votre propre site web ou un tableau de bord fait maison. Pas besoin d'être développeur pour comprendre ce qu'ils font ; cette page l'explique et montre comment créer une clé et un webhook.
Cette fonction est encore marquée Bientôt disponible dans l'application : vous ne pouvez pas encore créer de clés API ni de webhooks. Si vous ouvrez Paramètres > Avancé > API & Webhooks, vous voyez seulement un message indiquant que la fonction arrive. Cette page décrit son fonctionnement dès que la fonction est activée pour votre salon.
Qu'est-ce qu'une API ?
Une API est un accord qui permet à deux programmes de communiquer. Là où vous ouvrez une liste de rendez-vous dans l'application, un autre programme peut récupérer ces mêmes données via l'API, automatiquement et sans intervention. Par exemple : votre logiciel de comptabilité récupère vos rendez-vous chaque nuit, ou votre site web affiche vos prestations et vos prix directement depuis Salonnare.
L'accès passe par une clé API : un code secret qui prouve qu'une demande vient de votre salon. Traitez cette clé comme un mot de passe.
Créer une clé API
Seul un administrateur peut créer et supprimer des clés.
-
Étape 1: Ouvrez API & Webhooks et cliquez sur Nouvelle clé
Allez dans Paramètres > Avancé > API & Webhooks. Dans l'onglet Clés API (1), cliquez sur Nouvelle clé (2).
(Agrandir l'image) -
Étape 2: Donnez un nom à la clé et choisissez ce qu'elle peut lire
Saisissez un Nom reconnaissable, par exemple le nom de l'intégration (1). Sous Que peut lire cette clé ?, cochez uniquement les données dont l'intégration a besoin (2) : Rendez-vous, Clients, Prestations ou Collaborateurs. Si la clé doit s'arrêter après un certain jour, choisissez une date sous Expire. Cliquez sur Créer (3).
Une clé API peut uniquement récupérer des données, jamais rien modifier. Les Clients sont des données personnelles : activez-les uniquement si votre partenaire d'intégration en a vraiment besoin. Un site web qui affiche vos prestations et vos prix n'a besoin que de Prestations et Collaborateurs.
(Agrandir l'image) -
Étape 3: Copiez la clé
La clé complète (1) ne s'affiche qu'une seule fois. Cliquez sur le bouton de copie (2) et transmettez la clé à votre partenaire d'intégration, ou conservez-la dans un gestionnaire de mots de passe. Fermez ensuite la fenêtre.
(Agrandir l'image) -
Étape 4: Votre clé dans la liste
Dans la liste, vous voyez le nom, le début de la clé, ce qu'elle peut lire, quand elle a été utilisée pour la dernière fois et quand elle expire (1). Renouveler (2) vous donne une nouvelle clé avec le même nom et les mêmes droits ; vous choisissez combien de temps l'ancienne fonctionne encore (plus immédiatement, 24 heures ou 7 jours), pour que votre partenaire d'intégration ait le temps de changer. Révoquer (3) arrête une clé immédiatement.
(Agrandir l'image)
Qu'est-ce qu'un webhook ?
Un webhook est l'inverse de l'API. Au lieu qu'un programme demande sans cesse s'il y a du nouveau, Salonnare envoie lui-même un message à une adresse (URL) dès que quelque chose se produit. Salonnare peut envoyer ces sept événements :
booking.created: un nouveau rendez-vous est ajouté : dans l'application, via votre page de réservation en ligne ou le widget, via Google Reserve, ou dès qu'une demande de réservation est confirmée (y compris chaque rendez-vous créé par une série récurrente)booking.updated: un membre du personnel modifie un rendez-vous dans l'application (y compris un changement de statut vers terminé ou non-présentation)booking.cancelled: un membre du personnel annule un rendez-vous dans l'applicationpayment.received: un membre du personnel encaisse à la caisseclient.created: un membre du personnel crée un client dans l'applicationclient.updated: un membre du personnel modifie les données d'un client dans l'applicationclient.deleted: un collaborateur supprime un client dans l'application. La notification ne contient que le numéro du client ; Salonnare conserve ensuite les notifications précédentes sur ce client sans nom ni coordonnées
Chaque événement provient d'une action d'un membre du personnel dans l'application. Une réservation en ligne via votre page de réservation ou Google, un client qui annule lui-même, une liste d'attente convertie, une série récurrente, une cure et un client qui se crée lui-même sur la page de réservation n'envoient pas de notification. Votre partenaire d'intégration les rattrape en récupérant régulièrement la liste des rendez-vous.
Configurer un webhook
-
Étape 1: Ouvrez l'onglet Webhooks
Allez dans Paramètres > Avancé > API & Webhooks et cliquez sur l'onglet Webhooks.
(Agrandir l'image) -
Étape 2: Cliquez sur Nouveau webhook
Cliquez sur Nouveau webhook.
(Agrandir l'image) -
Étape 3: Saisissez l'adresse et choisissez les événements
À URL, saisissez l'adresse que vous a fournie votre partenaire d'intégration ; elle commence par
https://(1). Cochez les événements auxquels l'intégration doit réagir (2 et 3). Actif est activé par défaut. Cliquez sur Enregistrer (4).
(Agrandir l'image) -
Étape 4: Copiez le secret
Salonnare signe chaque message avec un secret, afin que le destinataire puisse vérifier qu'il vient bien de votre salon. Le secret (1) ne s'affiche qu'une seule fois : copiez-le (2) et transmettez-le à votre partenaire d'intégration.
(Agrandir l'image) -
Étape 5: Tester et consulter les notifications
Le webhook figure maintenant dans la liste (1). Avec Test (3), Salonnare envoie immédiatement un message de test et vous voyez s'il est arrivé. Sous Notifications (4), vous voyez chaque notification avec son état (livrée, nouvel essai prévu ou échouée) et ses tentatives ; vous pouvez y renvoyer une notification échouée avec Renvoyer. Si vous avez perdu le secret, cliquez sur Nouveau secret (2) ; l'ancien ne fonctionne plus ensuite, le côté destinataire doit donc aussi être mis à jour.
(Agrandir l'image)
Et si...
... le test n'arrive pas ? Salonnare indique alors que l'adresse n'a pas répondu ou quel code d'erreur le destinataire a renvoyé. Vérifiez l'adresse et demandez à votre partenaire d'intégration pourquoi son côté refuse le message.
... une notification n'arrive pas une fois ? Salonnare réessaie alors : après environ 1 minute, 5 minutes, 30 minutes, 2 heures, 8 heures et 24 heures. Chaque tentative porte le même numéro de notification, pour que le destinataire reconnaisse une notification reçue deux fois. Si aucune tentative ne réussit et que rien d'autre n'est passé entre-temps, Salonnare désactive le webhook et vous prévient par une notification. Vous le réactivez en le modifiant et en activant Actif. Vous renvoyez les notifications échouées sous Notifications avec Renvoyer.
... l'adresse est refusée ? Un webhook doit pointer vers une adresse publique. Salonnare refuse les adresses d'un réseau interne ou privé, localhost et les adresses qui ne commencent pas par https://, avec un message qui indique le problème.
... vous soupçonnez qu'une clé a fuité ? Supprimez-la immédiatement avec la corbeille et créez-en une nouvelle.
Travailler en sécurité
- Ne partagez jamais publiquement les clés API ni les secrets de webhook (pas dans un e-mail ordinaire, sur une capture d'écran ou dans du code en ligne).
- Ne donnez à une intégration que les permissions dont elle a besoin.
- Supprimez les clés et les webhooks que vous n'utilisez plus.
Vous êtes développeur et cherchez les détails techniques (authentification, endpoints, champs, signatures) ? Consultez l'API Reference. Cette page est en anglais, car elle est écrite pour les développeurs.