Paramètres

API & Webhooks

Ce que sont l'API et les webhooks de Salonnare, et étape par étape comment créer une clé API et configurer un webhook.

6 min de lecture6 sectionsAussi en 8 autres langues
Dans Paramètres (13 articles)
Sur cette page

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.

Pas encore disponible

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.

  1. É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).

    L'onglet Clés API avec le bouton Nouvelle clé mis en évidence (Agrandir l'image)
  2. É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.

    La fenêtre Nouvelle clé API avec le nom, les droits de lecture et le bouton Créer mis en évidence (Agrandir l'image)
  3. É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.

    La fenêtre Clé API créée avec la clé et le bouton de copie mis en évidence (Agrandir l'image)
  4. É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.

    La liste des clés API avec la nouvelle clé et les boutons Renouveler et Révoquer mis en évidence (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'application
  • payment.received : un membre du personnel encaisse à la caisse
  • client.created : un membre du personnel crée un client dans l'application
  • client.updated : un membre du personnel modifie les données d'un client dans l'application
  • client.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
Uniquement ce qui se passe dans l'application

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

  1. Étape 1: Ouvrez l'onglet Webhooks

    Allez dans Paramètres > Avancé > API & Webhooks et cliquez sur l'onglet Webhooks.

    API & Webhooks avec l'onglet Webhooks mis en évidence (Agrandir l'image)
  2. Étape 2: Cliquez sur Nouveau webhook

    Cliquez sur Nouveau webhook.

    L'onglet Webhooks avec le bouton Nouveau webhook mis en évidence (Agrandir l'image)
  3. É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).

    La fenêtre Nouveau webhook avec l'URL, deux événements cochés et le bouton Enregistrer mis en évidence (Agrandir l'image)
  4. É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.

    La fenêtre Secret du webhook avec le secret et le bouton de copie mis en évidence (Agrandir l'image)
  5. É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.

    Le webhook dans la liste avec les boutons Nouveau secret, Test et Notifications mis en évidence (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.

Cet article vous a-t-il aidé ?

Votre réponse nous aide à améliorer les guides.

Toujours bloqué ?

Support: lun-ven réponse sous 24 à 48 heures (Pro : sous 24 heures) · week-end et jours fériés : sous 24 heures en cas d'urgence, sinon le jour ouvré suivant

Nous contacter