Saltar al contenido
GuestMaker by HotelinkingDesarrolladores
Vista generalDocumentaciónEventosSDKSandboxNovedades
EN/ES
Solicitar acceso
Vista generalDocumentaciónEventosSDKSandboxNovedades
Solicitar acceso
Volver a la documentación para desarrolladores

SSO de fidelización

OIDC · v1

GuestMaker es un proveedor de identidad OpenID Connect estándar para huéspedes de fidelización. Tu sitio web se integra como Relying Party con el flujo Authorization Code y PKCE. Si tu plataforma ya admite «Iniciar sesión con Google / Apple / cualquier proveedor OIDC», es la misma integración con nuestros endpoints.

Inicio rápido para motores de reservas

¿Prefieres empezar por el código? Guía completa del flujo para copiar y pegar, independiente del framework.

Club externo: transferencia firmada

Sin cliente OIDC y con una URL de retorno que puede incluir el contexto de búsqueda del huésped.

Fidelización en tu sitio web

El popup web, los motores de reservas y un único inicio de sesión compartido: cómo encajan.

Protocolo
OAuth 2.1 + OpenID Connect
Flujo
Authorization Code + PKCE (S256)
Tokens
JWT RS256 · acceso ~5 min
Datos del socio
declaraciones de id_token + /api/loyalty/me/*

El flujo

Authorization Code + PKCE (S256), cliente confidencial. El huésped se autentica una vez en nuestro inicio de sesión con la marca del hotel; intercambias el código en el servidor y lees datos del socio con el token de acceso.

Los tokens de acceso duran poco (~5 minutos). Repite el flujo cuando uno caduque: como el huésped mantiene la sesión con nosotros, el nuevo inicio de sesión es silencioso (SSO real).

Un solo inicio de sesión para todo el grupo

Un huésped que inicia sesión una vez mantiene la sesión con nosotros durante 30 días, hasta que la cierre. La sesión es la misma sea cual sea la vía por la que llegó: un motor de reservas OIDC, un motor club externo o el portal de socios. Así, un grupo hotelero con dos motores en un mismo sitio web, uno de cada tipo, nunca pide al huésped que inicie sesión dos veces. Ambos flujos ofrecen los mismos tres controles: una comprobación silenciosa que nunca muestra una página (prompt=none), un formulario forzado para un ordenador compartido (prompt=login) y un cierre de sesión que desconecta al huésped en todas partes. Una sesión pertenece siempre a un solo grupo hotelero: un huésped del programa de otro grupo vuelve a iniciar sesión.

OIDC: mantener la sesión del huéspedClub externo: mantener la sesión del huésped
Cómo encaja todo
Un emisor; la cuenta (grupo hotelero) se obtiene de tu client_id.

Te proporcionamos un client_id y un client_secret (se muestra una vez) por entorno. Los huéspedes se autentican en el inicio de sesión con la marca del hotel que alojamos. Recibes un código de autorización, lo intercambias por tokens en el servidor y lees los datos del socio con el token de acceso.

Todo se descubre en la URL well-known: carga siempre endpoints y claves de firma desde el descubrimiento, en lugar de fijarlos en el código, porque rotamos las claves.

Permisos y declaraciones (v1)
El perfil, el correo electrónico y el nivel se incluyen en el id_token; el saldo e historial actuales provienen de los endpoints de recursos.
AlcanceDevuelveDónde
openidsub: the member's stable identifier. Required on every request.id_token
profilename, given_name, family_name, locale, country, updated_atid_token
emailemail (email_verified solo se emite cuando tenemos prueba de titularidad: nunca lo presupongas para socios existentes)id_token
loyalty:readloyalty_tier, loyalty_tier_name, points_balance, member_numberid_token + GET /api/loyalty/me/balance
transactions:readhistorial de obtención de puntos / canjesGET /api/loyalty/me/transactions

El saldo de crédito monetario está no disponible en v1.

Endpoints
Rutas canónicas bajo el emisor /api/oidc: resuélvelas desde el descubrimiento, no desde esta lista.
GET /api/oidc/.well-known/openid-configurationDescubrimiento: todos los endpoints, permisos y la URI de las JWKS. Cárgalos desde aquí; no los fijes en el código.
GET /api/oidc/authEndpoint de autorización (redirección del navegador).
POST /api/oidc/tokenEndpoint de tokens (de servidor a servidor, client_secret_basic).
GET /api/oidc/jwksClaves públicas de firma (RS256). Usa caché, pero actualízala ante un kid desconocido.
GET /api/loyalty/me/balanceNivel del socio + saldo de puntos + valor del crédito (token de acceso Bearer).
GET /api/loyalty/me/transactionsHistorial de puntos / canjes del socio (token de acceso Bearer).

No hay endpoint UserInfo por diseño: el perfil y el correo electrónico llegan como declaraciones de id_token y los datos actuales del socio se sirven mediante /api/loyalty/me/*. El token de acceso es un JWT RS256 cuyo aud es nuestro indicador de recurso. Estos endpoints lo verifican y aíslan los datos por socio y cuenta.

Requisitos de seguridad (obligatorios)
Los registramos y exigimos; las integraciones que los omiten fallan.
  • PKCE con S256 (nunca plain); un nuevo code_verifier por intento.
  • Envía y verifica state (CSRF) y nonce (protección frente a reutilización); comprueba que el parámetro de respuesta iss coincide con nuestro emisor.
  • Verifica la firma de id_token frente a nuestras JWKS con RS256: comprueba iss, aud = your client_id, nonce y la caducidad. Nunca aceptes un token sin verificar; rechaza alg: none / HS256.
  • redirect_uri debe coincidir exactamente: solo HTTPS, byte a byte, sin comodines ni variantes de barra final o mayúsculas. Registra cada valor que vayas a usar.
  • Mantén client_secret en el servidor; intercambia tokens solo desde tu backend. Usa TLS en todas las conexiones.
  • Guarda las JWKS en caché, pero actualízalas ante un kid desconocido: rotamos las claves.
Tokens y revocación
JWT sin estado con respaldo real de revocación.

Tanto access_token como id_token son JWT asimétricos RS256 que verificas frente a las JWKS publicadas. Los tokens de acceso duran unos 5 minutos.

La introspección está desactivada por diseño. Verifica la firma JWT y llama a /api/loyalty/me/*. Estos endpoints aplican una época de revocación en el servidor: cerrar sesión, bloquear, borrar datos o retirar el consentimiento invalida inmediatamente los tokens de acceso pendientes, incluso antes de que caduquen.

Respuestas de error
Errores estándar OAuth 2.0 en el endpoint de tokens; página de error del IdP (nunca redirección) si hay un client_id/redirect_uri o cuando el SSO no está activado para la cuenta.
errorSignificado
invalid_requestParámetro ausente o mal formado (p. ej., sin desafío PKCE, sintaxis de permisos incorrecta).
invalid_clientclient_id desconocido o client_secret incorrecto. Misma respuesta genérica para ambos.
invalid_grantCódigo caducado o reutilizado, redirect_uri no coincide o code_verifier no ha superado PKCE.
invalid_scopeSe ha solicitado un permiso no concedido a tu cliente.
access_deniedEl huésped ha abandonado o rechazado el inicio de sesión.
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