The spa, within the hotel booking.
The guest chooses their treatment without leaving your booking engine, and the spa is added to their stay's bill. The Siana widget does not charge: it returns the selection for you to create it with your public API. This guide is all your technical team needs — copy, paste, and replace your domain.
Table of contents
What it does and what it doesn't
This integration is not like the other four. The others connect the engine to your website; this one connects it to your booking engine. The widget enters read-only mode: it shows availability and price, allows selection, and upon completion, emits the selection to your page. There is no checkout, no payment gateway, nothing is written to Siana's backend.
The end-to-end flow
Two phases. The first occurs entirely in the guest's browser; the second, between your backend and the public API, when you decide.
| Step | Actor | What happens |
|---|---|---|
| Selection | browser · Siana | The hotel opens the widget (drawer) and the guest chooses service and time. Siana creates nothing. |
| Handoff | widget → host | When pressing "Finish", the widget emits cart:handoff with the payload. The host associates it with their booking via session_id. |
| start / create | host → public API | Forwards slots/items to POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id). The public API re-validates price and availability, and creates the started (held) booking. |
| confirm | host → public API | Changes started → confirmed and issues the locator. Payment is included in the hotel bill (deferred payment). |
When is each call made? start when adding the spa to the hotel
checkout (reserves the slot, held; optional if you don't need a hold). confirm when the
hotel booking is paid or confirmed. Abandonment = no API call → nothing
pending. The payload price is only for reference; send what the public API recalculates.
start. The slot
is validated upon creation, so if a lot of time passes, it may have been taken.
The public API will return an error and your engine decides: retry, offer
another time, or notify. The sooner you create, the less risk.
Set up the widget
Load the engine's embed.js and mark a button with data-siana-*
attributes. What activates hotel mode is data-siana-preset="hotel";
without it, the widget behaves like a normal embedded one and does charge.
<script src="https://YOUR-ENGINE/embed.js"></script> <!-- Side panel, a specific service --> <button data-siana-open data-siana-view="widget" data-siana-service="SERVICE-UUID" data-siana-mode="drawer" data-siana-chrome="minimal" data-siana-preset="hotel" data-siana-purchase-mode="appointment" data-siana-session-id="YOUR-BOOKING-ID" data-siana-callback-url="https://api.yourhotel.com/spa/handoff"> Add spa to my stay </button> <!-- Centered 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> <!-- Embedded in the page, full catalog --> <div data-siana-inline data-siana-view="full" data-siana-preset="hotel" data-siana-purchase-mode="appointment"></div>
Mode: drawer or modal (with
data-siana-open), or embedded (with
data-siana-inline). View:
widget for a single service, full for the
entire catalog. chrome="minimal" hides the engine's navigation.
session_id is your booking identifier, and
it returns intact in the payload: it's what allows you to associate the spa with the
correct room. It also isolates the cart, so if the guest closes
and reopens the widget, their selection is still there.
callback_url is optional and explained in point 4.
Receive the handoff
Three ways, and you can combine them. A is recommended; C is the fallback if you don't have JavaScript listening on the page.
// A) With the SDK — recommended, on the page itself SianaBooking.on('cart:handoff', function (payload) { // payload.purchase_type, payload.slots | payload.items, payload.session_id … addSpaToBooking(payload) }) // The guest can remove an item from your summary: SianaBooking.on('cart:remove', function (data) { removeItem(data.item_id) }) // B) Raw postMessage, without SDK — ALWAYS verify the origin window.addEventListener('message', function (e) { if (e.origin !== 'https://YOUR-ENGINE') return if (e.data && e.data.type === 'siana:cart-handoff') { /* e.data */ } }) // C) Server-side — data-siana-callback-url receives the SAME payload via POST // (navigator.sendBeacon, Content-Type: text/plain). Only https and only // if your origin is in the allowlist (see point 8).
The SDK re-emits the postMessage siana:cart-handoff
as a cart:handoff event: it's the same data, just easier to
listen for. Each item arrives with its item_id, so you can
offer a "remove" in your summary and the widget will be notified via
cart:remove.
Create the spa booking
The payload already comes in the exact format accepted by the public API, so
there's no need to translate anything: you add the buyer (you provide the identity,
not the widget) and the reference to the hotel booking.
// This runs ONLY on your server: the partner key must never reach // the browser. When your hotel booking is confirmed: await fetch(`https://YOUR-ENGINE/api/v1/public/.../${payload.purchase_type}-purchases`, { method: 'POST', headers: { 'Authorization': 'ApiKey YOUR-PARTNER-KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ buyer: hotelGuest, hotel_reservation_id: payload.session_id, ...(payload.slots ? { slots: payload.slots } : { items: payload.items }) // the price is NOT sent: the public API re-prices server-side }) })
The endpoint depends on purchase_type:
appointment-purchases when there is a date and time, or
voucher-purchases when it's a voucher without a date. The payload already
tells you which one, and brings slots or items accordingly.
Remove an item
Re-open the engine with data-siana-item-id (delete mode): it confirms the cancellation
by emitting cart:remove and closes. You remove that item from your booking by its id.
SianaBooking.open({ preset: 'hotel', sessionId: 'HOTEL-BOOKING-ID', itemId: ITEM_ID, mode: 'drawer' })
SianaBooking.on('cart:remove', function (data) {
// data.session_id, data.item_id → remove it from your booking
})
item_id that arrived in the handoff: it's the same id the engine returns to you in
cart:remove upon confirming the removal.
Payload contract
Example of an appointment with date (purchase_type: "appointment").
In voucher mode, "voucher" arrives with items[] instead
of 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 Circuit",
"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
- Contract version (today
1). If it changes incompatibly someday, this number increases: use it to detect such changes. - type
- Type of the
postMessagemessage:siana:cart-handoff. The SDK re-emits it as acart:handoffevent. - session_id
- The
data-siana-session-idyou passed, returned intact. It is your booking reference: use it to associate the spa with the room. - center_uuid
- UUID of the spa center to which the selection belongs.
- purchase_type
appointment(dated appointment →slotsarrives) orvoucher(undated voucher →itemsarrives). Determines the endpoint when creating.- total_reference
- Total reference amount, for display. The public API re-prices upon creation; do not charge against this number.
- slots / items
- The lines to create, already in the format accepted by the public API. They are re-sent untranslated.
- ↳ item_id
- unique id of that line within the cart. This is the one that arrives in
cart:removeand the one you pass indata-siana-item-idto remove it. - ↳ fulfillment_on / duration
- (appointment) date and time
YYYY-MM-DD HH:MM:SSand duration in minutes. - ↳ price_per_person
- unit reference price:
amountin cents and currency. - ↳ rate_db_id
- id of the chosen rate (
0= base rate). - ↳ item_type
- (voucher) line type:
service,service_packageorgift_card.
Security and allowlist
The engine only emits the handoff to explicitly authorized origins. This is configured in the engine's deployment, not on your website:
NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.tuhotel.com,https://www.tuhotel.com
postMessage nor via
callback_url — and the widget will appear to do nothing upon
completion. It is not a failure in your code. Pass us your exact domains
(with protocol, no trailing slash) before you start testing.
- With the list configured: the
postMessageis only published to those origins, and thecallback_urlis only accepted if it ishttpsand its origin is on the list. - Without a list, in production: nothing is emitted and a warning appears in the log.
- In local development: there is a permissive fallback to allow setting up the demo, but the
callback_urlvia beacon always requires an allowlist. - Verify the origin anyway if you listen for raw
postMessage, without the SDK. It's one line and protects you from any other iframe on the page.
callback_url is a public URL
of yours: anyone can POST to it. Authenticate each request
(secret header, shared signature, or mTLS), check that v
is a version you support and that center_uuid and
purchase_type are what you expect, and link the
session_id to a guest session you have already authorized
before creating or modifying anything. The received JSON does not by itself
prove who is sending it.
Try it right here.
This simulates a hotel's website. Above, the stay reservation; below,
its spa section. Click "Check availability", choose a treatment and
"Finalize": the widget will not ask you to pay — the selection is added to the reservation
and the total is recalculated. That's what your page receives via cart:handoff.
cart:handoff or a cart:remove arrives, you will see an
alert() with the raw JSON, so you can check at a glance what the engine is
delivering to you. In your real integration, that data is processed in code and the user
sees nothing: the alert() is here only to make the data visible while
testing.
Payload received from the spa engine
cart:handoff event as it arrives on your page.
Checklist
What is needed to go from demo to production. The first three points depend on us; the rest, on your technical team.
- Your domains in the allowlist. Provide us with the exact origins from which the widget will open. Without this, the handoff is not emitted (point 8).
- Your engine's origin. We give you the engine's domain for the
<script src>and to verify thepostMessageorigin. - Partner key for the public API. Your backend needs it to create the spa booking (point 5).
- Decide what to show: a specific service (
view="widget"+data-siana-service) or the entire catalog (view="full"). - Choose the mode: side panel, modal, or embedded. It is changed with an attribute, without touching the rest.
- Pass your booking reference in
data-siana-session-idand save it along with the selection. - Listen for
cart:handoffand render the lines in your summary. Addcart:removeif you allow them to be removed. - Create the spa booking when you confirm the hotel booking, and manage the case of an already occupied slot (point 2).