Eventos del sitio web y del motor de reservas

Vista general

Un motor de reservas sabe cuándo se va un huésped; el hotel quiere escribirle mientras aún tiene el viaje en mente. Los eventos conectan ambos sistemas. Tu sitio web o motor de reservas envía un evento, se identifica al huésped como contacto y se inicia un recorrido que tenga ese evento como activador.

  YOUR SIDE                                  GUESTMAKER

  Server API   POST /api/v1/website-events  --+
  Webhook      POST .../hooks/gme_wh_...    --+-->  one contract  -->  contact + consent evidence
  Browser SDK  gm-events.js                 --+                   |
                                                                  +->  journey trigger --> wait --> email / WhatsApp
                                                                                      |
                                                                                      +--> stops when the booking completes

No hay que registrar nada antes. Envía un evento con cualquier nombre válido y aparecerá en el desplegable del editor de recorridos en cuanto se reciba, junto a los eventos estándar siguientes. Cada fuente (un sistema que envía eventos) tiene su propia clave, por lo que puedes pausarla o sustituirla sin modificar las demás.

Inicio rápido

1. En GuestMaker, abre Ajustes → Integraciones → Eventos del sitio web y del motor de reservas, elige Nueva fuente, selecciona Servidor y copia la clave secreta. Solo se muestra una vez.
2. Envía tu primer evento. Añade "test": true para validarlo y registrarlo sin modificar ningún huésped.
3. En la fuente, abre el Registro de entregas: allí encontrarás el evento y su resultado. Corrige cualquier problema señalado.
4. En un recorrido, elige el activador Evento del sitio web o del motor de reservas, selecciona Carrito abandonado, añade una espera y un correo electrónico, y actívalo.

curl -X POST 'https://www.guestmaker.ai/api/v1/website-events' \
  -H 'Authorization: Bearer gme_sk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"event":"cart.abandoned","idempotency_key":"cart_8841","contact":{"email":"ana@example.com","first_name":"Ana","language":"es"},"consent":{"email_marketing":true,"text":"I agree to receive offers from this hotel by email","captured_at":"2026-09-30T10:11:58Z","language":"en","form_id":"checkout-details"},"context":{"hotel_code":"HD-MAD","stage":"payment","check_in":"2026-11-20","check_out":"2026-11-23","adults":2,"room_name":"Deluxe","value":612.4,"currency":"EUR","cart_id":"8841","resume_url":"https://book.example.com/resume?cart=8841"}}'

Una solicitud correcta devuelve 202 con un resultado por evento. El ejemplo anterior es un carrito abandonado real con pruebas de consentimiento; añade "test": true para probarlo de forma segura.

{
  "received": 1,
  "accepted": 1,
  "duplicate": 0,
  "rejected": 0,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "code": "accepted",
      "message": "Accepted",
      "event_id": "9b0e…",
      "contact": "matched",
      "warnings": []
    }
  ]
}

Elige una vía de entrada

Las tres vías aceptan los mismos eventos y aplican las mismas reglas. Elige según las capacidades de tu sistema.

El evento

* indica un campo obligatorio. Los demás son opcionales; los campos que no figuren en el contrato se rechazan, en lugar de ignorarse.

Eventos estándar

Estos eventos tienen su propio apartado al principio del desplegable del editor de recorridos. Cualquier otro nombre en minúsculas y separado por puntos (por ejemplo, custom.spa_viewed) es un evento personalizado: envíalo y podrás seleccionarlo una vez recibido.

En cart.abandoned, context.stage indica en qué punto abandonó el huésped: dates, room, extras, details, payment. Puedes limitar un recorrido a determinadas etapas, por ejemplo, a huéspedes que llegaron al pago.

API de servidor

Envía POST /api/v1/website-events con Authorization: Bearer gme_sk_… y un cuerpo JSON: un evento, o { "events": [ … ] } con hasta 50. En un lote, cada evento se evalúa por separado: la solicitud se acepta y cada evento tiene su propio resultado, por lo que un evento incorrecto no provoca el rechazo de los demás.

Idempotencia y reintentos

Asigna a cada evento un idempotency_key. Al enviar de nuevo la misma clave, la respuesta es duplicate y no se modifica nada, por lo que puedes reintentarlo. Un evento que ningún recorrido activo esté esperando se cuenta, pero no se almacena; si se repite, vuelve a responder accepted y tampoco se modifica nada. Reintenta ante 429 (espera los segundos que indique Retry-After) y ante 5xx. Cualquier otro 4xx seguirá fallando si envías los mismos bytes.

Un evento individual que no supera la validación

Devuelve 422, con los campos y sus problemas en results[0].issues. El mismo evento dentro de un lote se indica en una respuesta 202.

{
  "received": 1,
  "accepted": 0,
  "duplicate": 0,
  "rejected": 1,
  "results": [
    {
      "index": 0,
      "status": "rejected",
      "code": "invalid_event",
      "message": "The event does not match the contract",
      "event_id": null,
      "contact": "none",
      "warnings": [],
      "issues": [
        {
          "field": "context.check_out",
          "message": "check_out must be after check_in"
        }
      ]
    }
  ]
}

El evento completo

{
  "event": "cart.abandoned",
  "idempotency_key": "cart_8841",
  "contact": {
    "email": "ana@example.com",
    "first_name": "Ana",
    "language": "es"
  },
  "consent": {
    "email_marketing": true,
    "text": "I agree to receive offers from this hotel by email",
    "captured_at": "2026-09-30T10:11:58Z",
    "language": "en",
    "form_id": "checkout-details"
  },
  "context": {
    "hotel_code": "HD-MAD",
    "stage": "payment",
    "check_in": "2026-11-20",
    "check_out": "2026-11-23",
    "adults": 2,
    "room_name": "Deluxe",
    "value": 612.4,
    "currency": "EUR",
    "cart_id": "8841",
    "resume_url": "https://book.example.com/resume?cart=8841"
  }
}

La descripción legible por máquinas está en el documento OpenAPI, generado a partir de las mismas definiciones que usa la API para validar, por lo que coincide con lo que acepta el servidor.

Webhook y asignación de campos

Muchos motores de reservas solo pueden enviar su propio JSON a una URL mediante POST. Crea un Webhook como fuente, da al motor la URL privada e indica a GuestMaker una vez cómo se corresponden sus campos con los nuestros. Sin código en ninguno de los sistemas.

POST https://www.guestmaker.ai/api/v1/website-events/hooks/gme_wh_…?test=1
Content-Type: application/json

{
  "type": "CartAbandoned",
  "step": "PAYMENT",
  "user": {
    "mail": "ana@example.com",
    "name": "Ana"
  },
  "cart": {
    "id": 8841,
    "total": "612,40",
    "currency": "eur"
  },
  "stay": {
    "in": "20/11/2026",
    "out": "23/11/2026"
  }
}

El editor de asignaciones

En «Configura la asignación de campos» de la fuente, GuestMaker abre la última solicitud enviada por el motor (con los datos personales enmascarados), muestra sus campos para elegirlos y previsualiza el evento tal como lo construirá el servidor. Cada fila toma un valor de un campo del payload, un valor fijo o una plantilla, como cart_{{cart.id}}. Transformaciones disponibles: lower, upper, trim, number, boolean, date, datetime. Un mapa de términos traduce el vocabulario del motor, por ejemplo, CartAbandoned → cart.abandoned.

Checking the URL

Muchos motores de reservas y herramientas de webhook comprueban una URL mediante GET antes de guardarla. Un GET a la URL del webhook no envía ningún evento: devuelve 200 con { "ready": true, "signature_required": … } cuando se aceptaría un POST; en caso contrario, devuelve el mismo 401 o 403 que recibiría un POST. Así se distingue una fuente pausada de un token mal escrito.

Firma

Si el motor puede firmar sus solicitudes, configura un secreto de firma en la fuente. Cada solicitud debe incluir X-GM-Signature: t=<unix seconds>,v1=<hex>, donde v1 es el HMAC-SHA256 de "<t>.<raw body>" con ese secreto, la construcción que usa Stripe. Firma los bytes exactos que envíes y usa una marca de tiempo con un margen de 5 minutos respecto al reloj del servidor. Durante la rotación de un secreto puedes enviar dos valores de v1.

import { createHmac } from 'node:crypto'

const t = Math.floor(Date.now() / 1000)
const v1 = createHmac('sha256', SIGNING_SECRET).update(`${t}.${rawBody}`).digest('hex')

// rawBody is the EXACT string you send. Then add this header to the request:
const signature = `t=${t},v1=${v1}`   // X-GM-Signature: t=1767225600,v1=5257a869…

Sin un secreto, la URL privada es la credencial: compártela solo con el motor y revócala en la fuente si se filtra.

SDK para navegador

/sdk/gm-events.js es un script pequeño, sin dependencias (menos de 6 KB comprimido), que no crea cookies. Envía eventos desde el navegador del visitante y es la única vía que detecta cuándo un huésped cierra la pestaña, el momento en que se determina que un carrito ha quedado abandonado.

<script async src="https://www.guestmaker.ai/sdk/gm-events.js"></script>
<script>
  window.gme = window.gme || function () { (gme.q = gme.q || []).push(arguments) }
  gme('init', { key: 'gme_pk_YOUR_PUBLIC_KEY' /* , hotelCode: 'HD-MAD' */ })

  // The moment the guest gives an email or phone in your booking form:
  // gme('identify', { email: 'ana@example.com' })

  // Report the booking when the guest leaves without finishing it:
  gme('abandonOnLeave', {
    getCart: function () {
      // Return the booking in progress, or null when there is none.
      return { cart_id: 'YOUR-CART-ID', stage: 'payment', check_in: '2026-11-20', check_out: '2026-11-23', value: 612.4, currency: 'EUR' }
    }
  })

  // When the booking is paid:
  // gme('completed', { cart_id: 'YOUR-CART-ID' })
</script>

Casillas de consentimiento

identify(contact, { consent: { email_marketing: true, text, form_id } }) registra una declaración de consentimiento con la frase que pases y la hora en que se marcó la casilla. Sin text, la selección se envía, pero el servidor la ignora y no se envían correos de marketing.

Google Tag Manager

Pega el fragmento del SDK para navegador anterior en una etiqueta HTML personalizada que se active en tus páginas de reservas. Mantén el carrito en una variable global que defina tu sitio y llama a gme('identify', …) y gme('completed', …) desde otras etiquetas.

Qué ocurre cuando algo falla

No provoca excepciones en tu página ni la bloquea. Ante un error de red, 429 o 5xx, reintenta hasta cinco veces con espera progresiva (1, 2, 4 y 8 segundos) y respeta Retry-After. Un 4xx se indica una vez en la consola con el motivo del servidor y no se reintenta. Los eventos registrados durante la espera de un reintento se ponen en cola detrás de él, para mantener el orden. Pueden esperar hasta 50 eventos; a partir de ahí, se descarta el más antiguo.

Consentimiento y cumplimiento

Son reglas de la plataforma, se aplican a todas las vías de entrada y no se pueden configurar.

1. Sin prueba de consentimiento no se envían correos de marketing. Se crea el huésped a partir del carrito abandonado y se inicia el recorrido, pero se omite el paso de correo electrónico, con un motivo visible para la cuenta, salvo que el contacto tenga consentimiento de marketing.
2. El consentimiento debe acreditarse para que se acepte. Solo se acepta consent.email_marketing: true con el text exacto que aceptó el huésped y un captured_at de los últimos 7 días. GuestMaker registra la frase, la hora, el idioma, el formulario y la IP y el agente de usuario de la solicitud en el registro de auditoría del consentimiento.
3. Un evento nunca puede volver a suscribir a un huésped que se haya dado de baja. Si el contacto se ha dado de baja o está excluido, se ignora la declaración de consentimiento y la respuesta lo indica (consent_ignored_opted_out). Una casilla premarcada por error no puede anular una baja.
4. Nunca es transaccional. Un recordatorio a un huésped que dejó una reserva a medias es un mensaje comercial. Los recorridos iniciados por un evento web envían correos en la categoría de marketing; todas las plantillas de WhatsApp que envíen requieren consentimiento de marketing, sea cual sea la categoría en la que se registraron.
5. Solo personas. Un mostrador de agencia, un dato de relleno o una cuenta genérica no se aceptan como persona, por lo que una dirección intermediaria de OTA nunca se convierte en contacto de marketing.

Úsalo en un recorrido

Elige el activador Evento del sitio web o del motor de reservas (categoría Sitio web y motor de reservas). El desplegable lista primero los eventos estándar y después los personalizados recibidos por tu cuenta, marcados como «aún no recibido» hasta que llegue uno.

Un flujo habitual de carrito abandonado: actívalo con cart.abandoned (o checkout.started), espera 30 minutos y envía el correo de recordatorio con un botón al enlace que permite al huésped retomar la reserva. Si mientras tanto el huésped completa la reserva, checkout.completed para el mismo carrito termina el recorrido antes de enviar el correo.

Usar el evento en un mensaje

Los datos del evento pueden usarse en el correo de un recorrido como etiquetas de combinación y en una plantilla de WhatsApp como variables. Ambos leen el evento que inició esa ejecución del recorrido.

Etiquetas de combinación de correo electrónico

Escribe la etiqueta en el correo electrónico o selecciónala en Evento web en el selector de etiquetas de combinación. Las fechas se escriben en el idioma del huésped («20 de noviembre de 2026» para un huésped hispanohablante) y los importes con el formato de su moneda. Si el evento no incluye un valor, se muestra texto vacío; adapta el texto que lo rodea para que se lea bien sin él.

Declara tus propios eventos de antemano

Un evento personalizado suele aparecer en el desplegable del activador cuando tu sitio web lo ha enviado. Para crear el recorrido antes de terminar la integración, decláralo en Ajustes → Integraciones → Eventos web → Eventos que pueden iniciar un recorrido. Aparece como «aún no recibido» y el primer evento real se registra en él. Un evento declarado que no se haya enviado puede eliminarse; uno recibido permanece en el historial. Los nombres usan minúsculas, dígitos y guiones bajos con puntos entre las partes y deben coincidir con lo que envía tu sitio web.

Variables de WhatsApp

Los eventos solo se almacenan cuando hay un huésped identificado y un recorrido activo que los espera. Enviar un evento que ningún recorrido espera no consume recursos ni crea datos.

Errores y resultados

Los errores de solicitud devuelven { error: { code, message, detail?, fix, docs } } y el estado HTTP indicado. El enlace docs apunta a la entrada siguiente y fix indica qué cambiar.

Límites

Pruebas

• Añade "test": true (o ?test=1 en una URL de webhook): el evento se valida y registra, sin iniciar recorridos ni escribir contactos.
• Enviar evento de prueba en una fuente envía un evento desde el panel, para comprobar la conexión antes de que el motor esté listo.
• El Registro de entregas muestra cada solicitud con su resultado, el motivo del rechazo y un enlace para corregirlo. Los datos personales aparecen enmascarados.
• Una solicitud con clave ausente o incorrecta no puede asociarse a ninguna fuente y no aparece en ningún registro de entregas: el remitente ve el 401 y la cuenta no ve nada. Si un proveedor indica que los eventos no llegan, empieza comprobando la clave con una solicitud que incluya "test": true.
• Para una fuente de navegador, añade debug: true un init para ver en la consola lo que envía el SDK.

Proveedores de motores de reservas

Si eres proveedor de un motor de reservas, no necesitas una integración con nosotros: tu cliente crea una fuente Webhook, asigna tus campos una vez y tú envías a su URL mediante POST. Este es el mensaje que un hotel puede enviarte.

Subject: Send booking events to GuestMaker

Hello,

We use GuestMaker to follow up with guests who leave a booking half-finished. Please send these events
from our booking engine to the webhook URL below, as JSON over HTTPS (POST):

  1. CartAbandoned  – the guest left before paying (please include which step they were on)
  2. BookingPaid    – the guest completed the booking (so we stop following up)

Webhook URL:   https://www.guestmaker.ai/api/v1/website-events/hooks/gme_wh_YOUR_WEBHOOK_TOKEN
Signing:       optional. If you can sign requests, we will give you a secret; the header is
               X-GM-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">

Each payload should carry, in your own field names (we map them, you do not need to change anything):
  - the guest's email (and phone if you have it)
  - the cart or booking id
  - the hotel
  - check-in and check-out dates, adults, room name, total and currency
  - the step reached, and a link that resumes the booking
  - if you collect marketing consent: the exact sentence shown and when it was ticked

An example of what you might send:

{
  "type": "CartAbandoned",
  "step": "PAYMENT",
  "user": {
    "mail": "ana@example.com",
    "name": "Ana"
  },
  "cart": {
    "id": 8841,
    "total": "612,40",
    "currency": "eur"
  },
  "stay": {
    "in": "20/11/2026",
    "out": "23/11/2026"
  }
}

If your tool checks a URL before saving it, a GET on the URL answers 200 when it is live.
Please add "?test=1" to the URL for a first request: it is checked and logged but starts nothing.
Questions: developers@guestmaker.ai

Thank you.

Novedades