← Torna all'inizio Integrazione hotel
Embed SDK v1 · preset hotel · handoff

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.

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 widget di Sianamostra catalogo e disponibilità reale, e restituisce la selezione. Non addebita né crea nulla.
Il tuo motore di hotelriceve la selezione, la salva insieme alla prenotazione della camera e posticipa l'addebito alla fattura.
Il tuo backendcrea la prenotazione spa chiamando la public API quando la prenotazione dell'hotel è confermata.
Il prezzo del payload è di riferimento. Serve per disegnare la riga nel tuo riepilogo. La fonte di verità è la public API, che ricalcola il prezzo e convalida la disponibilità al momento della creazione. Non addebitare mai in base all'importo dell'handoff.

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.

PassoAttoreCosa succede
Selezionebrowser · SianaL'hotel apre il widget (drawer) e l'ospite sceglie servizio e orario. Siana non crea nulla.
Handoffwidget → hostCliccando su «Finalizza» il widget emette cart:handoff con il payload. L'host lo associa alla sua prenotazione tramite session_id.
start / createhost → public APIReindirizza 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).
confirmhost → public APIPassa 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.

Non c'è blocco dello slot tra l'handoff e lo 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
})
Il pulsante «rimuovi» si trova nel tuo riepilogo, non nel widget. Contrassegnalo con l' 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 evento cart:handoff.
session_id
Il data-siana-session-id che 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 → arriva slots) o voucher (buono senza data → arriva items). 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:remove e quello che passi in data-siana-item-id per rimuoverla.
↳ fulfillment_on / duration
(appointment) data e ora YYYY-MM-DD HH:MM:SS e durata in minuti.
↳ price_per_person
prezzo unitario di riferimento: amount in centesimi e valuta.
↳ rate_db_id
ID della tariffa scelta (0 = tariffa base).
↳ item_type
(voucher) tipo di linea: service, service_package o gift_card.
L'handoff non contiene dati personali o di pagamento. Né nome, né email, né carta. L'identità dell'ospite la fornisci tu al momento della creazione della prenotazione. Questo è intenzionale: riduce a cosa ti espone un'origine mal configurata.

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
Questa è la prima cosa da risolvere in una nuova integrazione. In produzione il comportamento è negare per difetto: se il tuo dominio non è in questa lista, l'handoff semplicemente non viene emesso — né tramite 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 postMessage viene pubblicato solo a quelle origini, e il callback_url viene accettato solo se è https e 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_url tramite beacon richiede sempre la allowlist.
  • Verifica l'origine comunque se ascolti postMessage in modo grezzo, senza l'SDK. È una riga e ti protegge da qualsiasi altro iframe della pagina.
La allowlist controlla dove esce l'handoff, non chi entra nel tuo endpoint. Il 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.
9 · Demo dal vivo

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.

Gli avvisi a comparsa fanno parte della demo, non del prodotto. Ogni volta che arriva un 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.

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 del postMessage.
  • 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-id e salvalo insieme alla selezione.
  • Ascolta cart:handoff e disegna le righe nel tuo riepilogo. Aggiungi cart:remove se permetti di rimuoverle.
  • Crea la prenotazione spa quando confermi quella dell'hotel e gestisci il caso di posto già occupato (punto 2).
Dubbi su qualche punto? Scrivici con il tuo caso specifico: modalità, vista e in quale momento del tuo flusso vuoi creare la prenotazione. È ciò che serve per definire i dettagli.