zurück...
OTA_HotelRateAmountNotif_v2
Der OTA_HotelRateAmountNotif Service dient zum aktualisieren von Tagespreisen einer Kategorie. Es ist also zwingend erforderlich, dass im CapCorn
Wartungsportal Zimmerkategorien angelegt werden (siehe entsprechende
Doku des Wartungsportal). Im Idealfall sollte der Service
nur dann benutzt werden wenn sich Änderungen bei den Preisen ergeben haben (also nicht bei jeder Freimeldung). Es handelt sich um einen
Webservice der nach dem REST (Representational State Transfer) Prinzip aufgebaut ist.
Methodik
- HTTP POST
- URL: https://mainframe.capcorn.net/OTA/OTA_HotelRateAmountNotif_v2?hotelId={Vermieternummer}&pin={CapCorn-PIN}
- HEADER: Content-Type: application/xml
- BODY: <OTA_HotelRateAmountNotifRQ ...> ... </OTA_HotelRateAmountNotifRQ >
Als Antwort liefert das System ein XML Element vom Typ "OTA_HotelRateAmountNotifRS" (siehe unten).
Authentifizierung
Die Authentifizierung erfolgt über URL Parameter. Dazu ist die Hotel-Id (CapCorn Vermieternummer) und der PIN (CapCorn Master PIN) zu verwenden.
Ein Beispiel für eine URL sehen sie in der folgenden Abbildung. Sollten Sie Ihren PIN nicht mehr wissen,
gibt Ihnen Ihr Verband gerne Auskunft darüber.
Der Request
Im Body der Nachricht werden die Daten im OTA_HotelRateAmountRQ Element übermittelt. Sämtliche Daten beziehen sich natürlich
immer auf den Betrieb der in der URL zur Authentifizierung verwendet wurde. Zentrales Element des "OTA_HotelRateAmountRQ" Elements ist der
"RateAmountMessages" Container. Dieser beinhaltet sämtliche Tagespreise, welche jeweils als "RateAmountMessage" Element dargestellt
werden. Als Beispiel sehen Sie im folgenden Bild eine Meldung.
Tagespreise setzen
Eine Meldung unterteilt sich in Attribute bzw. Elemente die zwingend notwendig sind und jene die optional sind. Wichtig:
Die Tagespreismeldung ist inkrementell! Das bedeutet, dass sie nicht immer alle Preise melden müssen. Also für Zeiten die in Ihrer Meldung nicht
enthalten sind bleiben die Preise im System erhalten. Wir empfehlen also immer nur bei einer Preisänderung die entsprechende Änderung
zu übertragen.
Zwingend notwendige Elemente
-
„RateAmountMessage“:
Ist das zentrale Element, welches 1...n mal angeführt werden muss und jeweils die Tagespreisinformation
enthält. Das Attribut LocatorID ist dabei optional (siehe unten).
-
„StatusApplicationControl“:
Dieses Element gibt an für welche Zimmerkategorie (= Parameter InvTypeCode) und für welchen Zeitraum der nachstehende Tagespreis hinterlegt werden soll.
Welche Kategorie welchen InvTypeCode besitzt, definieren Sie im Webinterface in den Kategorieeinstellungen im Feld
Kategorie (Importschnittstelle) bzw. unter "Channel Manager -> Schnittstellen-Codes".
Start und End Datum müssen in der Zukunft liegen. Das Enddatum muss mindestens gleich groß bzw. größer dem Startdatum sein. Der Tag
des Enddatums wird miteinbezogen. z.B. Enddatum "2017-08-20" bedeutet, dass der Tagespreis bis inklusive der Nächtigung vom 20. August
auf den 21. August gültig ist. Das Start- bzw. Enddatum darf maximal 500 Tage in der Zukunft liegen.
Die Datumswerte müssen in folgendem Format angegeben werden: "yyyy-MM-dd" (siehe Abbildung).
-
„Rates“:
Das Rates Element ist nun Container für genau ein Rate Elemente. Das Rate Element enthält den Container
BaseByGuestAmts. Dieser Container enthält wiederum genau ein BaseByGuestAmt Element. Dieses stellt mit seinen
Parametern die Preisinformation dar.
Die Anzahl der Dezimalstellen können Sie unter DecimalPlaces fixieren. Der Preis wird dann endgültig im Parameter AmountAfterTax angeführt.
Wenn Sie ohne DecimalPlaces arbeiten, aber Kommastellen anführen möchten, achten Sie dabei darauf, dass nur 2 Dezimalstellen erlaubt sind und ein "."
(sprich Punkt) als Trennzeichen verewndet werden muss.
Wenn Sie den Preis für ein Zimmer in einer bestimmten Saison löschen wollen, dann führen Sie bei "AmountAfterTax" den Wert "0" an.
Achtung: Die Werte entsprechen immer dem Nächtigungspreis für das gesamte Zimmer. Bei der Überprüfung im Wartungsportal sehen Sie jedoch
bei Hotelzimmern den Preis pro Person pro Nacht und bei Appartements den Tagespreis für das gesamte Appartement. Bei Hotelzimmern wird bei uns intern also
ihr übertragener Wert durch die "Anzahl der Personen bei Standardbelegung" dividiert, sprich bei einem Doppelzimmer halbiert.
Optionale Elemente
-
„LocatorID“:
Die LocatorID ist ein optionales Attribut der RateAmountMessage. Es stellt eine aufsteigende Nummerierung der "RateAmountMessage"
Elemente dar. Wir empfehlen dieses Element zu verwenden, denn es dient dazu, bei Ergebnissen mit Fehlern bzw. Warnungen den Bereich
anhand dieser ID genau definieren zu können. Sie finden dann die LocatorID im Result des Webservices wieder und können so Ihre Fehler
bzw. Warnungen genau lokalisieren.
Der Response
Success
Bei fehlerfreien Meldungen sieht die Antwort des Services immer folgendermaßen aus:
Warnings
Es besteht die Möglichkeit, dass Warnungen auftreten. Dies ist zum Beispiel der Fall wenn Sie eine ungültige Zimmerkategorie angeben haben. Dabei würde dieser
Wert ignoriert werden, der Rest aber dennoch abgearbeitet werden.
Die Antwort des Services enthält zwar ein Success-Element, zusätzlich sind aber alle Warnungen angeführt die aufgetreten sind
(siehe folgende Abbildung).
Die Werte werden wie folgt interpretiert:
- ShortText
Eine kurze Beschreibung der Warnung.
- Code
Fehlercode laut opentravel.org Error-Codes.
- Status
Complete steht dafür, dass die Freimeldung abgearbeitet wurde, die Daten übernommen und an den CapServer übertragen wurden.
NotProcessed bedeutet, dass keine Änderungen vorgenommen wurden. Ist in der Regel der Fall wenn eine Übertragung
fehlerhaft ist.
- RecordID
Ist gleichzusetzen mit der LocatorID aus Ihrer Anfrage und zeigt Ihnen somit in welcher AvailSatusMessage die Warnung bzw.
der Fehler aufgetreten ist.
Errors
Es besteht die Möglichkeit, dass Fehler (Errors) auftreten. Hierfür gibt es diverse Gründe wie etwa eine falsches Datumsformat oder eine Meldung
über die 500 Tage hinaus.
Wenn ein Fehler auftritt, werden automatisch keine Änderungen übernommen!
Wie so eine Antwort aussehen kann sehen Sie in der folgenden Abbildung.
