Chekin Web SDK – Guia de integração técnica

O Chekin Web SDK permite-lhe incorporar todo o processo de registo de hóspedes (check-in) diretamente na sua própria aplicação web, portal de proprietários ou PMS. O SDK fornece uma camada de integração segura com a plataforma Chekin, oferecendo ao mesmo tempo uma experiência para o hóspede totalmente personalizável e fluida.

1. O que é o Chekin Web SDK?

O Chekin Web SDK é uma biblioteca JavaScript leve que lhe permite:

• Incorporar o fluxo completo de check-in do hóspede na sua web ou aplicação.

• Iniciar processos de registo com base na reserva, no hóspede ou na propriedade.

• Personalizar o aspeto do widget incorporado.

• Gerir eventos e callbacks do fluxo.

• Utilizar um token JWT seguro gerado no seu backend para autenticar os pedidos.

Foi concebido para equipas que precisam de uma integração rápida, estável e segura, sem redirecionar os utilizadores para páginas externas.

---

2. Principais funcionalidades

• ✔ Incorporação na página através de iFrame ou modo de ecrã inteiro

• ✔ SDK JavaScript leve

• ✔ Autenticação segura baseada em JWT

• ✔ Compatível com SPA (React, Vue, Angular, etc.)

• ✔ Suporta vários modos de fluxo:

  • Fluxo de reserva

  • Fluxo de hóspede

  • Fluxo de propriedade

• ✔ Temas de interface e personalização da marca

• ✔ Hooks e eventos para controlo total do processo

---

3. Requisitos técnicos

Backend

• Tem de conseguir gerar tokens JWT assinados com a sua API Key da Chekin.

• Endpoint de backend para pedir um token antes de iniciar o fluxo.

Frontend

• Ambiente compatível com ES6+.

• Capacidade de carregar scripts externos a partir de uma CDN ou instalar via npm.

Credenciais

Vai precisar de:

• API Key da Chekin

• IDs relevantes consoante o fluxo:

  • reservation_id

  • guest_id

  • property_id

---

4. Instalar o SDK

CDN

<script src="https://assets.chekin.io/sdk/web/v1/chekin-sdk.js"></script>

npm

npm install @chekin/web-sdk

Depois importe-o:

import ChekinSDK from "@chekin/web-sdk";

---

5. Inicialização do SDK

Exemplo:

const sdk = new ChekinSDK({
token: "JWT_FROM_YOUR_BACKEND",
lang: "en",
theme: {
primaryColor: "#2F80ED",
logoUrl: "https://yourdomain.com/logo.png"
}
});

Parâmetros disponíveis

Parâmetro	Tipo	Descrição
token	string	Token JWT obrigatório com o payload da integração.
lang	string	Idioma do widget (en, es, it, etc.).
theme	object	Personalização visual (cores, logótipos, etc.).
hooks	object	Callbacks opcionais para os eventos do processo.

---

6. Gerar o token JWT

O SDK não gera tokens: o seu backend tem de criar um JWT seguro assinado com a sua API Key da Chekin.

Exemplo de payload do token

{
"reservation_id": "12345",
"guest_id": "67890",
"property_id": "abcd1234",
"mode": "reservation"
}

Exemplo em Node.js

const jwt = require("jsonwebtoken");

const token = jwt.sign(
{
reservation_id: "RESERVATION_ID",
mode: "reservation"
},
process.env.CHEKIN_API_KEY,
{ expiresIn: "10m" }
);

---

7. Tipos de fluxo suportados

1. Fluxo de reserva

Este é o fluxo mais comum para convidar os hóspedes a concluir o seu registo.

sdk.start("reservation", {
reservation_id: "12345"
});

2. Fluxo de hóspede

Utilizado quando cada hóspede tem de concluir o seu próprio processo de check-in individual.

sdk.start("guest", {
guest_id: "67890"
});

3. Fluxo de propriedade

Utilizado para a configuração ao nível da propriedade ou para fluxos de trabalho específicos.

sdk.start("property", {
property_id: "ABCD"
});

---

8. Incorporar o SDK

Incorporado em iFrame

sdk.mount("#chekin-container");

HTML:

<div></div>

Modo de ecrã inteiro

sdk.startFullscreen();

---

9. Hooks e callbacks

Pode subscrever os eventos emitidos pelo SDK.

const sdk = new ChekinSDK({
token,
hooks: {
onStatusChange: (status) => {
console.log("Status:", status);
},
onComplete: (data) => {
console.log("Check-in completed:", data);
},
onClose: () => {
console.log("Widget closed");
}
}
});

Eventos disponíveis

Evento	Descrição
onStatusChange	Acionado quando o estado do check-in muda.
onComplete	Acionado quando o hóspede conclui o check-in.
onClose	Acionado quando o utilizador fecha o widget.

---

10. Exemplo de implementação completo

<script src="https://assets.chekin.io/sdk/web/v1/chekin-sdk.js"></script>
<div></div>

<script>
const sdk = new ChekinSDK({
token: "",
lang: "en",
theme: {
primaryColor: "#1F4F91",
logoUrl: "https://yourdomain.com/logo.png"
},
hooks: {
onComplete: (payload) => {
console.log("Check-in finished:", payload);
}
}
});

sdk.start("reservation", { reservation_id: "12345" });
sdk.mount("#chekin-container");
</script>

---

11. Perguntas frequentes (FAQ)

Posso personalizar as cores e o logótipo do widget?

Sim, utilize o objeto de configuração theme.

Preciso de guardar documentos ou dados pessoais dos hóspedes?

Não. A Chekin guarda e trata todos os dados em conformidade com o RGPD e com os requisitos policiais.

Durante quanto tempo deve o JWT ser válido?

Recomendamos 5–15 minutos, gerado a pedido.

O SDK é compatível com aplicações móveis?

Sim, as aplicações híbridas ou baseadas em webview podem incorporá-lo sem problemas.

---

12. Suporte técnico

Se precisar de ajuda para depurar ou implementar o SDK:

📧 irene.paez@chekin.com

Inclua:

• Reservation ID / Guest ID / Property ID

• Tipo de fluxo

• Registos de rede

• Token utilizado (se for seguro partilhá-lo)

• Passos para reproduzir o problema

---

13. Limites de utilização, requisitos de ativação e aprovação obrigatória

A utilização do Chekin Web SDK e da Chekin API está sujeita a ativação comercial e técnica.

Ambas as ferramentas geram uma utilização que é monitorizada e faturada com base no número de propriedades, reservas ou chamadas API recorrentes.

Antes de ativar o SDK ou a API em produção, a sua conta tem de ser validada e ativada pela nossa equipa.

Isto é necessário para garantir que:

• A estrutura das suas propriedades está corretamente configurada

• Os limites de utilização e as definições de faturação estão aprovados

• O seu modo de integração (SDK, API ou híbrido) corresponde às suas necessidades operacionais

• Os requisitos de segurança (geração de JWT, separação de ambientes, limites de pedidos) são cumpridos

⚠️ IMPORTANTE:
O SDK/API não pode ser ativado automaticamente.

Tem de contactar a nossa equipa antes de ativar ou utilizar estas ferramentas.

Para ativação ou dúvidas, contacte:
📧 irene.paez@chekin.com