← Voltar ao início Integração hotel
Embed SDK v1 · preset hotel · handoff

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.

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 widget da Sianamostra catálogo e disponibilidade real, e devolve a seleção. Não cobra nem cria nada.
O seu motor de hotelrecebe a seleção, guarda-a juntamente com a reserva do quarto e adia o pagamento para a fatura.
O seu backendcria a reserva de spa chamando a public API quando a reserva do hotel é confirmada.
O preço do payload é de referência. Serve para pintar a linha no seu resumo. A fonte de verdade é a public API, que re-preifica e revalida a disponibilidade ao criar. Nunca cobre com base no valor do handoff.

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.

PassoAtorO que acontece
Seleçãonavegador · SianaO hotel abre o widget (drawer) e o hóspede escolhe o serviço e o horário. A Siana não cria nada.
Handoffwidget → hostAo clicar em «Finalizar» o widget emite cart:handoff com o payload. O host associa-o à sua reserva via session_id.
start / createhost → public APIReenvia 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).
confirmhost → public APIPassa 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.

Não há bloqueio do intervalo entre o handoff e o 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
})
O botão «remover» vive no seu resumo, não no widget. Marque-o com o 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 evento cart:handoff.
session_id
O data-siana-session-id que 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 → chega slots) ou voucher (vale sem data → chega items). 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:remove e o que passa em data-siana-item-id para a remover.
↳ fulfillment_on / duration
(appointment) data e hora YYYY-MM-DD HH:MM:SS e duração em minutos.
↳ price_per_person
preço unitário de referência: amount em cêntimos e moeda.
↳ rate_db_id
ID da tarifa escolhida (0 = tarifa base).
↳ item_type
(voucher) tipo de linha: service, service_package ou gift_card.
O handoff não contém dados pessoais nem de pagamento. Nem nome, nem e-mail, nem cartão. A identidade do hóspede é fornecida por si ao criar a reserva. Isto é deliberado: reduz a sua exposição a uma origem mal configurada.

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
Isto é o primeiro a ser resolvido numa nova integração . Em produção o comportamento é negar por predefinição: se o seu domínio não estiver nessa lista, o handoff simplesmente não é emitido — nem por 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 postMessage só é publicado para essas origens, e o callback_url só é aceite se for https e 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_url por beacon exige a lista de permissões sempre.
  • Verifique a origem igualmente se ouvir postMessage em bruto, sem o SDK. É uma linha e protege-o de qualquer outro iframe da página.
A lista de permissões controla para onde vai o handoff, não quem entra no seu endpoint. O 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.
9 · Demonstração ao vivo

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.

Os avisos pop-up fazem parte da demonstração, não do produto. Cada vez que chega um 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.

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 do postMessage.
  • 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-id e guarda-a juntamente com a seleção.
  • Ouve cart:handoff e mostra as linhas no teu resumo. Adiciona cart:remove se 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).
Dúvidas sobre algum ponto? Escreve-nos com o teu caso específico: modo, vista e em que momento do teu fluxo queres criar a reserva. É o que é preciso para finalizar os detalhes.