← Zurück zum Anfang Hotel-Integration
Embed SDK v1 · Preset Hotel · Handoff

Das Spa, innerhalb der Hotelreservierung.

Der Gast wählt seine Behandlung, ohne Ihr Buchungssystem zu verlassen, und das Spa wird zur Rechnung seines Aufenthalts hinzugefügt. Das Siana-Widget verlangt keine Zahlung: Es gibt Ihnen die Auswahl zurück, damit Sie sie mit Ihrer öffentlichen API erstellen können. Dieser Leitfaden ist alles, was Ihr technisches Team benötigt – kopieren, einfügen und Ihre Domain ersetzen.

Was es tut und was nicht

Diese Integration ist nicht wie die anderen vier. Die anderen verbinden das Buchungssystem mit Ihrer Website; diese verbindet es mit Ihrem Buchungssystem. Das Widget wechselt in den Nur-Lese-Modus: Es zeigt Verfügbarkeit und Preis an, lässt die Auswahl zu und sendet am Ende die Auswahl an Ihre Seite. Es gibt keinen Checkout, kein Zahlungsportal, und es wird nichts im Siana-Backend geschrieben.

Das Siana-Widgetzeigt Katalog und reale Verfügbarkeit an und gibt die Auswahl zurück. Es verlangt keine Zahlung und erstellt nichts.
Ihr Hotelbuchungssystemempfängt die Auswahl, speichert sie zusammen mit der Zimmerreservierung und verschiebt die Zahlung auf die Rechnung.
Ihr Backenderstellt die Spa-Reservierung, indem es die öffentliche API aufruft, wenn die Hotelreservierung bestätigt wird.
Der Preis des Payloads dient als Referenz. Er dient dazu, die Position in Ihrer Übersicht anzuzeigen. Die Quelle der Wahrheit ist die öffentliche API, die beim Erstellen den Preis neu berechnet und die Verfügbarkeit neu validiert. Verrechnen Sie niemals gegen den Betrag des Handoffs.

Der End-to-End-Ablauf

Zwei Phasen. Die erste findet vollständig im Browser des Gastes statt; die zweite, zwischen Ihrem Backend und der öffentlichen API, wann immer Sie sich entscheiden.

SchrittAkteurWas passiert
AuswahlBrowser · SianaDas Hotel öffnet das Widget (Drawer) und der Gast wählt Dienstleistung und Uhrzeit. Siana erstellt nichts.
HandoffWidget → HostBeim Klicken auf „Fertigstellen“ sendet das Widget cart:handoff mit dem Payload. Der Host verknüpft es über session_id mit seiner Reservierung.
start / createHost → öffentliche APILeitet slots/items an POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id) weiter. Die öffentliche API validiert Preis und Verfügbarkeit neu und erstellt die started (gehaltene) Reservierung.
confirmHost → öffentliche APIÄndert started → confirmed und gibt den locator aus. Die Zahlung erfolgt auf der Hotelrechnung (aufgeschobene Zahlung).

Wann welcher Aufruf? start beim Hinzufügen des Spas zum Hotel-Checkout (reserviert den Slot, gehalten; kann weggelassen werden, wenn kein Halten erforderlich ist). confirm, wenn die Hotelreservierung bezahlt oder bestätigt ist. Abbruch = kein API-Aufruf → nichts bleibt offen. Der Preis des Payloads dient nur als Referenz; maßgeblich ist das, was die öffentliche API neu berechnet.

Es gibt keine Blockierung des Zeitfensters zwischen Handoff und start. Der Slot wird beim Erstellen validiert, sodass er bei zu langer Wartezeit belegt sein kann. Die öffentliche API gibt Ihnen den Fehler zurück, und Ihr System entscheidet: erneut versuchen, eine andere Zeit anbieten oder benachrichtigen. Je früher Sie erstellen, desto geringer das Risiko.

Das Widget einbetten

Laden Sie embed.js des Buchungssystems und kennzeichnen Sie eine Schaltfläche mit data-siana-*-Attributen. Was den Hotelmodus aktiviert, ist data-siana-preset="hotel"; ohne dieses verhält sich das Widget wie ein normaler eingebetteter Inhalt und verlangt eine Zahlung.

<script src="https://DEIN-ENGINE/embed.js"></script>

<!-- Seitenleiste, eine bestimmte Dienstleistung -->
<button
  data-siana-open
  data-siana-view="widget"
  data-siana-service="UUID-DES-DIENSTES"
  data-siana-mode="drawer"
  data-siana-chrome="minimal"
  data-siana-preset="hotel"
  data-siana-purchase-mode="appointment"
  data-siana-session-id="ID-DEINER-RESERVIERUNG"
  data-siana-callback-url="https://api.deinhotel.com/spa/handoff">
  Spa zu meinem Aufenthalt hinzufügen
</button>
<!-- Zentriertes Modal -->
<button data-siana-open data-siana-mode="modal" data-siana-view="widget"
  data-siana-service="UUID-DEL-SERVICIO" data-siana-preset="hotel" data-siana-purchase-mode="appointment">…</button>

<!-- Eingebettet auf der Seite, vollständiger Katalog -->
<div data-siana-inline data-siana-view="full" data-siana-preset="hotel" data-siana-purchase-mode="appointment"></div>

Modus: drawer oder modal (mit data-siana-open), oder eingebettet (mit data-siana-inline). Ansicht: widget für einen einzelnen Service, full für den gesamten Katalog. chrome="minimal" blendet die Navigation der Engine aus.

session_id ist Ihr Buchungsidentifikator und wird unverändert im Payload zurückgegeben: damit können Sie das Spa der richtigen Zimmerbuchung zuordnen. Außerdem isoliert es den Warenkorb, sodass wenn der Gast das Widget schließt und wieder öffnet, seine Auswahl noch vorhanden ist. callback_url ist optional und wird unter Punkt 4 erklärt.

Den Handoff empfangen

Drei Wege, und Sie können sie kombinieren. A ist der empfohlene; C ist die Sicherung, wenn Sie kein JavaScript auf der Seite abhören.

// A) Mit dem SDK – empfohlen, auf der eigenen Seite
SianaBooking.on('cart:handoff', function (payload) {
  // payload.purchase_type, payload.slots | payload.items, payload.session_id …
  spaZurBuchungHinzufuegen(payload)
})

// Der Gast kann eine Position aus Ihrer Übersicht entfernen:
SianaBooking.on('cart:remove', function (data) { positionEntfernen(data.item_id) })

// B) Rohes postMessage, ohne SDK – überprüfen Sie IMMER die Herkunft
window.addEventListener('message', function (e) {
  if (e.origin !== 'https://IHRE-ENGINE') return
  if (e.data && e.data.type === 'siana:cart-handoff') { /* e.data */ }
})

// C) Serverseitig – data-siana-callback-url empfängt den GLEICHEN Payload per POST
//    (navigator.sendBeacon, Content-Type: text/plain). Nur https und nur
//    wenn Ihre Herkunft auf der Whitelist steht (siehe Punkt 8).

Das SDK gibt das postMessage siana:cart-handoff als cart:handoff-Ereignis erneut aus: Es sind die gleichen Daten, nur bequemer abzuhören. Jede Position kommt mit ihrer item_id, sodass Sie in Ihrer Zusammenfassung ein „Entfernen“ anbieten können und das Widget dies über cart:remove erfährt.

Die Spa-Buchung erstellen

Der Payload kommt bereits in genau der Form, die die öffentliche API akzeptiert, sodass nichts übersetzt werden muss: Sie fügen den buyer (die Identität stellen Sie bereit, nicht das Widget) und den Verweis auf die Hotelbuchung hinzu.

// Dies läuft NUR auf Ihrem Server: der Partnerschlüssel darf niemals
// den Browser erreichen. Wenn Ihre Hotelbuchung bestätigt wird:
await fetch(`https://IHRE-ENGINE/api/v1/public/.../${payload.purchase_type}-purchases`, {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey IHR-PARTNER-SCHLUESSEL',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    buyer: gastDesHotels,
    hotel_reservation_id: payload.session_id,
    ...(payload.slots ? { slots: payload.slots } : { items: payload.items })
    // der Preis wird NICHT gesendet: die öffentliche API berechnet den Preis serverseitig neu
  })
})

Der Endpunkt hängt von purchase_type ab: appointment-purchases, wenn Datum und Uhrzeit vorhanden sind, oder voucher-purchases, wenn es sich um einen Gutschein ohne Datum handelt. Der Payload sagt Ihnen bereits, welcher, und bringt entsprechend slots oder items mit.

Ein Element entfernen

Öffnen Sie die Engine erneut mit data-siana-item-id (Löschmodus): bestätigen Sie die Entfernung durch Aussenden von cart:remove und es wird geschlossen. Sie entfernen dieses Element aus Ihrer Buchung anhand seiner ID.

SianaBooking.open({ preset: 'hotel', sessionId: 'ID-HOTEL-RESERVIERUNG', itemId: ITEM_ID, mode: 'drawer' })

SianaBooking.on('cart:remove', function (data) {
  // data.session_id, data.item_id → aus Ihrer Buchung entfernen
})
Der „Entfernen“-Button befindet sich in Ihrer Zusammenfassung, nicht im Widget. Kennzeichnen Sie ihn mit der item_id, die im Handoff angekommen ist: Es ist dieselbe ID, die die Engine Ihnen in cart:remove bei Bestätigung der Entfernung zurückgibt.

Vertrag des Payloads

Beispiel eines Termins mit Datum (purchase_type: "appointment"). Im Gutscheinmodus kommt "voucher" mit items[] statt slots[].

{
  "v": 1,
  "type": "siana:cart-handoff",
  "session_id": "hotel-resv-DEMO-001",
  "center_uuid": "…",
  "purchase_type": "appointment",
  "slots": [
    {
      "item_id": "9c1f8f2a-4b77-4a5e-9f0e-2d31a6b8c554",
      "service_uuid": "3ea9a103-b45f-5442-bec3-592d1ba690cb",
      "service_name": "Spa-Rundgang",
      "fulfillment_on": "2026-06-01 10:00:00",
      "duration": 60,
      "pax": 2,
      "price_per_person": { "amount": 3000, "currency": "EUR" },
      "employee_db_id": null,
      "resource_db_id": null,
      "rate_db_id": 12
    }
  ],
  "total_reference": { "amount": 6000, "currency": "EUR" }
}
v
Version des Vertrags (heute 1). Wenn er sich eines Tages inkompatibel ändert, wird diese Nummer erhöht: Verwenden Sie dies, um es zu erkennen.
type
Typ der postMessage-Nachricht: siana:cart-handoff. Das SDK gibt sie als cart:handoff-Ereignis erneut aus.
session_id
Die data-siana-session-id, die Sie übergeben haben, wird unverändert zurückgegeben. Dies ist Ihre Buchungsreferenz: Verwenden Sie sie, um das Spa dem Zimmer zuzuordnen.
center_uuid
UUID des Spa-Zentrums, zu dem die Auswahl gehört.
purchase_type
appointment (Termin mit Datum → liefert slots) oder voucher (Gutschein ohne Datum → liefert items). Bestimmt den Endpunkt bei der Erstellung.
total_reference
Gesamtbetrag als Referenz, zur Anzeige. Die öffentliche API berechnet den Preis bei der Erstellung neu; buchen Sie nicht gegen diese Zahl ab.
slots / items
Die zu erstellenden Positionen, bereits in dem Format, das die öffentliche API akzeptiert. Sie werden unübersetzt weitergeleitet.
↳ item_id
Eindeutige ID dieser Position innerhalb des Warenkorbs. Dies ist die ID, die bei cart:remove ankommt und die Sie in data-siana-item-id übergeben, um sie zu entfernen.
↳ fulfillment_on / duration
(Termin) Datum und Uhrzeit JJJJ-MM-TT HH:MM:SS und Dauer in Minuten.
↳ price_per_person
Referenz-Einzelpreis: amount in Cent und Währung.
↳ rate_db_id
ID des gewählten Tarifs (0 = Basistarif).
↳ item_type
(Gutschein) Art der Position: service, service_package oder gift_card.
Der Handoff enthält keine persönlichen oder Zahlungsinformationen. Weder Name, noch E-Mail, noch Karte. Die Identität des Gastes geben Sie bei der Erstellung der Buchung an. Das ist Absicht: Es reduziert die Angreifbarkeit durch eine schlecht konfigurierte Quelle.

Sicherheit und Allowlist

Die Engine gibt den Handoff nur an explizit autorisierte Quellen aus. Dies wird in der Bereitstellung der Engine konfiguriert, nicht auf Ihrer Webseite:

NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.ihrhotel.com,https://www.ihrhotel.com
Dies ist das Erste, was bei einer neuen Integration geklärt werden muss. Im Produktivsystem ist das Verhalten standardmäßig verweigern: Wenn Ihre Domain nicht in dieser Liste steht, wird der Handoff einfach nicht gesendet — weder per postMessage noch per callback_url — und das Widget scheint beim Abschluss nichts zu tun. Dies ist kein Fehler in Ihrem Code. Geben Sie uns Ihre genauen Domains (mit Protokoll, ohne abschließenden Schrägstrich) bevor Sie mit dem Testen beginnen.
  • Mit konfigurierter Liste: Das postMessage wird nur an diese Ursprünge gesendet, und die callback_url wird nur akzeptiert, wenn sie https ist und ihr Ursprung in der Liste steht.
  • Ohne Liste, im Produktivsystem: Es wird nichts gesendet und eine Warnung im Log hinterlassen.
  • In der lokalen Entwicklung: Es gibt einen nachsichtigen Fallback, um die Demo aufbauen zu können, aber die callback_url über Beacon erfordert immer eine Allowlist.
  • Überprüfen Sie den Ursprung trotzdem, wenn Sie postMessage roh, ohne das SDK, abhören. Das ist eine Zeile und schützt Sie vor jedem anderen Iframe auf der Seite.
Die Allowlist steuert, wohin der Handoff geht, nicht, wer Ihren Endpunkt erreicht. Die callback_url ist eine öffentliche URL von Ihnen: Jeder kann einen POST an sie senden. Authentifizieren Sie jede Anfrage (geheimer Header, gemeinsame Signatur oder mTLS), überprüfen Sie, dass v eine von Ihnen unterstützte Version ist und dass center_uuid und purchase_type den Erwartungen entsprechen, und verknüpfen Sie die session_id mit einer bereits autorisierten Gastsitzung, bevor Sie etwas erstellen oder ändern. Das empfangene JSON beweist allein nicht, wer es sendet.
9 · Live-Demo

Probieren Sie es hier aus.

Dies simuliert die Webseite eines Hotels. Oben die Buchung des Aufenthalts; unten der Spa-Bereich. Klicken Sie auf „Verfügbarkeit suchen“, wählen Sie eine Behandlung und „Abschließen“: Das Widget fordert Sie nicht zur Zahlung auf – die Auswahl wird in die Buchung übernommen und der Gesamtbetrag neu berechnet. Das ist es, was Ihre Seite über cart:handoff empfängt.

Die Popup-Benachrichtigungen sind Teil der Demo, nicht des Produkts. Jedes Mal, wenn ein cart:handoff oder ein cart:remove eintrifft, sehen Sie ein alert() mit dem rohen JSON, damit Sie auf einen Blick überprüfen können, was die Engine Ihnen liefert. In Ihrer tatsächlichen Integration verarbeiten Sie diese Daten im Code und der Benutzer sieht nichts: Das alert() ist hier nur dazu da, die Daten während des Tests sichtbar zu machen.

Checkliste

Was erforderlich ist, um von der Demo zur Produktion überzugehen. Die ersten drei Punkte hängen von uns ab; die anderen von Ihrem technischen Team.

  • Ihre Domains in der Positivliste. Teilen Sie uns die genauen Ursprünge mit, von denen das Widget geöffnet wird. Ohne dies wird der Handoff (Punkt 8) nicht ausgelöst.
  • Der Ursprung Ihrer Engine. Wir geben Ihnen die Domain der Engine für das <script src> und zur Überprüfung des Ursprungs der postMessage.
  • Partner-Schlüssel für die öffentliche API. Ihr Backend benötigt ihn, um die Spa-Buchung zu erstellen (Punkt 5).
  • Entscheiden Sie, was Sie anzeigen: einen bestimmten Service (view="widget" + data-siana-service) oder den gesamten Katalog (view="full").
  • Wählen Sie den Modus: Seitenleiste, Modal oder eingebettet. Dies wird mit einem Attribut geändert, ohne den Rest zu berühren.
  • Übergeben Sie Ihre Buchungsreferenz in data-siana-session-id und speichern Sie sie zusammen mit der Auswahl.
  • Hören Sie auf cart:handoff und zeichnen Sie die Zeilen in Ihrer Zusammenfassung. Fügen Sie cart:remove hinzu, wenn Sie sie entfernen lassen.
  • Erstellen Sie die Spa-Buchung, wenn Sie die Hotelbuchung bestätigen, und verwalten Sie den Fall eines bereits belegten Slots (Punkt 2).
Fragen zu einem Punkt? Schreiben Sie uns mit Ihrem spezifischen Fall: Modus, Ansicht und zu welchem Zeitpunkt in Ihrem Ablauf Sie die Buchung erstellen möchten. Dies ist erforderlich, um die Details abzuschließen.