O spa, dentro da reserva do hotel.
O hóspede escolhe o seu tratamento sem sair do seu motor de reservas, e o spa soma-se à fatura da sua estadia. O widget da Siana não cobra: devolve-lhe a seleção para que a crie com a sua public API. Este guia é tudo o que a sua equipa técnica necessita — copiar, colar e substituir o seu domínio.
Índice
O que faz e o que não faz
Esta integração não é como as outras quatro. As restantes conectam o motor com a sua web; esta conecta-o com o seu motor de reservas. O widget entra em modo read-only: mostra disponibilidade e preço, permite escolher, e ao terminar emite a seleção para a sua página. Não há checkout, não há gateway, não se escreve nada no backend da Siana.
O fluxo de ponta a ponta
Duas fases. A primeira ocorre totalmente no navegador do hóspede; a segunda, entre o seu backend e a public API, quando decidir.
| Passo | Ator | O que acontece |
|---|---|---|
| Seleção | navegador · Siana | O hotel abre o widget (drawer) e o hóspede escolhe o serviço e o horário. A Siana não cria nada. |
| Handoff | widget → host | Ao clicar em «Finalizar» o widget emite cart:handoff com o payload. O host associa-o à sua reserva via session_id. |
| start / create | host → public API | Reenvia slots/items para POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id). A public API revalida preço e disponibilidade, e cria a reserva started (held). |
| confirm | host → public API | Passa started → confirmed e emite o locator. O pagamento vai na fatura do hotel (pagamento diferido). |
Quando cada chamada? start ao adicionar o spa ao checkout do
hotel (reserva o slot, held; omitível se não necessitar de hold). confirm quando a
reserva do hotel está paga ou confirmada. Abandono = não se chama a API → não fica nada
pendente. O preço do payload é apenas de referência; manda o que a public API recalcula.
start. O slot
é validado ao criar, portanto, se passar muito tempo, pode ter sido ocupado.
A public API devolverá o erro e o seu motor decide: tentar novamente, oferecer
outra hora ou avisar. Quanto antes criar, menos risco.
Montar o widget
Carrega embed.js do motor e marca um botão com atributos
data-siana-*. O que ativa o modo hotel é
data-siana-preset="hotel"; sem ele, o widget comporta-se como
um embedded normal e cobra.
<script src="https://SEU-MOTOR/embed.js"></script> <!-- Painel lateral, um serviço específico --> <button data-siana-open data-siana-view="widget" data-siana-service="UUID-DO-SERVIÇO" data-siana-mode="drawer" data-siana-chrome="minimal" data-siana-preset="hotel" data-siana-purchase-mode="appointment" data-siana-session-id="ID-DA-SUA-RESERVA" data-siana-callback-url="https://api.seuhotel.com/spa/handoff"> Adicionar spa à minha estadia </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> <!-- Integrado na 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 ou modal (com
data-siana-open), ou integrado (com
data-siana-inline). Vista:
widget para um único serviço, full para o
catálogo inteiro. chrome="minimal" oculta a navegação do
motor.
session_id é o seu identificador de reserva, e
volta intacto no payload: é o que lhe permite associar o spa ao
quarto correto. Além disso, isola o carrinho, por isso, se o hóspede fechar
e reabrir o widget, a sua seleção continua lá.
callback_url é opcional e é explicada no ponto 4.
Receber o handoff
Três vias, e pode combiná-las. A A é a recomendada; a C é o apoio se não tiver JavaScript a escutar na página.
// A) Com o SDK — recomendado, na própria página SianaBooking.on('cart:handoff', function (payload) { // payload.purchase_type, payload.slots | payload.items, payload.session_id … adicionarSpaÀReserva(payload) }) // O hóspede pode remover uma linha do seu resumo: SianaBooking.on('cart:remove', function (data) { removerLinha(data.item_id) }) // B) postMessage "raw", sem SDK — verifique SEMPRE a origem window.addEventListener('message', function (e) { if (e.origin !== 'https://SEU-MOTOR') return if (e.data && e.data.type === 'siana:cart-handoff') { /* e.data */ } }) // C) Server-side — data-siana-callback-url recebe o MESMO payload por POST // (navigator.sendBeacon, Content-Type: text/plain). Apenas https e apenas // se a sua origem estiver na allowlist (ver ponto 8).
O SDK reemite o postMessage siana:cart-handoff
como evento cart:handoff: é o mesmo dado, mais cómodo de
escutar. Cada linha chega com o seu item_id, assim pode
oferecer um «remover» no seu resumo e o widget fica a saber via
cart:remove.
Criar a reserva de spa
O payload já vem com a forma exata que a public API aceita, por isso
não é preciso traduzir nada: adiciona-lhe o buyer (a identidade é
fornecida por si, não pelo widget) e a referência à reserva de hotel.
// Isto corre SÓ no seu servidor: a chave de parceiro nunca deve chegar // ao navegador. Quando a sua reserva de hotel é confirmada: await fetch(`https://SEU-MOTOR/api/v1/public/.../${payload.purchase_type}-purchases`, { method: 'POST', headers: { 'Authorization': 'ApiKey SUA-CHAVE-DE-PARCEIRO', 'Content-Type': 'application/json' }, body: JSON.stringify({ buyer: hospedeDoHotel, hotel_reservation_id: payload.session_id, ...(payload.slots ? { slots: payload.slots } : { items: payload.items }) // o preço NÃO é enviado: a public API recalcula o preço server-side }) })
O endpoint depende de purchase_type:
appointment-purchases quando há data e hora, ou
voucher-purchases quando é um voucher sem data. O payload já
lhe diz qual, e traz slots ou items em
consequência.
Remover um item
Reabra o motor com data-siana-item-id (delete mode): confirma a remoção
emitindo cart:remove e fecha. Você remove esse item da sua reserva pelo seu 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 → remova-o da sua reserva
})
item_id que chegou no handoff: é o mesmo id que o motor lhe devolve em
cart:remove ao confirmar a remoção.
Contrato do payload
Exemplo de um agendamento com data (purchase_type: "appointment").
No modo voucher chega "voucher" com items[] em 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
- Versão do contrato (hoje
1). Se algum dia mudar de forma incompatível, este número aumenta: use-o para detetar. - type
- Tipo da mensagem
postMessage:siana:cart-handoff. O SDK reemite-o como eventocart:handoff. - session_id
- O
data-siana-session-idque forneceu, devolvido intacto. É a sua referência de reserva: use-o para associar o spa ao quarto. - center_uuid
- UUID do centro de spa ao qual pertence a seleção.
- purchase_type
appointment(marcação com data → chegaslots) ouvoucher(vale sem data → chegaitems). Determina o endpoint ao criar.- total_reference
- Valor total de referência, para apresentar. A public API refaz o preço ao criar; não cobre com base neste número.
- slots / items
- As linhas a criar, já com o formato que a public API aceita. São reencaminhadas sem tradução.
- ↳ item_id
- ID único dessa linha dentro do carrinho. É o que chega em
cart:removee o que passa emdata-siana-item-idpara a remover. - ↳ fulfillment_on / duration
- (appointment) data e hora
YYYY-MM-DD HH:MM:SSe duração em minutos. - ↳ price_per_person
- preço unitário de referência:
amountem cêntimos e moeda. - ↳ rate_db_id
- ID da tarifa escolhida (
0= tarifa base). - ↳ item_type
- (voucher) tipo de linha:
service,service_packageougift_card.
Segurança e lista de permissões
O motor só emite o handoff para origens explicitamente autorizadas. Configura-se na implementação do motor, não no seu site:
NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.tuhotel.com,https://www.tuhotel.com
postMessage nem por
callback_url — e o widget parecerá não fazer nada ao
finalizar. Não é uma falha no seu código. Forneça-nos os seus domínios exatos
(com protocolo, sem barra final) antes de começar a testar.
- Com a lista configurada: o
postMessagesó é publicado para essas origens, e ocallback_urlsó é aceite se forhttpse a sua origem estiver na lista. - Sem lista, em produção: nada é emitido e fica um aviso no log.
- Em desenvolvimento local: há um fallback permissivo para poder montar a demo, mas o
callback_urlpor beacon exige a lista de permissões sempre. - Verifique a origem igualmente se ouvir
postMessageem bruto, sem o SDK. É uma linha e protege-o de qualquer outro iframe da página.
callback_url é um URL público
seu: qualquer um pode fazer-lhe POST. Autentique cada pedido
(cabeçalho secreto, assinatura partilhada ou mTLS), verifique se v
é uma versão que suporta e se center_uuid e
purchase_type são os que espera, e associe o
session_id a uma sessão de hóspede que já tenha autorizada
antes de criar ou modificar algo. O JSON recebido não demonstra por si
só quem o envia.
Experimente aqui mesmo.
Isto simula o site de um hotel. Em cima, a reserva da estadia; em baixo,
a sua secção de spa. Clique em «Pesquisar disponibilidade», escolha um tratamento e
«Finalizar»: o widget não lhe pedirá para pagar — a seleção entra na reserva
e o total é recalculado. Isso é o que a sua página recebe por cart:handoff.
cart:handoff ou um cart:remove verás um
alert() com o JSON cru, para que verifiques rapidamente o que te está
a ser entregue pelo motor. Na tua integração real, esse dado é processado em código e o utilizador
não vê nada: o alert() está aqui apenas para que os dados sejam visíveis enquanto
testas.
Payload recebido do motor de spa
Evento cart:handoff tal como chega à tua página.
Checklist
O que é preciso para passar da demo para a produção. Os três primeiros pontos dependem de nós; os restantes, da tua equipa técnica.
- Os teus domínios na lista de permissões. Envia-nos as origens exatas de onde o widget será aberto. Sem isso, o handoff não é emitido (ponto 8).
- A origem do teu motor. Damos-te o domínio do motor para o
<script src>e para verificar a origem dopostMessage. - Chave de parceiro para a API pública. O teu backend precisa dela para criar a reserva de spa (ponto 5).
- Decide o que mostras: um serviço específico (
view="widget"+data-siana-service) ou o catálogo inteiro (view="full"). - Escolhe o modo: painel lateral, modal ou integrado. Muda-se com um atributo, sem tocar no resto.
- Passa a tua referência de reserva em
data-siana-session-ide guarda-a juntamente com a seleção. - Ouve
cart:handoffe mostra as linhas no teu resumo. Adicionacart:removese permitires que sejam removidas. - Cria a reserva de spa quando confirmares a do hotel, e gere o caso de um lugar já ocupado (ponto 2).