Saltar al contenido
GuestMaker by HotelinkingDesarrolladores
Vista generalDocumentaciónEventosSDKSandboxNovedades
EN/ES
Solicitar acceso
Vista generalDocumentaciónEventosSDKSandboxNovedades
Solicitar acceso
Volver a la vista general

Integración con PMS

de servidor a servidor

Un endpoint de lectura para cargar el estado del socio en la reserva. Cinco webhooks firmados con HMAC para mantenerte al día con los cambios de saldo. La entrega no está garantizada, así que concilia los datos con la instantánea de la reserva.

GET /reservation-snapshot
Devuelve en una sola llamada todo lo necesario para mostrar la interfaz de crédito monetario durante la estancia o a la salida.
GET /api/v1/loyalty/reservation-snapshot?reservation_id=${reservationId}
Authorization: Bearer ${GUESTMAKER_API_KEY}
Accept: application/json

// reservation_id is the GuestMaker reservation UUID. Scope: guests:read.
// Response (200)
{
  "success": true,
  "data": {
    "reservation": {
      "id": "uuid",
      "source": "direct",                // a string, or null
      "check_in": "2026-06-01",
      "check_out": "2026-06-04"
    },
    "member": {                          // null when the reservation holder is not a member
      "id": "uuid",
      "member_number": "ABC123",
      "points_balance": 12500,
      "lifetime_points": 18000,
      "tier_id": "uuid",                 // null when the member holds no tier
      "email": "guest@example.com",      // the holder's email, or null
      "full_name": "Ana Ruiz"            // or null
    },
    "spendable_points": 9500,            // = points_balance - active holds that have not expired
    "redemption_rate": 100,              // points per EUR 1
    "cash_credit_enabled": true,
    "applicable_surfaces": { "booking_direct": true, "in_stay": true, "checkout": false },
    "active_holds": [                    // the member's 10 latest holds that are active or confirmed
      {
        "hold_id": "uuid",
        "external_reference_id": "BOOK-2026-001",
        "points": 3000,
        "amount_value": 30.00,
        "currency": "EUR",
        "surface": "booking_direct",
        "status": "active",              // "active" or "confirmed"
        "expires_at": "2026-06-01T12:30:00Z",
        "confirmed_at": null             // a timestamp once the hold is confirmed
      }
    ]
  }
}

Usa spendable_points para decidir qué puede aplicar el socio ahora. No uses points_balance. Las retenciones activas ya están descontadas.

Eventos de webhook
Cinco eventos, enviados como JSON firmado con HMAC a la única dirección HTTPS que registra el programa. Solo se envían los eventos marcados en los ajustes del webhook.
loyalty.credit.held
{
  "event": "loyalty.credit.held",
  "tenant_id": "uuid",
  "occurred_at": "2026-06-01T10:00:00Z",
  "data": {
    "hold_id": "uuid",
    "member_id": "uuid",
    "points": 3000,
    "amount_value": 30.00,
    "currency": "EUR",
    "surface": "booking_direct",
    "external_reference_id": "BOOK-2026-001",
    "expires_at": "2026-06-01T10:15:00Z"
  }
}
loyalty.credit.confirmed
{
  "event": "loyalty.credit.confirmed",
  "tenant_id": "uuid",
  "occurred_at": "2026-06-01T10:05:00Z",
  "data": {
    "hold_id": "uuid",
    "transaction_id": "uuid",
    "member_id": "uuid",
    "points": 3000,
    "amount_value": 30.00,
    "currency": "EUR",
    "external_reference_id": "BOOK-2026-001"
  }
}
loyalty.credit.released
{
  "event": "loyalty.credit.released",
  "tenant_id": "uuid",
  "occurred_at": "2026-06-01T10:16:00Z",
  "data": {
    "hold_id": "uuid",
    "member_id": "uuid",
    "external_reference_id": "BOOK-2026-001",
    "points": 3000,
    "cause": "expired"   // /credit/release sends only hold_id and external_reference_id (null if you did not send it), with cause "released"
  }
}
loyalty.credit.reversed
{
  "event": "loyalty.credit.reversed",
  "tenant_id": "uuid",
  "occurred_at": "2026-06-02T09:00:00Z",
  "data": {
    "external_reference_id": "BOOK-2026-001",
    "points_restored": 3000   // a repeated reverse call (idempotent replay) sends no event
  }
}
loyalty.balance.changed
{
  "event": "loyalty.balance.changed",
  "tenant_id": "uuid",
  "occurred_at": "2026-06-01T10:05:00Z",
  "data": {
    "member_id": "uuid",
    "new_balance": 9500
  }
}

Una entrega que no recibe una respuesta 2xx en 15 segundos (una redirección cuenta como fallo) se reintenta al cabo de 1 minuto, 5 minutos, 30 minutos, 6 horas y 24 horas. Todas esas esperas se ejecutan dentro de la tarea en segundo plano de la solicitud que generó el evento, así que solo los primeros intentos son fiables: trata la entrega como no garantizada y concilia los datos con el endpoint de instantánea. Un reintento vuelve a enviar el mismo cuerpo y la misma firma, así que procesa cada evento de forma idempotente.

Verificación de firma HMAC
Verifica X-GM-Signature en todos los webhooks entrantes. Rechaza payloads sin firma o con firma incorrecta.
// Node.js: verify the X-GM-Signature header on every webhook.
// Its value is "sha256=" followed by the hex HMAC-SHA256 of the raw body.
import crypto from 'node:crypto';

function verifyLoyaltyWebhook(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  // Constant-time compare to avoid timing side channels.
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signature, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express handler
app.post('/webhooks/loyalty', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('X-GM-Signature') || '';
  if (!verifyLoyaltyWebhook(req.body.toString('utf8'), signature, process.env.LOYALTY_WEBHOOK_SECRET!)) {
    return res.status(401).end();
  }
  const payload = JSON.parse(req.body.toString('utf8'));
  // ... dispatch on payload.event
  res.status(200).end();
});

El secreto de firma se genera al guardar el webhook en Fidelización → Programa → Crédito en efectivo (Webhook del PMS). Un programa tiene un solo webhook: cada vez que lo guardas se sustituyen su dirección y sus eventos y se emite un secreto nuevo, que se muestra una sola vez; a partir de ese momento las entregas se firman con el secreto nuevo. Para rotarlo, guarda el webhook, añade el secreto nuevo a tu receptor y sigue aceptando el antiguo durante un tiempo, porque una entrega que ya espera un reintento conserva la firma con la que se envió la primera vez.

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