El spa, dentro de la reserva del hotel.
El huésped elige su tratamiento sin salir de tu motor de reservas, y el spa se suma a la factura de su estancia. El widget de Siana no cobra: te devuelve la selección para que la crees con tu public API. Esta guía es todo lo que necesita tu equipo técnico — copiar, pegar y sustituir tu dominio.
Índice
Qué hace y qué no hace
Esta integración no es como las otras cuatro. Las demás conectan el motor con tu web; esta lo conecta con tu motor de reservas. El widget entra en modo read-only: enseña disponibilidad y precio, deja elegir, y al terminar emite la selección hacia tu página. No hay checkout, no hay pasarela, no se escribe nada en el backend de Siana.
El flujo de punta a punta
Dos fases. La primera ocurre entera en el navegador del huésped; la segunda, entre tu backend y la public API, cuando tú decidas.
| Paso | Actor | Qué pasa |
|---|---|---|
| Selección | navegador · Siana | El hotel abre el widget (drawer) y el huésped elige servicio y horario. Siana no crea nada. |
| Handoff | widget → host | Al pulsar «Finalizar» el widget emite cart:handoff con el payload. El host lo asocia a su reserva vía session_id. |
| start / create | host → public API | Reenvía slots/items a POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id). La public API revalida precio y disponibilidad, y crea la reserva started (held). |
| confirm | host → public API | Pasa started → confirmed y emite el locator. El cobro va en la factura del hotel (pago diferido). |
¿Cuándo cada llamada? start al añadir el spa al checkout del
hotel (reserva el slot, held; omitible si no necesitas hold). confirm cuando la
reserva de hotel queda pagada o confirmada. Abandono = no se llama a la API → no queda nada
pendiente. El precio del payload es sólo de referencia; manda lo que recalcula la public API.
start. El slot
se valida al crear, así que si pasa mucho tiempo puede haberse ocupado.
La public API te devolverá el error y tu motor decide: reintentar, ofrecer
otra hora o avisar. Cuanto antes crees, menos riesgo.
Montar el widget
Carga embed.js del motor y marca un botón con atributos
data-siana-*. Lo que activa el modo hotel es
data-siana-preset="hotel"; sin él, el widget se comporta como
un embed normal y sí cobra.
<script src="https://TU-MOTOR/embed.js"></script> <!-- Panel lateral, un servicio concreto --> <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"> Añadir spa a mi estancia </button> <!-- Modal centrado --> <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> <!-- Insertado en la página, catálogo completo --> <div data-siana-inline data-siana-view="full" data-siana-preset="hotel" data-siana-purchase-mode="appointment"></div>
Modo: drawer o modal (con
data-siana-open), o insertado (con
data-siana-inline). Vista:
widget para un solo servicio, full para el
catálogo entero. chrome="minimal" oculta la navegación del
motor.
session_id es tu identificador de reserva, y
vuelve intacto en el payload: es lo que te permite asociar el spa a la
habitación correcta. Además aísla el carrito, así que si el huésped cierra
y reabre el widget, su selección sigue ahí.
callback_url es opcional y se explica en el punto 4.
Recibir el handoff
Tres vías, y puedes combinarlas. La A es la recomendada; la C es el respaldo si no tienes JavaScript escuchando en la página.
// A) Con el SDK — recomendado, en la propia página SianaBooking.on('cart:handoff', function (payload) { // payload.purchase_type, payload.slots | payload.items, payload.session_id … anadirSpaALaReserva(payload) }) // El huésped puede quitar una línea desde tu resumen: SianaBooking.on('cart:remove', function (data) { quitarLinea(data.item_id) }) // B) postMessage crudo, sin SDK — verifica SIEMPRE el origen 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 recibe el MISMO payload por POST // (navigator.sendBeacon, Content-Type: text/plain). Sólo https y sólo // si tu origen está en el allowlist (ver punto 8).
El SDK reemite el postMessage siana:cart-handoff
como evento cart:handoff: es el mismo dato, más cómodo de
escuchar. Cada línea llega con su item_id, así que puedes
ofrecer un «quitar» en tu resumen y el widget se entera vía
cart:remove.
Crear la reserva de spa
El payload ya viene con la forma exacta que acepta la public API, así que
no hay que traducir nada: le añades el buyer (la identidad la
aportas tú, no el widget) y la referencia a la reserva de hotel.
// Esto corre SÓLO en tu servidor: la clave de partner no debe llegar nunca // al navegador. Cuando tu reserva de hotel se confirma: await fetch(`https://TU-MOTOR/api/v1/public/.../${payload.purchase_type}-purchases`, { method: 'POST', headers: { 'Authorization': 'ApiKey TU-CLAVE-DE-PARTNER', 'Content-Type': 'application/json' }, body: JSON.stringify({ buyer: huespedDelHotel, hotel_reservation_id: payload.session_id, ...(payload.slots ? { slots: payload.slots } : { items: payload.items }) // el precio NO se manda: la public API re-precia server-side }) })
El endpoint depende de purchase_type:
appointment-purchases cuando hay fecha y hora, o
voucher-purchases cuando es un bono sin fecha. El payload ya
te dice cuál, y trae slots o items en
consecuencia.
Quitar un item
Re-abre el motor con data-siana-item-id (delete mode): confirma la baja
emitiendo cart:remove y se cierra. Tú quitas ese item de tu reserva por su id.
SianaBooking.open({ preset: 'hotel', sessionId: 'ID-RESERVA-HOTEL', itemId: ITEM_ID, mode: 'drawer' })
SianaBooking.on('cart:remove', function (data) {
// data.session_id, data.item_id → quítalo de tu reserva
})
item_id que llegó en el handoff: es el mismo id que el motor te devuelve en
cart:remove al confirmar la baja.
Contrato del payload
Ejemplo de una cita con fecha (purchase_type: "appointment").
En modo bono llega "voucher" con items[] en vez
de 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
- Versión del contrato (hoy
1). Si algún día cambia de forma incompatible, sube este número: úsalo para detectarlo. - type
- Tipo del mensaje
postMessage:siana:cart-handoff. El SDK lo reemite como eventocart:handoff. - session_id
- El
data-siana-session-idque tú pasaste, devuelto intacto. Es tu referencia de reserva: úsalo para asociar el spa a la habitación. - center_uuid
- UUID del centro de spa al que pertenece la selección.
- purchase_type
appointment(cita con fecha → llegaslots) ovoucher(bono sin fecha → llegaitems). Determina el endpoint al crear.- total_reference
- Importe total de referencia, para pintar. La public API re-precia al crear; no cobres contra este número.
- slots / items
- Las líneas a crear, ya con la forma que acepta la public API. Se reenvían sin traducir.
- ↳ item_id
- id único de esa línea dentro del carrito. Es el que llega en
cart:removey el que pasas endata-siana-item-idpara darla de baja. - ↳ fulfillment_on / duration
- (appointment) fecha y hora
YYYY-MM-DD HH:MM:SSy duración en minutos. - ↳ price_per_person
- precio unitario de referencia:
amounten céntimos y moneda. - ↳ rate_db_id
- id de la tarifa elegida (
0= tarifa base). - ↳ item_type
- (voucher) tipo de línea:
service,service_packageogift_card.
Seguridad y allowlist
El motor sólo emite el handoff hacia orígenes autorizados explícitamente. Se configura en el despliegue del motor, no en tu web:
NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.tuhotel.com,https://www.tuhotel.com
postMessage ni por
callback_url — y el widget parecerá no hacer nada al
finalizar. No es un fallo de tu código. Pásanos tus dominios exactos
(con protocolo, sin barra final) antes de empezar a probar.
- Con la lista configurada: el
postMessagesólo se publica a esos orígenes, y elcallback_urlsólo se acepta si eshttpsy su origen está en la lista. - Sin lista, en producción: no se emite nada y queda un aviso en el log.
- En desarrollo local: hay un fallback permisivo para poder montar la demo, pero el
callback_urlpor beacon exige allowlist siempre. - Verifica el origen igualmente si escuchas
postMessageen crudo, sin el SDK. Es una línea y te protege de cualquier otro iframe de la página.
callback_url es una URL pública
tuya: cualquiera puede hacerle POST. Autentica cada petición
(cabecera secreta, firma compartida o mTLS), comprueba que v
es una versión que soportas y que center_uuid y
purchase_type son los que esperas, y liga el
session_id a una sesión de huésped que ya tengas autorizada
antes de crear o modificar nada. El JSON recibido no demuestra por sí
solo quién lo envía.
Pruébalo aquí mismo.
Esto simula la web de un hotel. Arriba, la reserva de la estancia; abajo,
su sección de spa. Pulsa «Buscar disponibilidad», elige un tratamiento y
«Finalizar»: el widget no te pedirá pagar — la selección entra en la reserva
y el total se recalcula. Eso es lo que tu página recibe por cart:handoff.
cart:handoff o un cart:remove verás un
alert() con el JSON crudo, para que compruebes de un vistazo qué te está
entregando el motor. En tu integración real ese dato lo procesas en código y el usuario
no ve nada: el alert() está aquí sólo para que el dato sea visible mientras
pruebas.
Payload recibido del motor de spa
Evento cart:handoff tal y como llega a tu página.
Checklist
Lo que hace falta para pasar de la demo a producción. Los tres primeros puntos dependen de nosotros; los demás, de tu equipo técnico.
- Tus dominios en el allowlist. Pásanos los orígenes exactos desde los que se abrirá el widget. Sin esto no se emite el handoff (punto 8).
- El origen de tu motor. Te damos el dominio del motor para el
<script src>y para verificar el origen delpostMessage. - Clave de partner para la public API. La necesita tu backend para crear la reserva de spa (punto 5).
- Decide qué muestras: un servicio concreto (
view="widget"+data-siana-service) o el catálogo entero (view="full"). - Elige el modo: panel lateral, modal o insertado. Se cambia con un atributo, sin tocar el resto.
- Pasa tu referencia de reserva en
data-siana-session-idy guárdala junto a la selección. - Escucha
cart:handoffy pinta las líneas en tu resumen. Añadecart:removesi dejas quitarlas. - Crea la reserva de spa cuando confirmes la de hotel, y gestiona el caso de hueco ya ocupado (punto 2).