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.
Inhaltsverzeichnis
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.
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.
| Schritt | Akteur | Was passiert |
|---|---|---|
| Auswahl | Browser · Siana | Das Hotel öffnet das Widget (Drawer) und der Gast wählt Dienstleistung und Uhrzeit. Siana erstellt nichts. |
| Handoff | Widget → Host | Beim Klicken auf „Fertigstellen“ sendet das Widget cart:handoff mit dem Payload. Der Host verknüpft es über session_id mit seiner Reservierung. |
| start / create | Host → öffentliche API | Leitet 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. |
| confirm | Host → ö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.
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
})
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 alscart: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 → liefertslots) odervoucher(Gutschein ohne Datum → liefertitems). 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:removeankommt und die Sie indata-siana-item-idübergeben, um sie zu entfernen. - ↳ fulfillment_on / duration
- (Termin) Datum und Uhrzeit
JJJJ-MM-TT HH:MM:SSund Dauer in Minuten. - ↳ price_per_person
- Referenz-Einzelpreis:
amountin Cent und Währung. - ↳ rate_db_id
- ID des gewählten Tarifs (
0= Basistarif). - ↳ item_type
- (Gutschein) Art der Position:
service,service_packageodergift_card.
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
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
postMessagewird nur an diese Ursprünge gesendet, und diecallback_urlwird nur akzeptiert, wenn siehttpsist 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
postMessageroh, ohne das SDK, abhören. Das ist eine Zeile und schützt Sie vor jedem anderen Iframe auf der Seite.
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.
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.
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.
Vom Spa-Engine empfangener Payload
Ereignis cart:handoff, so wie es auf Ihrer Seite ankommt.
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 derpostMessage. - 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-idund speichern Sie sie zusammen mit der Auswahl. - Hören Sie auf
cart:handoffund zeichnen Sie die Zeilen in Ihrer Zusammenfassung. Fügen Siecart:removehinzu, 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).