La spa, all'interno della prenotazione dell'hotel.
L'ospite sceglie il suo trattamento senza uscire dal tuo motore di prenotazione, e la spa si aggiunge alla fattura del suo soggiorno. Il widget di Siana non addebita: ti restituisce la selezione affinché tu la crei con la tua public API. Questa guida è tutto ciò di cui il tuo team tecnico ha bisogno — copia, incolla e sostituisci il tuo dominio.
Indice
Cosa fa e cosa non fa
Questa integrazione non è come le altre quattro. Le altre connettono il motore con il tuo sito web; questa lo connette con il tuo motore di prenotazione. Il widget entra in modalità sola lettura: mostra disponibilità e prezzo, permette di scegliere e, al termine, emette la selezione verso la tua pagina. Non c'è checkout, non c'è gateway di pagamento, nulla viene scritto nel backend di Siana.
Il flusso end-to-end
Due fasi. La prima avviene interamente nel browser dell'ospite; la seconda, tra il tuo backend e la public API, quando decidi tu.
| Passo | Attore | Cosa succede |
|---|---|---|
| Selezione | browser · Siana | L'hotel apre il widget (drawer) e l'ospite sceglie servizio e orario. Siana non crea nulla. |
| Handoff | widget → host | Cliccando su «Finalizza» il widget emette cart:handoff con il payload. L'host lo associa alla sua prenotazione tramite session_id. |
| start / create | host → public API | Reindirizza slots/items a POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id). La public API rivaluta prezzo e disponibilità, e crea la prenotazione started (in sospeso). |
| confirm | host → public API | Passa started → confirmed ed emette il locator. L'addebito va nella fattura dell'hotel (pagamento posticipato). |
Quando ogni chiamata? start quando si aggiunge la spa al checkout dell'
hotel (prenota lo slot, in sospeso; omissibile se non hai bisogno di trattenere). confirm quando la
prenotazione dell'hotel è pagata o confermata. Abbandono = non si chiama l'API → non rimane nulla
in sospeso. Il prezzo del payload è solo di riferimento; vale ciò che ricalcola la public API.
start. Lo slot
viene convalidato al momento della creazione, quindi se passa molto tempo potrebbe essere occupato.
La public API ti restituirà l'errore e il tuo motore deciderà: riprovare, offrire
un'altra ora o avvisare. Prima crei, meno rischio.
Montare il widget
Carica embed.js del motore e segna un pulsante con gli attributi
data-siana-*. Ciò che attiva la modalità hotel è
data-siana-preset="hotel"; senza di esso, il widget si comporta come
un embed normale e addebita.
<script src="https://TU-MOTORE/embed.js"></script> <!-- Pannello laterale, un servizio specifico --> <button data-siana-open data-siana-view="widget" data-siana-service="UUID-DEL-SERVICIO" data-siana-mode="drawer" data-siana-chrome="minimal" data-siana-preset="hotel" data-siana-purchase-mode="appointment" data-siana-session-id="ID-DE-TU-RESERVA" data-siana-callback-url="https://api.tuhotel.com/spa/handoff"> Aggiungi spa al mio soggiorno </button> <!-- Modale centrato --> <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> <!-- Integrato nella pagina, catalogo completo --> <div data-siana-inline data-siana-view="full" data-siana-preset="hotel" data-siana-purchase-mode="appointment"></div>
Modalità: drawer o modal (con
data-siana-open), o integrato (con
data-siana-inline). Vista:
widget per un singolo servizio, full per il
catalogo intero. chrome="minimal" nasconde la navigazione del
motore.
session_id è il tuo identificativo di prenotazione, e
ritorna intatto nel payload: è ciò che ti permette di associare la spa alla
camera corretta. Inoltre isola il carrello, così se l'ospite chiude
e riapre il widget, la sua selezione è ancora lì.
callback_url è opzionale e viene spiegato al punto 4.
Ricevere l'handoff
Tre vie, e puoi combinarle. La A è la raccomandata; la C è il backup se non hai JavaScript in ascolto sulla pagina.
// A) Con l'SDK — raccomandato, nella pagina stessa SianaBooking.on('cart:handoff', function (payload) { // payload.purchase_type, payload.slots | payload.items, payload.session_id … aggiungiSpaAllaPrenotazione(payload) }) // L'ospite può rimuovere una riga dal tuo riepilogo: SianaBooking.on('cart:remove', function (data) { rimuoviRiga(data.item_id) }) // B) postMessage grezzo, senza SDK — verifica SEMPRE l'origine window.addEventListener('message', function (e) { if (e.origin !== 'https://TU-MOTOR') return if (e.data && e.data.type === 'siana:cart-handoff') { /* e.data */ } }) // C) Server-side — data-siana-callback-url riceve lo STESSO payload via POST // (navigator.sendBeacon, Content-Type: text/plain). Solo https e solo // se la tua origine è nella allowlist (vedi punto 8).
L'SDK riemette il postMessage siana:cart-handoff
come evento cart:handoff: è lo stesso dato, più comodo da
ascoltare. Ogni riga arriva con il suo item_id, così puoi
offrire un «rimuovi» nel tuo riepilogo e il widget lo sa tramite
cart:remove.
Creare la prenotazione spa
Il payload arriva già con la forma esatta che accetta la public API, quindi
non c'è bisogno di tradurre nulla: gli aggiungi il buyer (l'identità la
fornisci tu, non il widget) e il riferimento alla prenotazione dell'hotel.
// Questo viene eseguito SOLO sul tuo server: la chiave partner non deve mai arrivare // al browser. Quando la tua prenotazione hotel è confermata: await fetch(`https://TU-MOTOR/api/v1/public/.../${payload.purchase_type}-purchases`, { method: 'POST', headers: { 'Authorization': 'ApiKey LA-TUA-CHIAVE-PARTNER', 'Content-Type': 'application/json' }, body: JSON.stringify({ buyer: ospiteDellHotel, hotel_reservation_id: payload.session_id, ...(payload.slots ? { slots: payload.slots } : { items: payload.items }) // il prezzo NON viene inviato: la public API ricalcola il prezzo server-side }) })
L'endpoint dipende da purchase_type:
appointment-purchases quando c'è data e ora, o
voucher-purchases quando è un buono senza data. Il payload già
ti dice quale, e porta slots o items di conseguenza.
Rimuovere un elemento
Riapri il motore con data-siana-item-id (modalità elimina): conferma la rimozione
emettendo cart:remove e si chiude. Tu rimuovi quell'elemento dalla tua prenotazione tramite il suo ID.
SianaBooking.open({ preset: 'hotel', sessionId: 'ID-PRENOTAZIONE-HOTEL', itemId: ITEM_ID, mode: 'drawer' })
SianaBooking.on('cart:remove', function (data) {
// data.session_id, data.item_id → rimuovilo dalla tua prenotazione
})
item_id che è arrivato nell'handoff: è lo stesso ID che il motore ti restituisce in
cart:remove alla conferma della rimozione.
Contratto del payload
Esempio di un appuntamento con data (purchase_type: "appointment").
In modalità buono arriva "voucher" con items[] invece
di 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": "Circuito Spa",
"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
- Versione del contratto (oggi
1). Se un giorno cambia in modo incompatibile, questo numero aumenta: usalo per rilevarlo. - type
- Tipo del messaggio
postMessage:siana:cart-handoff. L'SDK lo riemette come eventocart:handoff. - session_id
- Il
data-siana-session-idche hai passato tu, restituito intatto. È il tuo riferimento di prenotazione: usalo per associare la spa alla camera. - center_uuid
- UUID del centro spa a cui appartiene la selezione.
- purchase_type
appointment(appuntamento con data → arrivaslots) ovoucher(buono senza data → arrivaitems). Determina l'endpoint al momento della creazione.- total_reference
- Importo totale di riferimento, per essere visualizzato. La public API ricalcola il prezzo al momento della creazione; non addebitare in base a questo numero.
- slots / items
- Le linee da creare, già nel formato accettato dalla public API. Vengono reinviate senza traduzione.
- ↳ item_id
- ID unico di quella linea all'interno del carrello. È quello che arriva in
cart:removee quello che passi indata-siana-item-idper rimuoverla. - ↳ fulfillment_on / duration
- (appointment) data e ora
YYYY-MM-DD HH:MM:SSe durata in minuti. - ↳ price_per_person
- prezzo unitario di riferimento:
amountin centesimi e valuta. - ↳ rate_db_id
- ID della tariffa scelta (
0= tariffa base). - ↳ item_type
- (voucher) tipo di linea:
service,service_packageogift_card.
Sicurezza e allowlist
Il motore emette l'handoff solo verso origini autorizzate esplicitamente. Si configura nel deployment del motore, non nel tuo sito web:
NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.tuhotel.com,https://www.tuhotel.com
postMessage né tramite
callback_url — e il widget sembrerà non fare nulla al
completamento. Non è un errore del tuo codice. Passaci i tuoi domini esatti
(con protocollo, senza barra finale) prima di iniziare a testare.
- Con la lista configurata: il
postMessageviene pubblicato solo a quelle origini, e ilcallback_urlviene accettato solo se èhttpse la sua origine è nella lista. - Senza lista, in produzione: non viene emesso nulla e rimane un avviso nel log.
- In sviluppo locale: c'è un fallback permissivo per poter montare la demo, ma il
callback_urltramite beacon richiede sempre la allowlist. - Verifica l'origine comunque se ascolti
postMessagein modo grezzo, senza l'SDK. È una riga e ti protegge da qualsiasi altro iframe della pagina.
callback_url è un URL pubblico
tuo: chiunque può fare un POST. Autentica ogni richiesta
(intestazione segreta, firma condivisa o mTLS), verifica che v
sia una versione che supporti e che center_uuid e
purchase_type siano quelli che ti aspetti, e collega il
session_id a una sessione ospite che hai già autorizzato
prima di creare o modificare qualcosa. Il JSON ricevuto non dimostra da sé
chi lo invia.
Provalo qui.
Questo simula il sito web di un hotel. In alto, la prenotazione del soggiorno; in basso,
la sua sezione spa. Clicca su "Cerca disponibilità", scegli un trattamento e
"Finalizza": il widget non ti chiederà di pagare — la selezione entra nella prenotazione
e il totale viene ricalcolato. Questo è ciò che la tua pagina riceve tramite cart:handoff.
cart:handoff o un cart:remove vedrai un
alert() con il JSON grezzo, per verificare a colpo d'occhio cosa ti sta
consegnando il motore. Nella tua integrazione reale quel dato lo elabori nel codice e l'utente
non vede nulla: l'alert() è qui solo per rendere il dato visibile mentre
testi.
Payload ricevuto dal motore spa
Evento cart:handoff così come arriva alla tua pagina.
Checklist
Ciò che serve per passare dalla demo alla produzione. I primi tre punti dipendono da noi; gli altri, dal tuo team tecnico.
- I tuoi domini nella allowlist. Passaci le origini esatte da cui si aprirà il widget. Senza questo non viene emesso l'handoff (punto 8).
- L'origine del tuo motore. Ti diamo il dominio del motore per lo
<script src>e per verificare l'origine delpostMessage. - Chiave partner per la public API. Il tuo backend ne ha bisogno per creare la prenotazione spa (punto 5).
- Decidi cosa mostrare: un servizio specifico (
view="widget"+data-siana-service) o l'intero catalogo (view="full"). - Scegli la modalità: pannello laterale, modale o integrato. Si cambia con un attributo, senza toccare il resto.
- Passa il tuo riferimento di prenotazione in
data-siana-session-ide salvalo insieme alla selezione. - Ascolta
cart:handoffe disegna le righe nel tuo riepilogo. Aggiungicart:removese permetti di rimuoverle. - Crea la prenotazione spa quando confermi quella dell'hotel e gestisci il caso di posto già occupato (punto 2).