Integración con PMS
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 /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.
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.
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.