Hotel-Zimmerbuchung (PMS)

Hinweis zur Systemintegration: Diese Funktion wurde auf Basis eines Simulationsadapters (Mock-Modus) entwickelt und getestet. Es liegt keine produktive Anbindung an ein Live-PMS vor. Für den Realeinsatz muss ein eigener PMS-Zugang sowie API-Zugangsdaten beim jeweiligen Anbieter (z. B. Apaleo oder Oracle OPERA) erworben und hinterlegt werden. Es wird keine zertifizierte Interoperabilität oder offizielle Freigabe durch Apaleo oder Oracle OPERA zugesichert.

Wozu dient das?#

Das Modul für die Hotel-Zimmerbuchung (PMS Integration) bindet die Kasse an das Property Management System (PMS) eines Hotels an. Im Backoffice richten Sie die Verbindung und die Ausfall-Richtlinie ein, prüfen ein Zimmerkonto, sehen das Protokoll der Zimmerbuchungen und stornieren eine Buchung. Gebucht wird dabei auf das Zimmerfoliokonto; der Gast begleicht die Rechnung erst beim Auschecken an der Hotelrezeption. Die Buchung selbst kommt über die Schnittstelle der Plattform, nicht über einen Bildschirm des Terminals.

Rollen#

Administrator (Betriebsleitung / IT): Konfiguriert die Zugangsdaten der PMS-Schnittstelle im Backoffice und legt die verbindliche Ausfall-Richtlinie (REFUSE vs. QUEUE) fest.
Servicekraft / Kellner: Nimmt Bestellungen am POS-Terminal auf und kassiert bar oder per Karte. Die Zimmerbuchung selbst hat im Terminal keinen Bildschirm (siehe Bildschirm für Bildschirm, Punkt 4).
Schichtleiter / Manager: Prüft im Reiter Transaktionsprotokoll & Storno die Zimmerbuchungen, stößt die Nachsynchronisation an und storniert Buchungen mit Korrektur.

Voraussetzungen#

Ein aktiver Vertrag und API-Zugangsdaten für ein unterstütztes Property Management System (API-Basis-URL, Property-ID, API-Schlüssel).
Die Konfiguration der PMS-Schnittstelle im Backoffice-Bereich PMS Hotel-Zimmerbuchung Integration.
Eine im Vorfeld festgelegte Ausfall-Richtlinie für Netzwerkausfälle (REFUSE oder QUEUE).
Eine geöffnete Schicht des Bedieners am POS-Terminal (→ Kapitel 12).

Bildschirm für Bildschirm#

Der Bereich PMS Hotel-Zimmerbuchung Integration trägt die Zeile PMS-Schnittstellen (Apaleo / Mock), Zimmer-Prüfung, Ausfall-Richtlinien und Stornierungen verwalten. Sie öffnen ihn im Backoffice über den Menüpunkt PMS (Administrator und Manager). Drei Reiter gliedern ihn.

1. Reiter Verbindung & Ausfall-Richtlinie#

PMS: Verbindung und Ausfall-Richtlinie

1 Die drei Reiter Verbindung & Ausfall-Richtlinie, Zimmer-Suchtest und Transaktionsprotokoll & Storno. Im Simulationsmodus steht darunter der Kasten Simulationsmodus & Apaleo Schnittstellenhinweis.
2 Anbieter: Apaleo (Cloud PMS API) oder Mock (Lokale Simulation / Test).
3 API Basis-URL: die Adresse des PMS (nennt der PMS-Anbieter).
4 Property-ID: die Kennung des Hotels im PMS.
5 Der Schlüssel des PMS. Das Feld trägt bisher die Beschriftung Fiskaly API-Key, gemeint ist der API-Schlüssel des PMS.
6 REFUSE (Verweigern): Standard und sicher; bei Netzausfall wird die Zimmerbuchung sofort abgelehnt.
7 QUEUE (Warteschlange): Store & Forward; die Buchung wird lokal gespeichert (Status QUEUED) und später nachsynchronisiert.
8 Einstellungen speichern.

2. Reiter Zimmer-Suchtest#

PMS: Zimmer-Suchtest

1 Der Reiter Zimmer-Suchtest mit der Überschrift Zimmer- und Gaststatus verifizieren.
2 Das Feld für die Zimmernummer. Es trägt bisher die Beschriftung Tisch-Nummer.
3 Nachname des Gastes (optional).
4 Zimmerkonto abfragen fragt das PMS ab (Meldung währenddessen: PMS wird abgefragt...).
5 Das Ergebnis: Zimmer … • Folio #…, Aktiv oder Inaktiv, der Kunde mit maskiertem Namen, Belastbar und Verbleibend.

3. Reiter Transaktionsprotokoll & Storno#

PMS: Transaktionsprotokoll und Storno

1 Der Reiter Transaktionsprotokoll & Storno.
2 Jetzt synchronisieren stößt die Nachsynchronisation an. Darüber steht PMS Zimmerbuchungs-Protokoll; ohne Eintrag steht dort Keine Zimmerbuchungen protokolliert.
3 Die Tabelle mit Posting-ID, Bestell-ID, Zimmer, Betrag, Status, Fehlermeldung, Datum und Aktion.
4 Korrektur in der Zeile öffnet die Maske PMS Zimmerbuchung stornieren.
5 Stornogrund: Pflichtfeld.
6 Stornierung bestätigen führt die Rückbuchung aus (Stornierung wird verarbeitet...). Danach kann die Meldung Storniert, Signatur folgt mit dem Titel Hinweis erscheinen.

4. Zimmeraufschrieb am Terminal (nur Schnittstelle)#

Im Zahlungsfenster der Kasse gibt es keine Zahlungsart Zimmeraufschrieb / Room Charge und keinen Dialog zur Zimmerprüfung. Die Buchung auf ein Zimmerkonto läuft über die Schnittstelle der Plattform (→ Kapitel 37); die Kasse bedient dort nur Bargeld und Karte (→ Kapitel 14).

Schritt für Schritt (mit Verzweigungen)#

Ablauf 1: Verbindung einrichten#

Öffnen Sie den Bereich PMS Hotel-Zimmerbuchung Integration und wählen Sie den Reiter Verbindung & Ausfall-Richtlinie.
Wählen Sie den Anbieter, tragen Sie API Basis-URL, Property-ID und den Schlüssel ein.
Wählen Sie die Ausfall-Richtlinie: REFUSE oder QUEUE.
Tippen Sie auf Einstellungen speichern.

Ablauf 2: Zimmer prüfen#

Wechseln Sie auf den Reiter Zimmer-Suchtest.
Tragen Sie die Zimmernummer und, wenn Sie möchten, den Nachnamen des Gastes ein.
Tippen Sie auf Zimmerkonto abfragen. Ist das Zimmer unbekannt oder das Konto geschlossen, meldet die Kasse einen Fehler (Fehler beim Ausführen der PMS-Transaktion., bei Bedarf mit der Meldung des PMS).

Ablauf 3: Verhalten bei PMS-Netzwerkausfall (Offline Policies)#

Fällt die Verbindung zum PMS bei einer Zimmerbuchung aus, bestimmt die gespeicherte Richtlinie das Verhalten:

Verzweigung A: Modus REFUSE (Standard & Empfohlen)
1. Die Zimmerbuchung wird sofort abgelehnt (Meldung PMS service unavailable — room charge refused. Please select an alternative payment method.).
2. Der Gast zahlt direkt vor Ort per Bargeld oder Karte.
Verzweigung B: Modus QUEUE (Store & Forward)
1. Die Buchung wird lokal mit dem Status QUEUED gespeichert, die Bestellung gilt als bezahlt, der Beleg trägt die TSE-Signatur.
2. Nachbearbeitung durch den Manager: Sobald die Verbindung wieder steht, versucht das Kassensystem die Nachsynchronisation. Im Reiter Transaktionsprotokoll & Storno sehen Sie, ob alle Einträge den Status SUCCESS erreicht haben; Jetzt synchronisieren stößt sie an.

Ablauf 4: Stornierung / Reversal einer Zimmerbuchung#

Öffnen Sie den Reiter Transaktionsprotokoll & Storno.
Tippen Sie in der Zeile der Buchung auf Korrektur.
Geben Sie den Stornogrund ein und tippen Sie auf Stornierung bestätigen.
Das PMS schreibt dem Foliokonto des Gastes den Betrag gut, der Status wechselt unveränderlich auf REVERSED, und die TSE signiert die Stornobuchung.

Was passiert im Hintergrund#

Beim Auslösen einer Zimmerbuchung generiert das Kassensystem einen eindeutigen Schlüssel (idempotency_key) und reserviert den Vorgang in den Protokollen (pms_posting_logs) mit dem Status IN_PROGRESS. Dadurch wird verhindert, dass Netzwerkwiederholungen oder mehrfaches Tippen zu Doppelbuchungen auf dem Gäste-Foliokonto führen.

Fiskalisch löst die Zimmerbuchung sofort den Aufruf FiscalService.finish_transaction mit der Zahlungsart ROOM_CHARGE aus. Die TSE signiert den Vorgang exakt wie eine Bar- oder Kartenzahlung. Zur Einhaltung der Datenschutz-Grundverordnung (DSGVO Art. 5 Abs. 1 lit. c) werden im Kassensystem nur die absolut notwendigen Transaktionsdaten (Zimmernummer, Folio-ID, maskierter Nachname) gespeichert. Es findet keine Synchronisation kompletter Gästedatenbanken statt.

Häufige Probleme#

1. `PMS service unavailable — room charge refused. Please select an alternative payment method.`#

Ursache: Das Hotel-PMS oder die lokale Internetverbindung ist ausgefallen und das Kassensystem ist auf den Offline-Behandlungsmodus REFUSE eingestellt.
Lösung: Bitten Sie den Gast um eine direkte Zahlung per Bargeld, EC-Karte oder Kreditkarte. Eine Zimmerbuchung ist im REFUSE-Modus bei Netzausfall nicht möglich.

2. `PMS service unavailable: {e}`#

Ursache: Die API-Schnittstelle des PMS antwortet mit einem unerwarteten Fehler oder einem Timeout (z. B. falsche API-Basis-URL oder abgelaufener API-Key).
Lösung: Überprüfen Sie im Bereich PMS Hotel-Zimmerbuchung Integration die API-Zugangsdaten und testen Sie die Erreichbarkeit der Serveradresse.

3. `PMS service unavailable for reversal: {exc}`#

Ursache: Eine Stornierung/Gutschrift konnte nicht an das PMS übermittelt werden, da die Netzwerkverbindung zum PMS unterbrochen ist.
Lösung: Stellen Sie die Netzwerkverbindung wieder her. Die Stornierung muss erneut ausgelöst werden, um die Daten im PMS synchron zu halten.

4. `Room charge error: {exc}`#

Ursache: Allgemeine Fehlermeldung des PMS-Adapters, z. B. wenn das angegebene Zimmer im PMS nicht existiert, nicht belegt ist oder das Foliokonto für Zusatzbuchungen gesperrt wurde.
Lösung: Prüfen Sie die Zimmernummer an der Hotelrezeption. Liegt eine Sperre vor, muss der Gast die Rechnung direkt an der Kasse begleichen.

5. `Cannot reverse PMS charge with status {status}`#

Ursache: Es wurde versucht, eine Zimmerbuchung zu stornieren, deren Status im System nicht SUCCESS lautet (z. B. wenn die Buchung noch IN_PROGRESS oder bereits REVERSED ist).
Lösung: Prüfen Sie den Status der Buchung im Reiter Transaktionsprotokoll & Storno. Ein bereits stornierter Vorgang kann nicht erneut storniert werden.

6. `Room charge posting is in progress for this idempotency key`#

Ursache: Ein identischer Buchungsversuch mit demselben Idempotenz-Schlüssel wird derzeit bereits vom System verarbeitet (z. B. durch schnelles Doppeltippen auf die Schaltfläche).
Lösung: Warten Sie zwei Sekunden ab. Das System schließt die laufende Anfrage automatisch ab und verhindert eine doppelte Abbuchung.

7. `PMS posting record not found`#

Ursache: Die im Stornierungs- oder Abfrageaufruf übergebene interne PMS-Protokoll-ID (pms_posting_id) existiert nicht in der Datenbank des Mandanten.
Lösung: Überprüfen Sie, ob Sie sich im richtigen Mandanten befinden oder wählen Sie die Buchung im Reiter Transaktionsprotokoll & Storno aus.

8. `Order not found`#

Ursache: Die übergebene order_id zur Zimmerbuchung existiert nicht im Kassensystem oder gehört zu einem anderen Mandanten.
Lösung: Vergewissern Sie sich, dass die Bestellung ordnungsgemäß erfasst und abgespeichert wurde.

Grenzen#

Die Integration basiert auf der Apaleo REST API sowie einem Simulationsadapter. Es besteht keine direkte Partnerschaft oder Zertifizierung seitens Apaleo oder Oracle OPERA.
Bei Aktivierung des QUEUE-Modus verbleibt das finanzielle Ausfallrisiko für nicht nachträglich synchronisierbare Buchungen beim Betrieb.
Die Kasseneingabe speichert aus Datenschutzgründen keine dauerhaften Gästeprofile im Kassensystem.

Dieses Kapitel gehört zum Merkuron-Handbuch für Inhaber und Servicepersonal.