← Volver al inicio Integración hotel
Embed SDK v1 · preset hotel · handoff

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.

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 widget de Sianamuestra catálogo y disponibilidad real, y devuelve la selección. No cobra ni crea nada.
Tu motor de hotelrecibe la selección, la guarda junto a la reserva de habitación y difiere el cobro a la factura.
Tu backendcrea la reserva de spa llamando a la public API cuando la reserva de hotel se confirma.
El precio del payload es de referencia. Sirve para pintar la línea en tu resumen. La fuente de verdad es la public API, que re-precia y revalida disponibilidad al crear. Nunca cobres contra el importe del handoff.

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.

PasoActorQué pasa
Selecciónnavegador · SianaEl hotel abre el widget (drawer) y el huésped elige servicio y horario. Siana no crea nada.
Handoffwidget → hostAl pulsar «Finalizar» el widget emite cart:handoff con el payload. El host lo asocia a su reserva vía session_id.
start / createhost → public APIReenví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).
confirmhost → public APIPasa 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.

No hay bloqueo del hueco entre el handoff y el 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
})
El botón «quitar» vive en tu resumen, no en el widget. Márcalo con el 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 evento cart:handoff.
session_id
El data-siana-session-id que 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 → llega slots) o voucher (bono sin fecha → llega items). 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:remove y el que pasas en data-siana-item-id para darla de baja.
↳ fulfillment_on / duration
(appointment) fecha y hora YYYY-MM-DD HH:MM:SS y duración en minutos.
↳ price_per_person
precio unitario de referencia: amount en céntimos y moneda.
↳ rate_db_id
id de la tarifa elegida (0 = tarifa base).
↳ item_type
(voucher) tipo de línea: service, service_package o gift_card.
El handoff no lleva datos personales ni de pago. Ni nombre, ni email, ni tarjeta. La identidad del huésped la aportas tú al crear la reserva. Eso es deliberado: reduce a qué te expone un origen mal configurado.

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
Esto es lo primero que hay que resolver en una integración nueva. En producción el comportamiento es denegar por defecto: si tu dominio no está en esa lista, el handoff sencillamente no se emite — ni por 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 postMessage sólo se publica a esos orígenes, y el callback_url sólo se acepta si es https y 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_url por beacon exige allowlist siempre.
  • Verifica el origen igualmente si escuchas postMessage en crudo, sin el SDK. Es una línea y te protege de cualquier otro iframe de la página.
La allowlist controla hacia dónde sale el handoff, no quién entra en tu endpoint. El 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.
9 · Demo en vivo

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.

Los avisos emergentes son parte del demo, no del producto. Cada vez que llega un 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.

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 del postMessage.
  • 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-id y guárdala junto a la selección.
  • Escucha cart:handoff y pinta las líneas en tu resumen. Añade cart:remove si dejas quitarlas.
  • Crea la reserva de spa cuando confirmes la de hotel, y gestiona el caso de hueco ya ocupado (punto 2).
¿Dudas sobre algún punto? Escríbenos con tu caso concreto: modo, vista y en qué momento de tu flujo quieres crear la reserva. Es lo que hace falta para cerrar el detalle.