Einstellungen

API & Webhooks

Was die Salonnare-API und Webhooks sind, und Schritt für Schritt einen API-Schlüssel erstellen und einen Webhook einrichten.

6 Minuten Lesezeit6 AbschnitteAuch in 8 weiteren Sprachen
In Einstellungen (13 Artikel)
Auf dieser Seite

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.

Noch nicht verfügbar

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.

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

    Der Tab API-Schlüssel mit der Schaltfläche Neuer Schlüssel markiert (Bild vergrößern)
  2. 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.

    Das Fenster Neuer API-Schlüssel mit dem Namen, den Leserechten und der Schaltfläche Erstellen markiert (Bild vergrößern)
  3. 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.

    Das Fenster API-Schlüssel erstellt mit dem Schlüssel und der Kopierschaltfläche markiert (Bild vergrößern)
  4. 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.

    Die Liste der API-Schlüssel mit dem neuen Schlüssel und den Schaltflächen Erneuern und Widerrufen markiert (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 Termin
  • payment.received: ein Mitarbeiter rechnet an der Kasse ab
  • client.created: ein Mitarbeiter legt in der App einen Kunden an
  • client.updated: ein Mitarbeiter ändert in der App Kundendaten
  • client.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
Nur, was in der App passiert

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

  1. Schritt 1: Öffne den Tab Webhooks

    Gehe zu Einstellungen > Erweitert > API & Webhooks und klicke auf den Tab Webhooks.

    API & Webhooks mit dem Tab Webhooks markiert (Bild vergrößern)
  2. Schritt 2: Klicke auf Neuer Webhook

    Klicke auf Neuer Webhook.

    Der Tab Webhooks mit der Schaltfläche Neuer Webhook markiert (Bild vergrößern)
  3. 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).

    Das Fenster Neuer Webhook mit der URL, zwei angehakten Ereignissen und der Schaltfläche Speichern markiert (Bild vergrößern)
  4. 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.

    Das Fenster Webhook-Geheimnis mit dem Geheimnis und der Kopierschaltfläche markiert (Bild vergrößern)
  5. 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.

    Der Webhook in der Liste mit den Schaltflächen Neues Geheimnis, Test und Meldungen markiert (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.

War das hilfreich?

Deine Antwort hilft uns, die Anleitungen zu verbessern.

Kommst du nicht weiter?

Support: Mo-Fr Antwort innerhalb von 24 bis 48 Stunden (Pro: innerhalb von 24 Stunden) · Wochenende und Feiertage: im Notfall innerhalb von 24 Stunden, sonst am nächsten Werktag

Kontakt aufnehmen