Skip to content

Integration scenarios

These scenarios show how the HotelPlatform APIs work together in real hotel integrations: a property management system (PMS) feeding reservations, a self check-in kiosk that issues key cards, a guest web app with PIN codes, card payments at the front office, and clients that stay in sync through webhooks and workflows. Each scenario links to the API categories it uses.

A PMS pushes reservations and profiles

A PMS, a channel manager or any other third-party client keeps the HotelPlatform up to date with its hotel reservations. It creates every new booking with its stays and guest profiles, and sends changes as they happen in the PMS.

Sequence diagram: a PMS or other third-party client creates a reservation with stays and guest profiles in the Hotel API, updates it when it changes, assigns a room and cancels its stays when the booking is cancelled.

  • Create and update bookings with the Reservations endpoints. Send the PMS's own id as externalId, so you can find the reservation again without storing HotelPlatform ids.
  • Keep guest data in Profiles: name, contact details, addresses and preferred language.
  • Arrival, departure, room assignment and services belong to the Stays of a reservation.
  • When a booking is cancelled, set the status of its stays to Cancelled instead of deleting the reservation. The booking and its history stay available, and subscribers receive a stayUpdated event they can act on.

Self check-in kiosk issues a key card

A kiosk in the lobby checks guests in without the front desk. It reads the reservation, lets the guest complete the registration, encodes a key card for the stay and hands it out from the card dispenser.

Sequence diagram: a guest checks in at a kiosk, which reads the reservation from the Hotel API, updates the guest profile, creates the key card with one createKey call that encodes it and moves it out of the card dispenser, and sets the stay to checked in.

  • Look up the booking in Reservations and check that the stay is eligible: arrival today, a room assigned and no amount due.
  • Save the registration details to the guest's profile.
  • Encode the key card with Key (Create a Key, POST /access/controllers/{controllerId}/key) on the card encoder's controller. When that controller references the kiosk's card dispenser, the same call moves the card out to the guest; no separate dispenser request is needed. CardDispenser is there for the dispenser's status and maintenance.
  • Set the stay to checked in through Stays. The encoder and the dispenser are set up once in the Configuration API.

Guest web app issues a PIN code

Guests who arrive late or skip the front desk get a PIN code for their room in a web app, linked from the booking confirmation. The PIN is valid from arrival to departure only.

Sequence diagram: a guest opens a web app before arrival, the app reads the stay from the Hotel API, checks that the stay has no key yet and has the AccessControl API create a PIN code, which the guest sees in the app.

  • Read the stay from Reservations, then create the PIN code with Key (Create a Key) on the controller of the PIN locks; a controller's type decides whether it issues key cards or PIN codes.
  • Before creating one, list the stay's keys with Key and show the PIN it already has: a guest who opens the app twice should not get a second code. To guarantee one PIN per reservation, let a workflow issue it (see the n8n example below).

Front office takes a payment on a terminal

The front office collects the amount due on a card terminal. A payment intent starts the transaction on the terminal; once it completes, the payment is recorded on the reservation. See the Payment API reference.

Sequence diagram: the front office starts a payment intent with the Payment API, the guest pays on the card terminal, the front office reads the final status and records the payment on the reservation in the Hotel API.

  • Start the transaction with a payment intent (POST /intents, amount in the lowest currency unit). It returns at once with status processing; the result arrives as the intentUpdated event or on a later read.
  • A terminal handles one transaction at a time: a second intent for the same terminal is refused with 409 until the first one is final.
  • Record the payment on the booking with Payments in the Hotel API.

A client keeps in sync through webhooks

Changes made by kiosks, web apps or the front office have to reach the PMS and other systems. Instead of polling, a client subscribes to the events it needs and receives them as signed webhooks.

Sequence diagram: a client subscribes to events, answers the signed verification challenge, and later receives signed profileUpdated and stayUpdated events, verifies them, reads the changed records from the Hotel API and applies them.

  • Create a webhook subscription with Subscription, listing events such as profileUpdated, stayUpdated or keyCreated. Your endpoint has to answer the signed verification challenge before the subscription is active.
  • Check every request as described in Webhook security, and use webhook-id to drop duplicates.
  • By default an event carries the resource type and id; read the current record from the Hotel API. With dataRequired: true the full event data comes along.

Pre-arrival PIN code built in n8n

Workflow tools such as n8n, Make or Zapier receive the same webhooks and turn events into automations without code on your servers. In this n8n example, a new booking triggers a pre-arrival email with the guest's PIN code.

Sequence diagram: an n8n workflow receives the signed reservationCreated webhook, answers the verification challenge, verifies the signature, reads the reservation from the Hotel API, issues the stay's single PIN code with the idempotent AccessControl call and emails it to the guest.

  • A Webhook trigger receives the events; a Respond to Webhook node echoes the challenge of the verification request so the subscription becomes active.
  • A Code node checks the signature over the raw body (Webhook security) and stops the workflow when it does not match.
  • One HTTP Request node reads the reservation from Reservations; a second one issues the PIN with Key (Create or Reconcile a Key for a Stay). That call is idempotent: when n8n retries or the event arrives twice, the stay keeps its single PIN code. An email node sends the message. For workflows on your own workflow server, a subscription with eventType: workflow starts the workflow directly.