zurück...

OTA_HotelResNotif

Dieser Service dient zum Abholen von Buchungen die am CapServer eingegangen sind. Es werden neue CapCorn Buchungen sowie Buchungen die auf booking.com (wenn der Kanal aktiviert ist) eingegangen sind als Ergebnis zurückgeliefert.

Notification Push

Die von CapCorn empfohlene Methode ist der sogenannte Notification Push. Um auf ihrer sowie auf unserer Seite den Traffic so gering wie möglich zu halten, haben wir uns dazu entschlossen einen Push-Notification Service anzubieten. Dieser Service ruft einen einfachen HTTP-GET Request mit den wichtigsten Informationen (Vermieternummer, Buchungs-ID und Buchungstyp) auf und stößt damit im Idealfall auf Ihrer Seite einen Service an der die neue Buchung abholt. Dazu finden Sie im CapCorn Webinterface unter dem Menüpunkt ext. Kanäle -> OTA / PMS Einstellungen folgende Einstellungsmöglichkeiten.

• Push Notifikations-URL
  Hier geben Sie jene Adresse ein wo Ihr Service zu finden ist, der auf die Push Notifikation reagiert.
• Benutzername/Passwort
  Die Eingabe eines Benutzernamen/Passwort ist optional. Wenn hier Daten hinterlegt sind, werden Sie im Zuge des HTTP-Get Request an Ihren Service zur Authentifizierung verwendet (Basic Authentication). Also sollte Ihr Service eine Authentifizierung verlangen, können Sie hier die entsprechenden Daten hinterlegen.

Der Service versendet also einen HTTP-GET Request (optional mit Authentifizierung) an die von ihnen hinterlegt Adresse. Die sieht dann zum Beispiel wie folgt aus:

In diesem Beispiel würde also ihr Service darüber informiert werden, dass für den Betrieb mit der Nummer 5900 die Reservierung mit der Nummer 123456789 vom Typ "confirmation" neu eingegangen ist.
Der Typ kann confirmation, modification bzw. cancellation sein. "Confirmation" steht für neue Buchungen. "Modification" steht für Buchungen in denen eine Änderung vorgenommen wurde (kann im Moment nur bei booking.com Buchungen der Fall sein). Und "Cancellation" steht für Stornierungen (ebenfalls nur über booking.com möglich). Der Typ spielt deswegen eine entscheidende Rolle, da neue Buchungen vom Typ "confirmation" beim Service OTA_HotelResNotif abzuholen sind. "Modification" bzw. "Cancellation" sind beim Service OTA_HotelResModifyNotif abzuholen. Mehr Infos dazu finden Sie hier.

Pull

Sollten Sie keine Möglichkeit haben den oben beschriebenen Notification Push Service zu nutzen, müssen Sie eigenständig in regelmäßigem Intervall (z.B. alle 15 min.) bei unseren Services nachfragen ob neue Buchungen, Buchungsänderungen oder Stornos eingegangen sind.

Als Antwort liefert das System ein XML Element vom Typ "OTA_HotelResNotifRQ" (mehr dazu unten). Es beinhaltet alle neuen (nicht bestätigten) Buchungen die im System eingegangen sind.

Authentifizierung

Die Authentifizierung erfolgt über die URL. Dazu ist die Hotel-Id (CapCorn Vermieternummer) und der PIN (CapCorn Master PIN) zu verwenden.

Id / LastChange Parameter

Sie können in der URL optional auch eine Buchungs-ID bzw. ein "LastChange" Datum angeben. Verwenden Sie diese optionalen Elemente nicht kombiniert! Enthält die ID eine Information (nur nummerische Werte erlaubt), so liefert der Service genau die Buchung mit der Buchungsnummer die Sie als ID angegeben haben. Diese Funktion ist beim oben beschriebenen Notification Push sinnvoll.
Der "LastChange" Parameter gibt Ihnen die Möglichkeit, dass Sie nur Buchungen ab einem gewissen Datum abholen. Bitte geben Sie das Datum im Format "yyyy-MM-dd" an.

Der Response

Als Antwort sendet der Service ein OTA_HotelResNotifRQ Element welches dem OTA Standard (www.opentravel.org) entspricht. Den grundsätzlichen Aufbau sehen Sie in der folgenden Abbildung.

Das Hauptelement ist "HotelReservations" welches als Container für 1...n "HotelReservation" Elemente dient. Jede Buchung wird also als "HotelReservation" Element dargestellt. Dieses ist wiederum in 2 Hauptbereiche, die "RoomStays" und die "ResGlobalInfo" aufgeteilt.

<RoomStays>

Wie der Name bereits erahnen lässt, werden unter dem <RoomStays> Element sämtliche Zimmer der Buchung angeführt. Jedes Zimmer wird in einem <RoomStay> Element dargestellt (siehe folgendes Beispiel).

Das Attribut "IndexNumber" dient als eindeutige Identifizierung der Zimmerreservierung in der Datenbank. Es ist im Normalfall für Sie als Konsument des Webservices nicht von Relevanz.

• RoomTypes
  RoomTypes enthält stehts 1 Element vom Typ RoomType welches anhand diverser Attribute/Elemente das Zimmer beschreibt. Das Attribut RoomType gibt an ob es sich um ein Zimmer (=1) bzw. um ein Appartement (=2) handelt. Der RoomTypeCode beschreibt die Kategorie welche im CapCorn Webinterface in den Zimmereinstellungen unter "Kategorie (Importschnittstelle)" hinterlegt ist. Die RoomID steht für die Zimmernummer des Zimmers.
  Jeder RoomType enhält auch ein RoomDescription Element. Dieses beschreibt im Attribut Name den Namen des Zimmers. Als Text wird die Beschreibung bzw. die Verpflegung des Zimmers zum Zeitpunkt der Buchung dargestellt.
• GuestCounts
  GuestCounts ist Grundlage für GuestCount Elemente, welche die gebuchte Belegung darstellen (Anzahl Erw. und Kinder inkl. deren Alter). Für Erwachsene wird ein GuestCount Element mit dem Attribut AgeQualifyingCode="10" angeführt, wobei Count die Anzahl der Erwachsenen darstellt. Für alle Kinder unterschiedlichen Alters, wird je ein GuestCount Element mit dem Attribut AgeQualifyingCode="8" angeführt. Age steht dabei für das Alter des Kindes bzw. der Kinder und Count steht für die Anzahl der Kinder in diesem Alter.
• TimeSpan
  Dieses Element beschreibt den Zeitraum der Zimmerreservierung. Unter Start wird das Datum der Anreise angegeben. Das Attribut Duration beschreibt die Anzahl der Nächtigungen.
• Total
  Total ist Basis für die Preisinformationen des Zimmers. Das Attribut AmountAfterTax gibt den Zimmergesamtpreis (inkl. aller Zu-/Abschläge) an. Wobei darauf zu achten ist, wieviele Dezimalstellen laut dem Attribut DecimalPlaces hier relevant sind. In unserem Beispiel oben wäre dies ein Zimmerpreis von € 576,-. CurrencyCode gibt die Währung an. In der Regel wird dies "EUR" sein.
• BasicPropertyInfo
  Dieses Element enthält nur das Attribut HotelCode, welches die Vermieternummer beinhaltet. Zu ihrer Kontrolle sollte dies die selbe Nummer sein die Sie in der URL als Vermieternummer angegeben haben.
• SpecialRequests
  SpecialRequests ist Basis für diverse Zu- bzw. Abschläge. Für die Zuschläge finden sie ein Element mit dem Namen additions. Das zugehörige Text Element enthält die Beschreibung aller Zuschläge in Form eines Textes. Das gleiche Prinzip gilt für diverse Abschläge welche im Element discounts beschrieben werden. Die Preisaufschläge bzw. Nachlässe sind wie oben bereits erwähnt im jeweiligen Zimmerpreis (AmountAfterTax) bereits berücksichtigt.

<ResGlobalInfo>

ResGlobalInfo ist wie oben bereist erwähnt der zweite Hauptbestandteil eines jeden HotelReservation Elements. Dem Name entsprechend enthält es allgemeine Informationen wie eine mögliche kurze Nachricht des Gastes, die Zahlungsinformationen/Kreditkarteninformationen, den Gesamtpreis, Buchungsnummer und die Daten des Gastes. Ein Beispiel sehen Sie in der folgenden Abbildung.

• Comments
  Im Rahmen des Comments Element finden Sie immer ein Element Comment welches aus einem Text Element besteht. Dieses Text Element beinhaltet evtl. eine kurze Nachricht die der Gast im Rahmen der Buchung an Sie gerichtet hat.
• Guarantee
  Dieses Element ist Rahmen für die Kreditkarteninformationen des Gastes und für mögliche Anzahlungen.
  GuaranteesAccepted -> GuaranteeAccepted -> PaymentCard stellt sämtliche Kreditkarteninformationen dar. CardCode beschreibt das Kreditkarteninstitut. ExpireDate steht für das Ablaufdatum der Karte (Format: MMyy). Das Element CardHolderName beschreibt den Namen des Kreditkarteninhabers. CardNumber -> PlainText gibt die Kreditkartennummer wieder. Der Sicherheitscode der Karte wird im Element SeriesCode -> PlainText gespeichert.
  Comments -> Comment -> Text beschreibt in Worten, ob die Kreditkarte nur zur Sicherstellung dient oder ob eventuell eine Anzahlung eingezogen werden darf (wie z.B. im Bild oben zu sehen ist).
• Total
  Nach dem selben Prinzip wie oben beim Zimmerpreis wird hier der Gesamtpreis der Buchung beschreiben.
• HotelReservationIDs
  Hier ist immer das Element HotelReservationID vorhanden. Das Attribut ResID_Type beschreibt den Kanal über den die Buchung eingegangen ist (CAPCORN bzw. BOOKING.COM). ResID_Value steht für die eindeutige Reservierungsnummer. ResID_Date beschreibt den Zeitpunkt der Buchung.
• Profiles
  Das Element ProfileInfo -> Profile -> Customer speichert die Stammdaten des Gastes. Das Attribut Gender beschreibt anhand der Werte "Male", "Female" oder "Unknown" das Geschlecht des Gastes. Das Element PersonName beschreibt anhand GivenName und Surname den Vor- und Nachnamen. Das Element Telephone enthält das Attribut PhoneNumber welche die Telefonnummer des Gastes speichert. Das Element Email enthält die Email-Adresse des Gastes.
  Sämtliche Adressinformationen werden im Element Address gespeichert. AddressLine steht für die Straße. CityName beschreibt den Ort und PostalCode die zugehörige Postleitzahl. Das Attribut Code im Element CountryCode beschreibt das Länderkürzel der Adresse.

Response bestätigen

Alle Reservierungen die neu eingehen, werden solange in einem Cache gehalten bis sie über den beschriebenen Service abgeholt werden. Um nun eine Buchung aus dem Cache zu entfernen muss der Benutzer zusätzlich zum oben beschriebenen abrufen der Reservierungsdaten auch noch die Abholung bestätigen. Dazu muss er nach dem Abruf nochmals eine Success Message in fogender Form an den Service zurückschicken.

• HTTP POST
• URL: https://mainframe.capcorn.net/OTA/OTA_HotelResNotif?hotelId={Vermieternummer}&pin={CapCorn-PIN}
• HEADER: Content-Type: application/xml
• BODY: <OTA_HotelResNotifRS ...> ... </OTA_HotelResNotifRS>

Ein Beispiel für einen Body sieht wie folgt aus:

Aufbau des Response

Wichtig ist, dass das erste Element des OTA_HotelResNotifRS ein Success Element ist. Dieses signalisiert, dass die nachfolgende(n) Reservierung(en) erfolgreich exportiert wurden.
Nach dem Success Element ist nun ein HotelReservations Element einzufügen. Dieses ist der Container für 1...n HotelReservation Elemente. Pro HotelReservation Element können Sie je eine Buchung als erfolgreich exportiert melden. Um die richtige Buchung identifizieren zu können, dienen die Attribute ResID_Value und ResID_Source in ResGlobalInfo -> HotelReservationIDs -> HotelReservationID. In ResID_Value geben Sie die Reservierungsnummer an und in ResID_Source den Buchungskanal (CAPCORN bzw. BOOKING.COM). Verwenden Sie eben die Nummer und den Kanal den Sie oben beim Abruf der Buchung als Ergebnis erhalten haben.

Alle bestätigten Buchungen können nun über den Webservice nicht mehr abgerufen werden. Sollten Sie dennoch eine Buchung erneut abrufen wollen, dann müssen Sie im CapCorn Webinterface in den Details der Buchung das Flag zum PMS Export händisch wieder auf false setzen.