Die Protel-API mit den Myprotelmod-Webhooks koppeln

Die Myprotelmod-API stellt Ihren Entwicklerinnen und Entwicklern einen kontrollierten Zugriff auf Zimmerreservierungen, Zimmerverfügbarkeiten, Ratenpläne und Gastprofile Ihres Protel-Mandanten bereit. Dieser Artikel erläutert die Grundprinzipien der Anbindung, typische Anwendungsfälle für Einzelhotels und kleine Ketten und zeigt, wie Webhooks eine saubere ereignisgetriebene Architektur zwischen Protel Air, Protel MPE, Protel SPE und Ihren nachgelagerten Systemen (DATEV, CRM, BI) ermöglichen.

1. Authentifizierung und API-Schlüssel

Die Myprotelmod-API arbeitet mit einer Authentifizierung per API-Schlüssel, den Sie im Kundenbereich unter Einstellungen → Integrationen → Protel-API generieren. Jeder Schlüssel ist genau einem Protel-Mandanten zugeordnet und lässt sich auf bestimmte Berechtigungen einschränken: Reservierungen lesen, Reservierungen schreiben, Zimmerverfügbarkeiten lesen, Ratenpläne ändern, Gastprofile lesen, Zugriff auf DATEV-Exporte oder auf die GoBD-signierten Belege.

Für jede Integration wird ein eigener Schlüssel angelegt (einer für DATEV, einer für Ihr BI, einer für ein hauseigenes CRM), statt einen einzigen Schlüssel überall zu verwenden. So lassen sich kompromittierte Schlüssel gezielt widerrufen und die Zugriffs-Logs bleiben lesbar. Jeder Aufruf muss den Schlüssel im Header X-Api-Key mitschicken und ausschließlich über TLS 1.3 erfolgen.

2. Reservierungen aus Protel auslesen

Der Endpunkt /reservations liefert Zimmerreservierungen für einen definierten Anreise- oder Abreisezeitraum, gefiltert nach Zimmerkategorie, Ratenplan oder OTA-Kanal (Booking.com, Expedia, HRS, hotel.de, Trip.com, Direktbuchung). Die Antwort enthält die Reservierungs-ID des Protel-Mandanten, den Namen des Hauptbuchers, die Zahl der Erwachsenen und Kinder, Anreise, Abreise, Zimmerkategorie, Ratenplan, Zahlungsstatus und den Herkunftskanal.

Ein typischer Aufruf zum Abgleich der Anreisen der kommenden Woche:

curl -H "X-Api-Key: $MYPROTELMOD_KEY" \
     "https://api.myprotelmod.org/v1/reservations?arrival_from=2026-08-10&arrival_to=2026-08-17&property=BER-01"

Der häufigste Anwendungsfall ist die tägliche Synchronisation dieser Reservierungen in ein hauseigenes CRM, um eine einheitliche Gastsicht aufzubauen: Aufenthaltshistorie, Sprachpräferenzen, Kissenwünsche, Loyalty-Status. Ein Aufruf alle vier bis sechs Stunden reicht für die meisten Häuser aus.

3. Zimmerverfügbarkeiten und Ratenpläne steuern

Der Endpunkt /availability verwaltet Zimmerverfügbarkeiten je Kategorie und Tag: freie Zimmer, minimale Aufenthaltsdauer, Close-to-Arrival- und Close-to-Departure-Regeln, manuelle Sperren für Renovierungen. Über /rateplans lassen sich zudem dynamische Ratenpläne (BAR, Frühbucher, Non-Refundable, Corporate, Loyalty) einspielen — inklusive Preisstaffelung nach Aufenthaltsdauer.

Ein typisches Szenario: Ihr Revenue Manager spielt jeden Montagmorgen die Preistabelle für die Folgewoche ein und berücksichtigt dabei Auslastungsprognose, Kompressionsdaten und laufende Messebelegung der Stadt. Die API verteilt die Änderungen anschließend in weniger als zwei Minuten auf Ihre Booking Engine und alle angeschlossenen OTA-Kanäle (Booking.com, Expedia, HRS, hotel.de, Trip.com).

4. Webhooks: ereignisgetriebene Architektur

Statt die API per Polling abzufragen, können Sie Myprotelmod-Webhooks für die wichtigsten Reservierungsereignisse registrieren: reservation.created, reservation.cancelled, reservation.modified, guest.checked_in, guest.checked_out, invoice.issued, invoice.tse_signed, meldeschein.confirmed. Myprotelmod sendet dann per POST einen HTTP-Aufruf an Ihren Endpunkt, sobald das Ereignis eintritt.

Webhooks eignen sich, um sofort eine individuelle Pre-Arrival-E-Mail zu verschicken, ein Live-Dashboard an der Rezeption zu aktualisieren oder Housekeeping und Haustechnik zu informieren, dass ein Zimmer für einen VIP-Gast früher vorbereitet werden muss. Jede Nutzlast ist per HMAC-SHA256 signiert; den Header X-Myprotelmod-Signature validieren Sie serverseitig gegen den in Ihrem Kundenbereich hinterlegten Webhook-Secret.

5. GoBD-konforme Belege und DATEV-Export

Für die Buchhaltung liefert der Endpunkt /invoices jede Rechnung inklusive TSE-Signatur nach BSI TR-03153, XRechnung- und ZUGFeRD-Struktur sowie der Referenz auf die zugrundeliegende Reservierung. Der Endpunkt /datev/export erzeugt on demand einen DATEV-konformen CSV-Export (Format „EXTF") für einen frei wählbaren Zeitraum. Die KassenSichV-Anforderungen (unveränderliche Belegkette, Journal-Log) werden serverseitig durchgesetzt — Ihre Anwendung braucht die Belege lediglich abzurufen und beim Steuerberater bereitzustellen.

6. Ratenlimits und bewährte Vorgehensweisen

Um die Plattform stabil zu halten, gilt bei Myprotelmod ein Limit von 600 Anfragen pro Minute je API-Schlüssel. Ein Überschreiten liefert HTTP 429 mit einem Retry-After-Header, der die einzuhaltende Wartezeit angibt. Wir empfehlen einen exponentiellen Backoff: 1 Sekunde beim ersten 429, 2 Sekunden beim zweiten, 4 Sekunden beim dritten.

• Bündeln Sie Aufrufe: /reservations?arrival_from=…&arrival_to=… statt einer Serie von Einzelaufrufen.
• Nutzen Sie Webhooks für Einzelereignisse und Polling nur für geplante Synchronisationen (Nachtlauf, Monatsabschluss).
• Speichern Sie Idempotenzschlüssel serverseitig, um Duplikate bei erneutem Webhook-Zustellversuch zu vermeiden.
• Halten Sie die Zeitzone Ihres Protel-Mandanten (Europe/Berlin) explizit im Timestamp fest — vermeidet Off-by-One-Fehler beim Datumsschnitt für Nachtläufe.

7. Sandbox und Dokumentation

Jeder Protel-Mandant verfügt über eine Sandbox, die strukturell identisch zur Produktion ist, aber vollständig isoliert läuft — inklusive einer TSE-Simulation, die valide Signaturen für Testbelege liefert. Damit prüfen Sie Ihre Integrationen, ohne die produktive Belegkette zu berühren. Die vollständige OpenAPI-Spezifikation, ein Beispielprojekt in Node.js und eine gebrauchsfertige Postman-Collection finden Sie auf der Seite API-Dokumentation.