Saltar al contenido
GuestMaker by HotelinkingDesarrolladores
Vista generalDocumentaciónEventosSDKSandboxNovedades
EN/ES
Solicitar acceso
Vista generalDocumentaciónEventosSDKSandboxNovedades
Solicitar acceso
Volver al SSO de fidelización

Club externo

Inicio de sesión de fidelización para motores de reservas

Permite que los huéspedes inicien sesión en el club de fidelización del hotel desde tu motor de reservas. Envías al huésped a una página de inicio de sesión de GuestMaker; vuelve a la misma página que dejó, con sus fechas, hotel y ocupación intactos; y tu servidor recibe quién es: nombre, correo electrónico y nivel de socio.

Usa esta página si
  • La página a la que vuelve el huésped cambia con cada búsqueda (lleva fechas, hotel u ocupación).
  • Prefieres hacer dos llamadas HTTP antes que añadir una librería de OpenID Connect.
Usa en su lugar el inicio rápido de OIDC si
  • Tienes una única URL de callback fija o ya usas una librería de OpenID Connect.
Ir al inicio rápido de OIDC

Cómo funciona

Tres partes: el navegador del huésped, tu motor de reservas y GuestMaker. El huésped solo sale de tu sitio para una página de inicio de sesión.

  1. 1Tu motorGuestMaker

    El huésped pulsa «Iniciar sesión». Rediriges su navegador al inicio de sesión de GuestMaker, con tu client id y la página a la que debe volver.

  2. 2HuéspedGuestMaker

    El huésped inicia sesión en el club del hotel. ¿Ya inició sesión en los últimos 30 días? Se salta el formulario.

  3. 3GuestMakerTu motor

    El navegador vuelve a tu página, sin cambios, con un código de un solo uso añadido a la URL.

  4. 4Tu backendGuestMaker

    Tu servidor cambia el código por el socio: nombre, correo electrónico, nivel y el resto del perfil.

Lo que te proporcionamos

Cuatro cosas, configuradas una vez por motor de reservas. Pídelas a tu contacto de GuestMaker.

ElementoQué es
client_idIdentifica tu motor de reservas. Es público: va en la URL de inicio de sesión.
client_secretSe muestra una sola vez. Guárdalo en tu servidor: nunca debe llegar a un navegador.
Hosts de retorno permitidosLos hosts a los que puede volver el huésped, como book.hotel.com. Hosts, no URL exactas: se acepta cualquier ruta y consulta en ellos. http://localhost está permitido para desarrollo.
Modo de entregaCómo se añade el resultado a tu URL de retorno: code (recomendado), fragment, o both mientras pasas de uno a otro. El paso 2 muestra cada uno.
Paso 1
Envía al huésped al inicio de sesión
Paso 2
Lee lo que trae de vuelta
Paso 3
Obtén el socio
Paso 4
Lee el perfil con el token

1. Envía al huésped al inicio de sesión

Redirige el navegador del huésped a la página de inicio de sesión. Pasa la URL completa de la página a la que debe volver, codificada como un único valor: créala con una librería de URL, como en el ejemplo, para que sus propios ? y & no la dividan en parámetros separados.

const returnUrl = "https://book.hotel.com/rates?checkin=2026-10-01&adults=2";

const login = new URL("https://www.guestmaker.ai/loyalty/club/login");
login.searchParams.set("client_id", process.env.GM_CLIENT_ID);
login.searchParams.set("redirectUrl", returnUrl);   // encoded for you
login.searchParams.set("locale", "pt");

redirect(login.toString());

Parámetros

ParámetroObligatorioSignificado
client_idSíTu client id.
redirectUrlSíAdónde vuelve el huésped. Su host debe estar en tu lista permitida. Cualquier #fragment que lleve se descarta (el resultado se vuelve a añadir como en el paso 2). También se acepta como domain.
localeNoIdioma de la página de inicio de sesión: pt, es, en, fr, de o it. También se acepta como lang.
promptNonone para comprobar sin mostrar nada si el huésped tiene la sesión iniciada; login para mostrar siempre el formulario. Consulta Mantener la sesión del huésped.

2. Lee lo que trae de vuelta

El huésped vuelve a tu URL de retorno con un valor adicional. Cuál depende de tu modo de entrega:

VesCuandoQuién puede leerlo
?hlCode=…Modo de entrega codeTu servidor. Un código de un solo uso, válido durante 5 minutos.
#hlToken=…Modo de entrega fragmentSolo el navegador: la parte que sigue a # nunca se envía a un servidor.
AmbosModo de entrega bothUsa el código e ignora el token.
?hlError=login_requiredSolo con prompt=noneEl huésped no tiene la sesión iniciada. Muestra tu página normal.

Nunca pases el token a una query string para que llegue más fácilmente a tu servidor: las query strings se registran en cada proxy y log de acceso del camino. Precisamente por eso existe el código de un solo uso.

3. Obtén el socio

Ambas llamadas se ejecutan en tu servidor y envían tus credenciales de cliente. Sigue el bloque de tu modo de entrega.

Modo de entrega code: cambia el código por el socio

Un código funciona una vez, durante 5 minutos, y solo para el cliente al que se emitió. Si la llamada falla, no la repitas: envía al huésped de nuevo al inicio de sesión. Si sigue con la sesión iniciada, vuelve directamente con un código nuevo.

const code = new URL(req.url).searchParams.get("hlCode");

const res = await fetch("https://www.guestmaker.ai/api/loyalty/club/exchange", {
  method: "POST",
  headers: {
    "X-Client-Id": process.env.GM_CLIENT_ID,
    "X-Client-Secret": process.env.GM_CLIENT_SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ code }),
});

const { token, member } = await res.json();
// {
//   "token": "eyJ…",          ← keep it for step 4 (valid 5 minutes)
//   "token_type": "Bearer",
//   "expires_in": 300,
//   "member": { "id": "…", "email": "…", "firstName": "…", "tier": "gold", … }
// }

Modo de entrega fragment: pasa el token a tu servidor

Tu servidor no puede ver el token, así que unas líneas de JavaScript en la página de retorno lo envían a tu propio backend, que después lee el perfil con él (paso 4).

// On your return page, in the browser:
const token = new URLSearchParams(location.hash.slice(1)).get("hlToken");
if (token) {
  history.replaceState(null, "", location.pathname + location.search); // drop it from the URL
  await fetch("/club/token", {                                          // your own endpoint
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token }),
  });
}

// On your server, in /club/token: read the member with that token (step 4).

4. Lee el perfil con el token

Con el modo de entrega code ya tienes el socio desde el paso 3, así que solo necesitas esto para volver a leerlo mientras el token sea válido (5 minutos). Con el modo de entrega fragment, así es como obtienes el socio. Requiere el token y tus credenciales de cliente a la vez, de modo que un token robado por sí solo no puede leer los datos de un huésped.

const member = await fetch("https://www.guestmaker.ai/api/loyalty/club/me", {
  headers: {
    "X-Client-Id": process.env.GM_CLIENT_ID,
    "X-Client-Secret": process.env.GM_CLIENT_SECRET,
    Authorization: `Bearer ${token}`,
  },
}).then((r) => r.json());

El perfil del socio

CampoNotas
id, email, firstName, lastName, tierSiempre presente.
phone, address, city, zipCode, country, languagenull cuando el hotel no tiene el dato.
marketingConsenttrue, false, o null cuando nunca se le preguntó al huésped.

Mantener la sesión del huésped

Un huésped que inicia sesión una vez mantiene la sesión en GuestMaker durante 30 días, sea cual sea el motor o la página desde la que empezó (un motor club, un motor OIDC o el portal de socios), hasta que cierre sesión. Así que, siempre que necesites saber quién es el huésped, envíalo al inicio de sesión: si tiene la sesión iniciada, vuelve directamente y nunca ve el formulario.

// Check silently on page load: never shows a page.
login.searchParams.set("prompt", "none");
// → back with ?hlCode= / #hlToken= when signed in
// → back with ?hlError=login_required when not

// Always show the form (switch account, shared computer):
login.searchParams.set("prompt", "login");

// Sign the guest out of GuestMaker too, from your own logout:
const logout = new URL("https://www.guestmaker.ai/loyalty/club/logout");
logout.searchParams.set("client_id", process.env.GM_CLIENT_ID);
logout.searchParams.set("redirectUrl", "https://book.hotel.com/");
redirect(logout.toString());

El cierre de sesión, igual que el inicio, solo vuelve a un host de tu lista permitida, y cierra la sesión del huésped en GuestMaker en todos sus dispositivos. Sin él, tu propio cierre de sesión dura solo hasta la próxima vez que nos envíes al huésped.

Errores

DóndeRespuestaSignificado y qué hacer
Página de inicio de sesiónUna página de error (403)Client id desconocido, el programa de fidelización del hotel no está activo o el host de retorno no está en tu lista permitida. El huésped nunca se redirige. Revisa los parámetros y, después, contacta con nosotros.
exchange, me401 invalid_clientClient id o secret incorrectos.
exchange400 invalid_requestNo hay código en el cuerpo de la petición.
exchange400 invalid_grantEl código es desconocido, ha caducado, ya se usó o se emitió para otro cliente. Los cuatro casos se ven igual a propósito. Envía al huésped de nuevo al inicio de sesión.
me401 invalid_tokenEl token ha caducado (a los 5 minutos) o se revocó al cerrar sesión. Envía al huésped de nuevo al inicio de sesión.
exchange, me429Demasiadas peticiones. Espera y vuelve a intentarlo.
Si el huésped inicia sesión y nunca llega
Este fallo no muestra ningún error en ninguno de los dos lados.

El inicio de sesión puede funcionar y el navegador aun así rechazar la redirección final hacia ti. Comprueba, en este orden:

  • Tu host de retorno está en la lista permitida. Si no lo está, el inicio de sesión muestra una página de error antes de que el huésped inicie sesión: el caso fácil.
  • La consola del navegador al pulsar iniciar sesión. Un error form-action de Content-Security-Policy ahí nombra la URL de inicio de sesión, no tu URL de retorno, así que parece que el inicio de sesión falló cuando funcionó. Avísanos: esto nos toca arreglarlo a nosotros.
  • La página de inicio de sesión caduca a los 15 minutos. Un huésped que deja la pestaña y vuelve empieza de nuevo.
Un motor funcional que puedes ejecutar
examples/loyalty-club-rp/server.mjs: un archivo, sin dependencias.

Un motor de reservas de prueba que hace todo lo de esta página: ambas formas de los parámetros, los tres modos de entrega, el token devuelto desde el navegador y la lectura del perfil. Se ejecuta en localhost, que está permitido precisamente para esto.

GM_CLIENT_ID=… GM_CLIENT_SECRET=… node server.mjs
# → http://localhost:4321

Al arrancar, prueba un inicio de sesión real con tu configuración y te dice si el huésped podrá volver, antes de que hagas clic en nada. Pídenoslo junto con tus credenciales de sandbox.

GuestMaker by Hotelinking

El CRM con IA omnicanal
para grupos hoteleros.

● de Hotelinking ↗
DESARROLLARInicio rápidoReferencia de la APIAutenticaciónWebhooksSandbox de API
EXPLORAREventos webSDK y bibliotecasFidelización y SSOCrédito monetarioNovedades
CONECTARSolicitar acceso a la APIPlataforma GuestMakerIntegraciones
© 2026 GuestMaker · Hotelinking, S.L.Palma de Mallorca, España
PrivacidadCondicionesAviso legal
Política de cookies