Beiträge in diesem Abschnitt

Die Smoobu-API nutzen: API-Schlüssel erstellen, Webhooks einrichten und Anfragen signieren

  • Aktualisiert

Über die Smoobu-API liest und schreibt ein Tool oder dein eigener Code deine Buchungsdaten, und Webhooks melden deinem System sofort, sobald sich etwas ändert. Verwaltet wird das alles unter Fortgeschrittene Einstellungen > API-Schlüssel. Greif dazu, wenn ein Tool Zugriff auf deine Buchungen braucht oder du deine eigene Integration baust. Das ist nur etwas für erfahrene Nutzer: Der Kundensupport hilft nur bei Integrationsproblemen mit Marktplatz-Partnern, bei eigenen Entwicklungen kann unser Support-Team nicht weiterhelfen.

Bevor du startest

Das brauchst du, bevor du die API nutzen kannst:

  • Ein kostenpflichtiges Smoobu-Konto. In der kostenlosen Testphase lassen sich keine Schlüssel erzeugen. Wenn du in der Testphase bist und API-Zugriff brauchst, wende dich an das Smoobu-Team, um ihn freischalten zu lassen.
  • Das Bewusstsein, dass jeder Schlüssel vollen Zugriff auf dein ganzes Konto gibt. Behandle einen Schlüssel wie ein Passwort.

Einen API-Schlüssel erstellen

  1. Öffne in Smoobu Fortgeschrittene Einstellungen und dann API-Schlüssel.
  2. Klicke auf Generiere API Key.
  3. Kopiere den Schlüssel und speichere ihn sofort an einem sicheren Ort, zum Beispiel in einem Passwortmanager. Smoobu zeigt den Schlüssel nur ein einziges Mal an. Verlässt du die Seite, ohne ihn zu sichern, musst du einen neuen erzeugen.
  4. Füge den Schlüssel in das Tool oder den Code ein, der Zugriff braucht.

Jeder Schlüssel gibt vollen Zugriff auf dein ganzes Konto, und auf einen Teil deiner Daten lässt er sich derzeit nicht begrenzen. Nutzt du mehrere Integrationen, gib jeder einen eigenen Schlüssel, dann kannst du einen widerrufen, ohne die anderen lahmzulegen. Und willst du einen Schlüssel stilllegen, lösche ihn auf dieser Seite: Das Tool, das ihn nutzt, verliert sofort den Zugriff.

Schütze deinen Schlüssel

Ein Schlüssel ist ein Passwort zu deinem ganzen Konto. Behandle ihn also wie ein Passwort:

  • Schreibe einen Schlüssel nie direkt in deinen Code. Das gilt für API-Schlüssel, Passwörter und Tokens gleichermaßen: Wer den Code sehen kann, sieht auch den Schlüssel.
  • Speichere Zugangsdaten stattdessen in Umgebungsvariablen, zum Beispiel in einer .env-Datei, die dein Code zur Laufzeit ausliest.
  • Halte die .env-Datei aus der Versionsverwaltung heraus. Trage .env und jede andere Konfigurationsdatei mit geheimen Werten in deine .gitignore ein, damit sie nie zu GitHub hochgeladen werden.
  • Mach deine Repositorys privat. Wenn dein Integrationscode auf GitHub liegt, stelle die Sichtbarkeit des Repositorys sofort auf Private, besonders wenn der Code deine eigene, geschützte Arbeit ist.

Gelangt ein Schlüssel doch nach außen, lösche ihn auf der Seite API-Schlüssel und erzeuge einen neuen; der alte funktioniert dann sofort nicht mehr.

Einen Webhook einrichten

Ein Webhook meldet deinem eigenen System, wenn sich in Smoobu etwas ändert, sodass dein System nicht ständig nachfragen muss.

  1. Suche auf der Seite API-Schlüssel das Feld Webhook-URLs.
  2. Gib die Adresse auf deinem Server ein, die die Updates empfangen soll.
  3. Klicke auf Speichern. Du kannst mehr als einen Webhook hinzufügen.

Smoobu sendet einen Webhook für diese Ereignisse:

  • eine neue Buchung
  • eine aktualisierte Buchung
  • eine stornierte Buchung
  • ein abgeschickter Online-Check-in
  • ein erstelltes Preiselement
  • ein aktualisiertes Preiselement
  • ein gelöschtes Preiselement
  • eine neue Nachricht

Diese Liste ist vollständig. Für Bewertungen gibt es keinen Webhook, und es gibt keine versteckten oder undokumentierten Ereignisse.

Welche Daten Smoobu genau mit jedem Ereignis sendet, steht in der Entwicklerdokumentation (docs.smoobu.com): Klicke auf der Seite API-Schlüssel auf Hier geht es zur Dokumentation der API. Dieselbe Dokumentation enthält die vollständige Endpunkt-Referenz und Code-Beispiele.

Stattdessen ein Marktplatz-Tool anbinden

Ist das gewünschte Tool schon ein Smoobu-Marktplatz-Partner, etwa ein Preistool oder ein Check-in-Tool, gibst du gar keinen Schlüssel weiter, sondern folgst einfach den Anleitungen im Smoobu-Marktplatz. Marktplatz-Partner kannst du jederzeit trennen; das kappt ihren Zugriff sofort, beendet dein Abonnement für den Dienst aber nicht unbedingt. Nimm diesen Weg, wo es ihn gibt, und erzeuge einen eigenen Schlüssel nur für ein Tool oder Skript, das kein gelisteter Partner ist.

Deine Anfragen mit HMAC signieren

Smoobu stellt den direkten API-Zugriff auf signierte Anfragen (HMAC) um, sodass jeder Aufruf belegt, dass er echt und unverändert ist. Hast du deine eigene Integration gebaut, ergänze die Signierung vor dem 25. September 2026; danach werden unsignierte Anfragen abgelehnt. In der Übergangszeit funktionieren beide, signiert und unsigniert, du kannst also umstellen und testen, ohne dein laufendes Setup zu unterbrechen.

Wer etwas tun muss:

  • Marktplatz-Partner (Preistools, Check-in-Tools und Ähnliches): nichts zu tun, der Partner kümmert sich darum.
  • Portalverbindungen (Airbnb, Booking.com und andere Portale): nicht betroffen.
  • Dein eigenes Skript oder deine eigene Integration, die du selbst kontrollierst: Ergänze die Signierung mit den Schritten unten.
  • Ein Tool, das du nicht kontrollierst, in das du aber deinen Schlüssel eingefügt hast: Lösche deinen Schlüssel nicht und migriere ihn nicht selbst, das legt das Tool lahm. Wende dich an das Smoobu-Team, nenne das Tool, das du nutzt, und Smoobu richtet den Partner ein. Dein Schlüssel funktioniert während der Umstellung weiter.

So richtest du die Signierung ein:

  1. Gehe zu Fortgeschrittene Einstellungen und dann API-Schlüssel.
  2. Klicke auf Neu erstellen, gib dem Schlüssel ein aussagekräftiges Label und klicke auf Absenden.
  3. Kopiere das Secret sofort und speichere es sicher. Smoobu zeigt es nur ein einziges Mal an. Wenn du es verlierst, nutze Regenerate Secret auf dieser Seite; das erneute Erzeugen macht das alte Secret aber sofort ungültig, aktualisiere also zuerst deine Integration.
  4. Passe deine Integration so an, dass sie jede Anfrage signiert. Zusätzlich zu deinem Schlüssel sendet jede Anfrage vier weitere Header:
    1. X-API-Key (dein Schlüssel),
    2. X-Timestamp (die aktuelle Zeit im UTC-Format ISO 8601 (Beispiel: 2026-04-01T12:00:00Z)),
    3. X-Nonce (ein eindeutiger Wert, den du nie wiederverwendest; nutze UUID v4),
    4. und X-Signature (die HMAC-SHA256-Signatur). Wie du die Signatur bildest und wie jeder Header genau aufgebaut ist, steht in der Entwicklerdokumentation: Die vollständige technische Anleitung mit Code-Beispielen findest du hier: docs.smoobu.com/#hmac-authentication

Häufige Probleme

Generiere API Key fehlt oder tut nichts

Auf Testkonten ist das Erzeugen von Schlüsseln abgeschaltet. Bist du in der Testphase und brauchst API-Zugriff, wende dich an das Smoobu-Team, das ihn einschalten kann.

Meine signierten Anfragen scheitern mit 401 Unauthorized

Meist liegt es an der Signatur oder am Timestamp. Weitere häufige Ursachen:

  • Zeitabweichung: Deine Systemzeit weicht um mehr als 5 Minuten ab. Stelle sicher, dass dein Server NTP nutzt.
  • Wiederverwendete Nonce: Jede Anfrage muss eine eindeutige X-Nonce haben (nutze UUID v4 oder zufällige Bytes).
  • Falscher Body-Hash: Bei GET- und DELETE-Anfragen hashst du einen leeren String, nicht null oder undefined.
  • Reihenfolge der Query-Parameter: Sortiere die Parameter alphabetisch, wenn du den kanonischen String bildest.
  • Abweichende Kodierung: Signiere den rohen JSON-Body genau so, wie er gesendet wird, mit demselben Whitespace und derselben Kodierung.

In der Übergangszeit kannst du vorübergehend auf unsignierte Anfragen zurückgreifen, während du den Fehler behebst.

Verwandte Artikel

Kommst du nicht weiter?

Wenn diese Schritte das Problem nicht gelöst haben, kontaktiere das Smoobu-Team: Öffne das Menü Hilfe, um ein Ticket zu eröffnen oder einen Telefontermin zu buchen, oder nutze die Chat-Blase unten rechts. Für die schnellste Antwort gib bitte an:

  • Deine Smoobu User ID (im Profil-Icon-Menü oben rechts).
  • Den Namen oder die ID der Unterkunft, wenn es um eine bestimmte Unterkunft geht.
  • Die Buchungs-ID, wenn es um eine bestimmte Buchung geht (Buchungen, dann Mehr anzeigen).
  • Den Namen des Portals, wenn es um Portal-Sync geht (Booking.com, Airbnb, Vrbo und so weiter).
  • Eine kurze Schritt-für-Schritt-Beschreibung: was du getan hast, was du erwartet hast und was passiert ist.
  • Screenshots oder eine kurze Bildschirmaufnahme des Problems.

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.