Mit der API und Webhooks verbindest du deinen Salon mit anderer Software, etwa deinem Buchhaltungsprogramm, deiner eigenen Website oder einem selbst gebauten Dashboard. Du musst kein Entwickler sein, um zu verstehen, was sie tun; diese Seite erklärt es und zeigt, wie du einen Schlüssel und einen Webhook erstellst.
Diese Funktion steht in der App noch auf Demnächst verfügbar: Du kannst derzeit keine API-Schlüssel oder Webhooks erstellen. Öffnest du Einstellungen > Erweitert > API & Webhooks, siehst du nur einen Hinweis, dass die Funktion kommt. Diese Seite beschreibt, wie es funktioniert, sobald die Funktion für deinen Salon aktiviert ist.
Was ist eine API?
Eine API ist eine Vereinbarung, über die zwei Programme miteinander sprechen. Wo du in der App eine Terminliste öffnest, kann ein anderes Programm dieselben Daten über die API abrufen, automatisch und ohne dein Zutun. Zum Beispiel: Dein Buchhaltungsprogramm ruft jede Nacht deine Termine ab, oder deine Website zeigt deine Behandlungen und Preise direkt aus Salonnare.
Der Zugriff läuft über einen API-Schlüssel: einen geheimen Code, der beweist, dass eine Anfrage von deinem Salon kommt. Behandle diesen Schlüssel wie ein Passwort.
Einen API-Schlüssel erstellen
Nur ein Administrator kann Schlüssel erstellen und löschen.
-
Schritt 1: Öffne API & Webhooks und klicke auf Neuer Schlüssel
Gehe zu Einstellungen > Erweitert > API & Webhooks. Klicke auf dem Tab API-Schlüssel (1) auf Neuer Schlüssel (2).
(Bild vergrößern) -
Schritt 2: Gib dem Schlüssel einen Namen und wähle, was er lesen darf
Gib einen gut erkennbaren Namen ein, zum Beispiel den Namen der Integration (1). Hake unter Was darf dieser Schlüssel lesen? nur die Daten an, die die Integration braucht (2): Termine, Kunden, Behandlungen oder Mitarbeiter. Soll der Schlüssel nach einem bestimmten Tag aufhören, wähle unter Läuft ab ein Datum. Klicke auf Erstellen (3).
Ein API-Schlüssel kann nur Daten abrufen, nie etwas ändern. Kunden sind personenbezogene Daten: Schalte das nur ein, wenn dein Integrationspartner sie wirklich braucht. Eine Website, die deine Behandlungen und Preise zeigt, kommt mit Behandlungen und Mitarbeiter aus.
(Bild vergrößern) -
Schritt 3: Kopiere den Schlüssel
Der vollständige Schlüssel (1) wird nur einmal angezeigt. Klicke auf die Kopierschaltfläche (2) und gib den Schlüssel an deinen Integrationspartner weiter oder speichere ihn in einem Passwortmanager. Schließe danach das Fenster.
(Bild vergrößern) -
Schritt 4: Dein Schlüssel in der Liste
In der Liste siehst du den Namen, den Anfang des Schlüssels, was er lesen darf, wann er zuletzt verwendet wurde und wann er abläuft (1). Mit Erneuern (2) bekommst du einen neuen Schlüssel mit demselben Namen und denselben Rechten; du wählst, wie lange der alte noch funktioniert (sofort nicht mehr, 24 Stunden oder 7 Tage), damit dein Integrationspartner Zeit zum Wechseln hat. Mit Widerrufen (3) hört ein Schlüssel sofort auf.
(Bild vergrößern)
Was ist ein Webhook?
Ein Webhook ist das Gegenstück zur API. Statt dass ein Programm immer wieder nachfragt, ob es etwas Neues gibt, schickt Salonnare selbst eine Nachricht an eine Adresse (URL), sobald etwas passiert. Salonnare kann diese sieben Ereignisse senden:
booking.created: ein neuer Termin kommt hinzu: in der App, über deine Online-Buchungsseite oder das Widget, über Reserve with Google oder sobald eine Buchungsanfrage bestätigt ist (auch jeder Termin, den eine Terminserie anlegt)booking.updated: ein Mitarbeiter ändert in der App einen Termin (auch eine Statusänderung auf abgeschlossen oder No-Show)booking.cancelled: ein Mitarbeiter storniert in der App einen Terminpayment.received: ein Mitarbeiter rechnet an der Kasse abclient.created: ein Mitarbeiter legt in der App einen Kunden anclient.updated: ein Mitarbeiter ändert in der App Kundendatenclient.deleted: ein Mitarbeiter löscht einen Kunden in der App. Die Meldung enthält nur die Kundennummer; frühere Meldungen zu diesem Kunden bewahrt Salonnare danach ohne Namen und Kontaktdaten auf
Jedes Ereignis stammt aus einer Aktion eines Mitarbeiters in der App. Eine Online-Buchung über deine Buchungsseite oder Google, ein Kunde, der selbst storniert, ein umgewandelter Wartelisteneintrag, eine wiederkehrende Serie, eine Kur und ein Kunde, der sich selbst auf der Buchungsseite anlegt, lösen keine Benachrichtigung aus. Dein Integrationspartner fängt diese ab, indem er regelmäßig die Terminliste abruft.
Einen Webhook einrichten
-
Schritt 1: Öffne den Tab Webhooks
Gehe zu Einstellungen > Erweitert > API & Webhooks und klicke auf den Tab Webhooks.
(Bild vergrößern) -
Schritt 2: Klicke auf Neuer Webhook
Klicke auf Neuer Webhook.
(Bild vergrößern) -
Schritt 3: Gib die Adresse ein und wähle die Ereignisse
Gib bei URL die Adresse ein, die du von deinem Integrationspartner bekommen hast; sie beginnt mit
https://(1). Hake die Ereignisse an, auf die die Verbindung reagieren soll (2 und 3). Aktiv ist standardmäßig eingeschaltet. Klicke auf Speichern (4).
(Bild vergrößern) -
Schritt 4: Kopiere das Geheimnis
Salonnare signiert jede Nachricht mit einem Geheimnis, damit der Empfänger prüfen kann, dass sie wirklich von deinem Salon kommt. Das Geheimnis (1) wird nur einmal angezeigt: Kopiere es (2) und gib es an deinen Integrationspartner weiter.
(Bild vergrößern) -
Schritt 5: Testen und die Meldungen ansehen
Der Webhook steht jetzt in der Liste (1). Mit Test (3) schickt Salonnare sofort eine Testnachricht, und du siehst, ob sie angekommen ist. Unter Meldungen (4) siehst du jede Meldung mit ihrem Stand (angekommen, wird erneut versucht oder fehlgeschlagen) und den Versuchen; eine fehlgeschlagene Meldung sendest du dort mit Erneut senden noch einmal. Hast du das Geheimnis verloren, klicke auf Neues Geheimnis (2); das alte funktioniert danach nicht mehr, deshalb muss auch die empfangende Seite aktualisiert werden.
(Bild vergrößern)
Was ist, wenn ...
... der Test nicht ankommt? Dann meldet Salonnare, dass die Adresse nicht geantwortet hat oder welchen Fehlercode der Empfänger zurückgegeben hat. Prüfe die Adresse und bitte deinen Integrationspartner nachzusehen, warum seine Seite die Nachricht ablehnt.
... eine Benachrichtigung einmal nicht ankommt? Salonnare versucht es dann erneut: nach etwa 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 8 Stunden und 24 Stunden. Jeder Versuch trägt dieselbe Benachrichtigungsnummer, sodass der Empfänger eine doppelt ankommende Benachrichtigung erkennt. Gelingt kein Versuch und kam in dieser Zeit auch nichts anderes an, schaltet Salonnare den Webhook aus und benachrichtigt dich. Du schaltest ihn wieder ein, indem du ihn bearbeitest und Aktiv einschaltest. Fehlgeschlagene Meldungen sendest du unter Meldungen mit Erneut senden noch einmal.
... die Adresse abgelehnt wird? Ein Webhook muss auf eine öffentliche Adresse zeigen. Adressen in einem internen oder privaten Netzwerk, localhost und Adressen, die nicht mit https:// beginnen, lehnt Salonnare ab, mit einer Meldung, die sagt, was falsch ist.
... du vermutest, dass ein Schlüssel öffentlich geworden ist? Lösche ihn sofort mit dem Papierkorb und erstelle einen neuen.
Sicher arbeiten
- Teile API-Schlüssel und Webhook-Geheimnisse nie öffentlich (nicht in einer normalen E-Mail, auf einem Screenshot oder in Code, der online steht).
- Gib einer Verbindung nur die Rechte, die sie braucht.
- Lösche Schlüssel und Webhooks, die du nicht mehr nutzt.
Bist du Entwickler und suchst die technischen Details (Authentifizierung, Endpunkte, Felder, Signaturen)? Sieh dir die API Reference an. Diese Seite ist auf Englisch, weil sie für Entwickler geschrieben ist.