Myprotelmod API und Protel-Konnektor
Vollständiger programmatischer Zugriff auf Ihr Myprotelmod-Konto und Ihre Protel-PMS-Installation: Zimmerkategorien, Zimmerverfügbarkeiten, Ratenpläne, Reservierungen, Housekeeping-Ressourcen und Berichte. Für Hotelketten und Rezeptionsteams, die Myprotelmod an ihre individuell entwickelte Hotelwebsite, ihre mobile App für Gäste oder ihr internes ERP-System anbinden möchten.
Basis-URL
https://api.myprotelmod.org/v1
Authentifizierung
Alle Anfragen benötigen den Header Authorization: Bearer <api-key>. API-Schlüssel werden im Kundenbereich erzeugt und besitzen die gleiche Berechtigungsstufe wie das Eigentümerkonto Ihres Hotels. Sie können mehrere Schlüssel anlegen (Staging, Produktion, Housekeeping-App, Gäste-App) und unabhängig voneinander widerrufen.
Wichtigste Endpunkte
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/rooms | GET | Alle Zimmerkategorien mit Paginierung auflisten |
/rooms/{id} | GET | Vollständiges Zimmerkategorie-Profil abrufen (Fotos, Bettenkonfiguration, Ratenpläne) |
/rooms | POST | Neue Zimmerkategorie anlegen |
/rooms/{id} | PATCH | Bestehendes Zimmerkategorie-Profil bearbeiten |
/availability | GET | Zimmerverfügbarkeiten nach Kategorie und Zeitraum abfragen |
/availability | POST | Neue Verfügbarkeitsregel oder Blockade anlegen |
/rates | GET | Ratenpläne mit saisonalen Preisen und Mindestaufenthalt abfragen |
/rates | PATCH | Ratenplan aktualisieren (Yield-Steuerung, saisonale Anpassung) |
/reservations | GET | Reservierungen mit Filtern auflisten (Kanal, Status, Anreisedatum) |
/reservations/{id} | GET | Vollständiges Reservierungsdetail (Hotelgast, Zusatzleistungen, Meldeschein) |
/reservations | POST | Reservierung aus einem externen System heraus anlegen |
/reservations/{id}/cancel | POST | Reservierung mit Stornoregel stornieren |
/housekeeping | GET | Housekeeping-Kräfte, Etagenwagen und Wäschewagen auflisten |
/housekeeping/{id}/schedule | GET | Einsatzplan einer Housekeeping-Kraft über einen Zeitraum |
/reports/revpar | GET | RevPAR-, ADR- und Belegungsbericht mit MwSt.-Aufschlüsselung |
/reports/channels | GET | Umsatz- und Reservierungsaufteilung nach Buchungskanal |
/invoices | POST | GoBD-Rechnung oder Rechnungsstorno ausstellen |
Protel-Konnektor
Der Protel-Konnektor läuft entweder als Cloud-Bridge zu Protel Air oder als On-Prem-Agent für Protel MPE und SPE. Er nutzt den offiziellen Protel HTNG-Endpunkt sowie die Protel Air OpenAPI. Die Kopplung wird über OAuth 2.0 mit Ihrem Protel-Konto autorisiert. Sensible Zugangsdaten liegen ausschließlich verschlüsselt (AES-256) auf unseren Servern in Frankfurt.
Rate-Limits
Die API ist auf 120 Requests pro Minute je API-Schlüssel begrenzt, mit einem monatlichen Kontingent von 100.000 Requests, das im mp-kassensystem-tse-Modul enthalten ist. Bei Überschreitung wird HTTP 429 zurückgegeben; der Header Retry-After gibt die Wartezeit bis zum nächsten Versuch an. Erweiterte Kontingente sind für Hotelketten mit mehr als 500 Zimmern auf Anfrage erhältlich.
Ereignisgesteuerte Webhooks
Hinterlegen Sie eine oder mehrere Webhook-URLs im Kundenbereich, um Benachrichtigungen in Echtzeit zu empfangen. Jedes Ereignis wird per HTTP POST mit einem JSON-Body zugestellt und mit HMAC-SHA256 signiert (Header X-Myprotelmod-Signature), damit Sie die Herkunft empfangsseitig prüfen können.
| Ereignis | Auslöser |
|---|---|
reservation.created | Neue bestätigte Reservierung (über alle Kanäle) |
reservation.cancelled | Reservierung vom Hotelgast oder Rezeption storniert |
reservation.refunded | Erstattung durch den Zahlungsdienstleister ausgeführt |
checkin.completed | Digitaler Meldeschein an der Rezeption abgeschlossen |
housekeeping.status | Zimmerstatus vom Housekeeping-Tablet aktualisiert |
guest.created | Neuer Hotelgast in der Gäste-Datenbank angelegt |
availability.updated | Zimmerverfügbarkeit geändert (Anlage oder Blockade) |
Sandbox-Umgebung
Eine Testumgebung steht unter https://sandbox.myprotelmod.org/v1 zur Verfügung, inklusive eines vorbefüllten Kontos (Beispiel-Zimmerkategorien, fiktive Reservierungen, simulierter Protel-Server). Verwenden Sie den Sandbox-API-Schlüssel aus Ihrem Kundenbereich, um Ihre Integrationen zu testen, ohne Ihre Produktivdaten in Protel PMS zu berühren.
OpenAPI-Dokumentation
Eine vollständige OpenAPI-3.1-Spezifikation ist Bestandteil des mp-kassensystem-tse-Moduls. Sie lässt sich in Postman, Insomnia, Swagger UI oder jeden kompatiblen SDK-Generator importieren, um automatisch Clients in der Sprache Ihrer Wahl zu erzeugen.
Kontakt für Entwickler
Fragen zur API, Unterstützung bei der Protel-Kopplung, Anfrage zur Kontingenterhöhung: support@myprotelmod.org — bitte „API" im Betreff angeben.