Wer sich integrieren kann

Schritte zur Integration

Vorbereitung der Integration

1. Zugangsdaten generieren
   Für den Zugriff auf die PriceLabs Integration API (IAPI) benötigen Sie die folgenden Anmeldedaten:
   X-INTEGRATION-NAME
   X-INTEGRATION-TOKEN
   
   Füllen Sie bitte zunächst dieses Formular aus, um den Integrations-Arbeitsablauf zu starten: Integrations-Arbeitsablauf starten
   
   Sobald das Formular abgesendet wurde, wird unser Integrationen-Team Kontakt aufnehmen und Ihnen die Zugangsdaten für die PriceLabs IAPI bereitstellen.
   
   
2. API erkunden und testen
   Sobald Sie Ihre Zugangsdaten erhalten haben, empfehlen wir Ihnen, sich mithilfe der PriceLabs API-Dokumentation mit den verfügbaren Endpunkten vertraut zu machen.
   
   Die Dokumentation bietet interaktive Tools, mit denen Sie Endpunkte direkt testen und die Funktionsweise der API verstehen können.
   
   Die Basis-URL für alle API-Aufrufe finden Sie ebenfalls in der Swagger-Dokumentation.

Entwicklung und Zertifizierung

Entwicklungsphase

1. Sicherheit
   
1. PMS-Anfragen an PriceLabs: Es sind zwei Sicherheits-Header erforderlich. Der X-INTEGRATION-TOKEN wird anfangs von PriceLabs bereitgestellt und kann vom PMS über den Endpunkt /integration neu generiert werden.  Der X-INTEGRATION-NAME wird von PriceLabs vorgegeben und bleibt konstant.
   PriceLabs-Anfragen an das PMS: Folgende Komponenten werden zu zwei Signaturen zusammengeführt: eine Reihe von Headern, eine Versionsangabe und der JSON-String im Body. Diese werden mit Ihrem Integrationstoken signiert.
   
   Beispielwerte:
   ● version = "v1"
   ● headers["X-SOURCE"] = "request_source"
   ● headers["X-PL-TIMESTAMP"] = "request_timestamp"
   ● headers["X-PL-REQUESTID"] = "request_id"
   ● body = "{"test":"body"}"
   
   Im Pseudocode werden diese Beispielwerte wie folgt kombiniert:  
   ● api_token = "26eea40c-f297-4b68-aeb8-bb626fe4b5e5"
   ● header_components = "v1:request_source:request_timestamp:request_id"
   ● signed_headers = "v1." + sha256_sign(header_components, api_token)
   ● body_components = signed_headers + "{\"test\":\"body\"}"
   ● signed_body = sha256_sign(body_components, api_token)
   
   Diese werden in den folgenden Headern übermittelt:
   ● headers["X-PL-SIGNED-HEADERS"] = signed_headers
   ● headers["X-PL-SIGNED-BODY"] = signed_body
   
   Nachdem Sie die Signatur der empfangenen Daten berechnet haben, können Sie diese mit den im Request übergebenen Signatur-Headern abgleichen.
   
   Zur Überprüfung Ihrer Implementierung dienen folgende Beispiel-Signaturen:
   ● headers["X-PL-SIGNED-HEADERS"] = "v1.567425e5a91b576652d591cabea78e9e1fe017d1c67e2d812ae2859c355965ff"
   ● headers["X-PL-SIGNED-BODY"] = "5011b348ff6691bb9cbe93f85ffb836ef0e3fec45a4ce924f5940cb1aa4071b8"
   
   Die Version lässt sich im Header ermitteln, indem Sie am ersten Punkt trennen. Die Zeichenfolge vor dem Punkt entspricht der Version (im obigen signierten Header etwa v1).
   
   Hinweis: Die Funktion sha256_sign bezeichnet eine HMAC-SHA256-Signierungsoperation mit dem api_token als Schlüssel.
   
   
2. PMS-URL-Konfiguration: Das PMS muss die folgenden drei URLs einrichten, um Preisinformationen empfangen zu können. Beachten Sie bitte die verpflichtenden Endpunkte:
   
   
1. Sync-URL (erforderlich)
   
1. Dieser Endpunkt muss vom PMS erstellt und gehostet werden.
   
2. Das PMS übergibt diesen Endpunkt über den Endpunkt /integration an PriceLabs.
   
3. PriceLabs ruft diesen Endpunkt auf, um Preise und Einstellungen (beispielsweise Vorgaben zum Mindestaufenthalt) für bestehende Objekte zu übertragen, wie im Abschnitt zu den Preisfunktionen beschrieben.
   
4. Sollte die Synchronisierung fehlschlagen, versucht PriceLabs die Übertragung am selben Kalendertag bis zu 10 Mal erneut.
   
   
2. Kalender-Trigger-URL (erforderlich)
   
1. Dieser Endpunkt muss vom PMS erstellt und gehostet werden.
   
2. Das PMS übergibt diesen Endpunkt über den Endpunkt /integration an PriceLabs.
   
3. PriceLabs sendet darüber die listing_ids, für die eine vollständige Datenaktualisierung erforderlich ist.
   
4. Nach dem Auslösen muss das PMS den vollständigen Kalender mit den aktuellen Preisen und der Verfügbarkeit über den Endpunkt /calendar zurücksenden.
   
   
3. Hook-URL (erforderlich)
   
1. Dieser Endpunkt muss vom PMS erstellt und gehostet werden.
   
2. Das PMS übergibt diesen Endpunkt über den Endpunkt /integration an PriceLabs.
   
3. PriceLabs sendet hierüber stets Benachrichtigungen, etwa bei Fehlern, fehlenden Daten eines Objekts bei Synchronisierungsfehlern oder API-Timeouts. 
   
   HINWEIS: Derzeit unterstützt PriceLabs nur die Konfiguration eines einzigen Satzes von Basis-URLs pro Integration. Verwendet Ihr PMS unterschiedliche Domains oder Endpunkte je Unterkunft oder Einheit, muss im PMS ein internes Routing eingerichtet werden, das eingehende Preisübertragungen von PriceLabs an das richtige Konto weiterleitet.
   
   
3. Preisfunktionen
   
   Im Rahmen unserer Dynamic Pricing-Lösung unterstützen wir die folgenden Preisfunktionen über unsere API. Es wird dringend empfohlen, mindestens die als verpflichtend markierten Funktionen (*) zu implementieren. Sie stellen die Grundvoraussetzung für die Integration dar. Mit den weiteren Funktionen schaffen Sie eine noch leistungsfähigere Anbindung, damit Benutzer das volle Potenzial von PriceLabs ausschöpfen können.
1. Preise*: Basis-Übernachtungspreise für Objekte.
   
2. Mindestaufenthalt*: Vorgaben zum Mindestaufenthalt je Datum.
   
3. Einschränkungen für Check-in und Check-out: Regeln für zulässige An- und Abreisetage.
   
4. Preise nach Aufenthaltsdauer (LOS): Rabatte oder Aufpreise je nach Aufenthaltsdauer.
   
5. Multi-Einheit: Eine Unterkunft oder ein Objekt, das mehrere Einheiten umfasst.
   
6. Wochen- und Monatsrabatte: Nachlässe für längere Aufenthalte auf Wochen- oder Monatsbasis.
   
7. Gebühren für zusätzliche Personen und Gäste-Schwellenwert: Zusätzliche Gebühren pro Person und Nacht ab einer bestimmten Gästezahl, die über den Schwellenwert definiert wird.
   
   
4. API-Aufrufe
   
   Die Kommunikation zwischen PriceLabs und dem PMS erfolgt in beide Richtungen. Einige APIs werden von PriceLabs bereitgestellt, andere wiederum vom PMS entwickelt und gehostet. Nachfolgend finden Sie die von PriceLabs bereitgestellten API-Aufrufe. Einige davon sind obligatorisch, andere optional.
1. Integration
   
1. Endpunkt: /integration
   
2. Verpflichtend: Ja
   
3. Voraussetzung: Das PMS muss die API-Zugangsdaten von PriceLabs erhalten haben. Dies ist ein eigenständiger API-Aufruf.
   
4. Beschreibung
   
1. Über diesen Endpunkt wird die PMS-Integration aktualisiert und verwaltet. Er dient vor allem dazu, zentrale Parameter zu pflegen:
   
2. Aktualisierung von sync_url, calendar_trigger_url und hook_url
   
3. Aktualisieren des API-Tokens
   
4. Festlegen, welche Preis-Features für Benutzer freigeschaltet sind, wie Mindestaufenthalt, An- und Abreisebeschränkungen, Wochen- oder Monatsrabatte sowie Gebühren für zusätzliche Personen.
   
2. Objekte
   
1. Endpunkt: /listings
   
2. Verpflichtend: Ja
   
3. Voraussetzung:
   
1. Der Kunde erstellt oder aktualisiert Objekte und deren Attribute im PMS.
   
2. Der Kunde muss bei PriceLabs registriert sein und das PMS autorisieren, Objektattribute und Preise an PriceLabs zu übermitteln.
   
4. Beschreibung:
   
1. Um Preisempfehlungen zu erhalten, rufen Sie diesen Endpunkt für neue oder geänderte Objekte auf. Dies ist essenziell für die Aufnahme neuer Objekte in PriceLabs. Andernfalls können für diese im PMS keine Empfehlungen bereitgestellt werden.
   
2. Die bei PriceLabs registrierte E-Mail-Adresse des Kunden muss zwingend im Parameter „user_token“ dieses Requests übergeben werden. 
5. Wichtig: Jede an PriceLabs übermittelte listing_id muss im gesamten PMS eindeutig sein. Sie darf ausschließlich einem Benutzer zugewiesen sein und nicht für Unterkünfte mehrerer Benutzer wiederverwendet werden, um Konflikte zu vermeiden. Sollte die listing_id nicht eindeutig sein, hängen Sie bitte die eindeutige Benutzerkennung des Kunden an die Objekt-ID an.
   
3. Kalender
   
1. Endpunkt: /calendar
   
2. Verpflichtend: Ja
   
3. Voraussetzung: /listings
   
4. Beschreibung:
   
1. Über diesen Endpunkt wird der Kalender eines Objekts mit Tagespreisen und Verfügbarkeiten aktualisiert. Ohne diesen Aufruf kann PriceLabs keine dynamische Preisgestaltung für das jeweilige Objekt berechnen.
   
2. Für ein neu angelegtes Objekt muss der Kalender-Request Preise und Verfügbarkeiten für mindestens 730 Tage enthalten. Sobald ein vollständiger Kalender an PriceLabs übertragen wurde, genügen nachfolgende Aufrufe, um Änderungen für das gesamte Kalenderjahr oder bestimmte Datumsbereiche zu melden.
   
3. Wir empfehlen, über diese API nur die tatsächlichen Änderungen (Deltas statt des kompletten Kalenders) an Preisen und Verfügbarkeiten für den gewählten Zeitraum zu übermitteln. So bleibt PriceLabs stets auf dem aktuellen Stand.
   
4. Mindestens Preis und Verfügbarkeit müssen für jedes Datum aktualisiert werden. 
   
4. Preise abrufen
   
1. Endpunkt: /get_prices
   
2. Verpflichtend: Nein, aber empfohlen
   
3. Voraussetzung: Diese API sollte erst aufgerufen werden, nachdem PriceLabs die sync_url ausgelöst hat.
   
4. Beschreibung:
   
1. Sobald die Objekte samt Preisen und Verfügbarkeiten über /listings und /calendar eingerichtet sind, ruft PriceLabs die vom PMS hinterlegte sync_url auf, sobald neue Preise bereitstehen.
   
2. Sobald das PMS den Aufruf an die sync_url registriert, können die Preise entweder direkt aus dem Body dieses Aufrufs verarbeitet oder über /get_prices separat abgefragt werden, um die neuesten dynamischen Preise zu laden.
   
3. In der Regel erfolgt dieser Aufruf einmal täglich nach dem Auslösen der sync_url. Möchte ein Kunde neue Preise schneller veröffentlichen, kann der Aufruf auch mehrmals am Tag stattfinden.
   
4. Bitte beachten Sie: Das PMS darf keinen automatisierten Cronjob für diesen Endpunkt einrichten. Rufen Sie ihn nur nach einem Signal über die sync_url auf.
   
5. Dieser Aufruf ist optional, da die Preise bereits in der Nachricht an die sync_url enthalten sind. Das PMS kann die Daten direkt dort auslesen, wenn /get_prices nicht genutzt werden soll.
   
6. Schlägt die Übertragung an die sync_url fehl, wiederholt PriceLabs den Vorgang standardmäßig bis zu 10 Mal am selben Tag.
   
5. Reservierungen
   
1. Endpunkt: /reservations
   
2. Verpflichtend: Ja. Diese API ist die Grundlage für Portfolio Analytics für Kunden.
   
3. Voraussetzung: Das Objekt, für das Reservierungen übermittelt werden, muss in PriceLabs vollständig eingerichtet sein.
   
4. Beschreibung:
   
1. Über diesen Endpunkt werden neue Buchungen angelegt oder bestehende Reservierungen für ein Objekt aktualisiert.
   
2. Rufen Sie diesen Endpunkt auf, sobald Reservierungen neu eingehen, geändert oder storniert werden. Diese Daten fließen in das Produkt Portfolio Analytics ein, mit dem Kunden Trends analysieren und ihre Leistung mit dem Markt vergleichen.
   
3. Das Feld total_cost im Buchungs-Request muss die Gesamtsumme aller anfallenden Kosten inklusive Gebühren und Steuern enthalten.
   
4. Das Feld rental_revenue muss den reinen Übernachtungspreis ohne Nebengebühren, Steuern oder Rabatte abbilden.
   
5. Für eine präzise Belegungsberechnung müssen Kalenderblockierungen (Eigentümerzeiten, Wartungsarbeiten etc.) als Reservierung mit Kosten von 0 $ und dem Status BLOCKED übertragen werden.
   
6. Status
   
1. Endpunkt: /status
   
2. Verpflichtend: Nein
   
3. Voraussetzung: Objekte müssen in PriceLabs angelegt sein.
   
4. Beschreibung:
   
1. Über diesen Endpunkt rufen Sie den aktuellen Verarbeitungsstatus der Daten aus PriceLabs ab.
   
2. Informationen können für Reservierungen, Objekte sowie Objektkalender abgefragt werden.
   
3. Dieser Aufruf hat keine direkten Auswirkungen auf die Daten oder das Benutzererlebnis. Er hilft dem PMS jedoch bei der Datenprüfung, der Fehlerbehebung während der Entwicklung und beim Support für angebundene Benutzer.
   
7. Preispläne
   
1. Endpunkt: /rate_plans
   
2. Verpflichtend: Nein
   
3. Voraussetzung: /listings
   
4. Beschreibung:
   
1. Verfügt ein Objekt über mehrere Preispläne, können diese über diesen Endpunkt hinzugefügt oder bearbeitet werden.
   
2. Beachten Sie bitte, dass für jedes Objekt genau ein Standard-Preisplan definiert sein muss.
   
3. Nach dem Aufruf dieses Endpunkts muss zwingend /calendar aufgerufen werden, um Preise und Verfügbarkeit für den Standard-Preisplan zu aktualisieren.
   
4. Wird der Standard-Preisplan gewechselt, ist der Aufruf von /calendar für den neuen Plan ebenfalls verpflichtend.
   
   
5. Beispiel für einen Integrationsablauf
   
   Zur Veranschaulichung nutzen wir das fiktive PMS „Fancy Rentals“, das sich an PriceLabs anbindet. Sobald Fancy Rentals das Integrationstoken und den Integrationsnamen erhalten hat, können die API-Aufrufe wie im vorherigen Abschnitt beschrieben erfolgen.
   
   
1. Zuerst ruft Fancy Rentals den Endpunkt /integration auf, um die eigenen URLs zu hinterlegen (Abschnitt 5) und das Integrationstoken abzurufen. Fancy Rentals speichert das Token und kann es bei Bedarf über diesen Endpunkt erneuern. Ohne hinterlegte PMS-URLs schlagen Folgeaufrufe möglicherweise fehl. Um das Token zu erneuern, senden Sie „regenerate_token“ = true im Request an /integration.
   
2. Erstellt ein Benutzer ein neues Objekt in Fancy Rentals und pflegt Preise oder Verfügbarkeiten ein, ruft Fancy Rentals den Endpunkt /listings auf. Direkt danach folgt der Aufruf von /calendar, um Preise und Verfügbarkeiten für mindestens 12 Monate bis maximal 2 Jahre zu übertragen.
   
3. Ändert der Benutzer Preise und Verfügbarkeiten für ein Objekt in Fancy Rentals, wird /calendar aufgerufen, um diese Aktualisierungen an PriceLabs weiterzugeben.
   
4. Ruft PriceLabs die Kalender-Trigger-URL mit bestimmten Objekt-IDs auf, meldet Fancy Rentals den vollständigen Kalender mit Preisen und Verfügbarkeiten für diese Einheiten über /calendar zurück.
   
5. Nimmt der Benutzer Personalisierungen an den Preisen vor und aktiviert die Objektsynchronisierung oder startet einen manuellen Abgleich in PriceLabs, sendet PriceLabs die Objekt-IDs samt dynamischen Preisen und Einstellungen an die Sync-URL. Fancy Rentals kann diese Daten bei Bedarf auch über /get_prices abrufen.
   
6. Gehen in Fancy Rentals neue Buchungen, Änderungen oder Stornierungen ein, werden diese Buchungsdetails über /reservations an PriceLabs gemeldet. Da Buchungen und Stornierungen die Verfügbarkeit verändern, folgt darauf ein Aufruf von /calendar zur Aktualisierung von Preisen und Kalenderdaten.

Zertifizierung

1. Das PMS prüft die eigene Anbindung anhand unserer Zertifizierungs-Checkliste.
   https://docs.google.com/spreadsheets/d/1nSzDMLMneX3Byukieo9CYhbXksYIL_NfT87tmBA5aP4/edit?   usp=sharing
2.  Das PMS-Team stellt die erforderlichen technischen Angaben zur Integration sowie Marketingmaterialien bereit. Die genauen Anforderungen finden Sie in der verlinkten Checkliste.
   
3. Die Checkliste beinhaltet Testläufe zur Bestätigung, dass die API-Prozesse einwandfrei greifen.
   
1. Diese werden entweder durch PriceLabs über ein Testkonto im PMS durchgeführt ODER
   
2. in einem gemeinsamen Termin von beiden Teams gemeinsam durchlaufen.
   

Go-Live

1. Das PMS hinterlegt seine Produktions-URLs in PriceLabs: Sync-URL, Kalender-Trigger-URL und Hook-URL, und fordert das finale Integrationstoken an.
   
2. Das PMS und PriceLabs wählen gemeinsam geeignete Pilotkunden für den Start aus. Eine ausgewählte Gruppe stellt sicher, dass alle Abläufe in der Praxis fehlerfrei ineinandergreifen. PriceLabs schaltet die Schnittstelle für diese Konten frei.
   
3. Läuft die Datenübertragung bei den Pilotkunden reibungslos, wird die Integration in Abstimmung mit dem PMS für alle gemeinsamen Kunden freigegeben.
   

Nach der Integration

1. Offizielle Ankündigung der Integration über alle Marketingkanäle wie Social Media oder unsere Partnerseite.
   
2. Mögliche gemeinsame Marketingaktivitäten.