Technischer Leitfaden zum Protel-Konnektor und zur Myprotelmod-API

Für Hotel-IT, technische Verantwortliche in Hotelketten und Multi-Property-Betreiber, die Protel PMS über den Myprotelmod-Konnektor an interne Systeme (DATEV, Yield-Tools, Housekeeping-App) anbinden möchten.

Überblick

Der Myprotelmod-Konnektor ist eine REST-Schnittstelle, die vor Ihrer Protel-PMS-Installation liegt und autorisierten Anwendungen lesenden und schreibenden Zugriff auf Ihre Hoteldaten gewährt: Zimmerreservierungen, Zimmerverfügbarkeiten, Raten, Gästeprofile, OTA-Kanäle. Alle Anfragen sind authentifiziert und laufen über HTTPS mit mTLS zum Protel-Server. Die Antworten werden als JSON in UTF-8 zurückgegeben und übersetzen die internen Protel-Feldnamen in ein sauberes, dokumentiertes Schema.

Base-URL und Versionen

Produktions-URL: https://api.myprotelmod.org/v1. Staging-URL: https://staging.myprotelmod.org/v1. Die aktuelle Version ist v1. Abwärtskompatible Weiterentwicklungen bleiben auf v1. Größere Änderungen führen zu einer v2 mit einer Übergangszeit von mindestens 12 Monaten — abgestimmt auf die Release-Zyklen von Protel PMS.

Schritte zur Einrichtung

API-Schlüssel im Kundenbereich erzeugen

Öffnen Sie in Ihrem Myprotelmod-Kundenbereich Einstellungen → Integrationen → API-Zugang. Klicken Sie auf „Neuer Schlüssel", benennen Sie ihn nach der Zielintegration (z. B. „DATEV-Export", „Yield-Tool", „Power BI Reporting") und wählen Sie ausschließlich die minimal notwendigen Berechtigungen (Scopes: reservations:read, availability:read, rates:write).

Schlüssel serverseitig speichern

Der Schlüssel wird bei der Erzeugung nur einmal angezeigt. Kopieren Sie ihn in Ihren Secret-Manager (HashiCorp Vault, AWS Secrets Manager, verschlüsselte Umgebungsvariablen auf dem Hotel-Backoffice-Server). Legen Sie ihn niemals in einem Git-Repository oder in einer .env-Datei auf einem Rezeptions-PC ab.

Im Staging gegen einen Test-Hotelmandanten prüfen

Richten Sie Ihre Aufrufe zunächst gegen staging.myprotelmod.org. Das Staging enthält einen Test-Hotelmandanten mit 40 Musterzimmern und synthetischen Buchungen, das jede Nacht zurückgesetzt wird. Prüfen Sie das Antwortformat, das Fehlerverhalten und die Ratenlimits, bevor Sie den Konnektor auf die Live-Protel-Installation umschalten.

In Produktion gehen

Ersetzen Sie die URL durch die Produktionsadresse und beobachten Sie die ersten 48 Stunden über die Aufrufprotokolle unter Einstellungen → Integrationen → Protokolle. Achten Sie besonders auf 409-Konflikte bei parallelen Schreibvorgängen aus dem Protel-Frontoffice und Ihrer externen Integration.

Authentifizierung

Jede Anfrage muss den Header X-Api-Key enthalten. Beispiel: X-Api-Key: mp_live_a1b2c3d4e5f6.... Staging-Schlüssel beginnen mit mp_staging_. Produktionsschlüssel beginnen mit mp_live_. Zusätzlich muss der Header X-Property-Code mit dem Protel-Property-Code (z. B. BER01 für Ihr Berliner Haus) gesetzt werden — sonst gibt der Konnektor bei Multi-Property-Installationen HTTP 400 zurück. Ein kompromittierter Schlüssel muss über die Verwaltungsansicht sofort widerrufen werden.

Kategorien von Endpunkten

Zimmerreservierungen: GET/POST/PATCH auf /reservations. Enthält Gästedaten, Anreise-/Abreisedatum, Zimmerkategorie, Ratenplan, Zahlungsstatus, Herkunftskanal (OTA oder Direktbuchung), gebuchte Zusatzleistungen.
Zimmerverfügbarkeiten: GET/PATCH auf /availability. Abruf und Sperren von Zimmern pro Kategorie und Datum, Steuerung von Stopsell und Mindestaufenthalt.
Raten: GET/POST auf /rates. Ratenpläne, BAR, Wochenendzuschläge, Firmenraten, saisonale Preise.
Zimmerkategorien: GET auf /room-types und /rate-plans. Katalogstruktur der Zimmertypen, Ausstattungsmerkmale, Bilder.
Gäste: GET/PATCH auf /guests. Gästestammdaten, Aufenthaltshistorie, Loyalty-Status, Präferenzen (Kissen, Zimmerlage).
OTA-Kanäle: GET auf /channels. Status der Anbindungen an Booking.com, Expedia, HRS, hotel.de, Trip.com über den mp-kanalmanager.
Webhooks: GET/POST/DELETE auf /webhooks. Registrieren von Ziel-URLs je Ereignistyp (reservation.created, reservation.cancelled, rate.updated).
Berichte: GET auf /reports. Belegung, Umsätze, ADR und RevPAR nach Kanal, Zimmerkategorie oder Property.

Ratenlimits

600 Anfragen pro Minute je API-Schlüssel und Property. Ein Überschreiten liefert HTTP 429 mit einem Retry-After-Header. Setzen Sie einen exponentiellen Backoff ein: 1 s, 2 s, 4 s, 8 s. Bündeln Sie Ihre Anfragen mit Datums-Ranges (?checkin_from=&checkin_to=), statt jede Reservierung einzeln abzufragen — das schont sowohl den Konnektor als auch die Protel-Datenbank.

Fehlerbehandlung

HTTP-Code	Bedeutung	Empfohlene Maßnahme
200 / 201	Erfolg	Antwort normal verarbeiten
400	Ungültige Anfrage — Payload fehlerhaft oder Property-Code fehlt	JSON-Struktur des Aufrufs und X-Property-Code prüfen
401	Nicht authentifiziert — Schlüssel fehlt oder falsch	Header X-Api-Key prüfen
403	Verboten — unzureichende Scopes	Berechtigungen des Schlüssels im Kundenbereich anpassen
404	Ressource nicht gefunden	Reservierungs- oder Zimmer-ID prüfen
409	Konflikt — Protel-Frontoffice hat parallel geschrieben	Ressource neu lesen (ETag) und erneut versuchen
429	Zu viele Anfragen	Retry-After beachten, Backoff einsetzen
500 / 503	Serverfehler am Konnektor oder Protel-Server	Nach 60 s erneut versuchen, bei Anhalten Support kontaktieren

Webhooks: HMAC-Signatur

Jeder von Myprotelmod versendete Webhook enthält den Header X-Myprotelmod-Signature mit einer HMAC-SHA256-Signatur des Requestkörpers, berechnet mit dem gemeinsamen Geheimnis Ihres Endpunkts. Prüfen Sie diese Signatur konsequent vor jeder Verarbeitung — andernfalls könnte eine dritte Partei Buchungs-Events fälschen und Ihr Yield-Modul manipulieren. Empfohlene Ereignisse für den Einstieg: reservation.created, reservation.modified, reservation.cancelled, guest.checked_in, guest.checked_out.