OTA_HotelAvailNotif

Der OTA_HotelAvailNotif Service dient zum aktualisieren der Verfügbarkeiten eines Betriebes. Im Idealfall sollte der Service jedes mal benutzt werden wenn sich in der Verfügbarkeit Änderungen ergeben haben. Es handelt sich um einen Webservice der nach dem REST (Representational State Transfer) Prinzip aufgebaut ist.

Methodik

Als Antwort liefert das System ein XML Element vom Typ "OTA_HotelAvailNotifRS" (siehe unten).

Authentifizierung

Die Authentifizierung erfolgt über die URL. Dazu ist die Hotel-Id (CapCorn Vermieternummer) und der PIN (CapCorn Master PIN) zu verwenden. Ein Beispiel für eine URL sehen Sie im Folgenden. 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_HotelAvailNotifRQ Element übermittelt. Sämtliche Freimeldungsdaten beziehen sich natürlich immer auf den Betrieb der in der URL zur Authentifizierung verwendet wurde. Zentrales Element des "OTA_HotelAvailNotifRQ" Elements ist der "AvailStatusMessages" Container. Dieser beinhaltet sämtliche Freimeldungen, welche jeweils als "AvailStatusMessage" Element dargestellt werden. Hierbei werden zwei Arten der Freimeldung unterschieden. Zum einen die Freimeldung nach Kategorien und zum anderen jene die direkt an ein Zimmer gebunden sind.

<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2005-08-01T09:30:47-05:00">
    <AvailStatusMessages>
        <AvailStatusMessage LocatorID="1">
            <StatusApplicationControl Start="2014-12-08" End="2014-12-15" InvCode="101" />
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="SetMinLOS" Time="3" />
            </LengthsOfStay>
            <RestrictionStatus Restriction="Departure" Status="Close" />
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Freimeldung nach Kategorien

Grundsätzlich wird bei dieser Methode eine bestimmte Kategorie (InvTypeCode) für einen bestimmten Zeitraum (Start, End) angesprochen. Sollten Sie zum Beispiel drei von fünf Zimmern einer Kategorie für einen Zeitraum freimelden, werden für diesen Zeitraum die übrigen zwei Zimmer automatisch auf belegt gesetzt. Da CapCorn nicht nach Kategorien arbeitet sondern die Granularität viel feiner ist und auf Zimmerebene geht, werden die Zimmer immer in der Reihenfolge der Sortierung im CapCorn Webinterface ausgewählt. Es ist daher nicht zu empfehlen, dass Sie die Sortierung ändern wenn Sie bereits Daten importiert haben. Legen Sie die von Ihnen gewünschte Sortierung fest bevor Sie mit der Wartung über die OTA Schnittstelle beginnen.

Ein Beispiel für eine Freimeldung nach Kategorien sehen Sie im folgenden Ausschnitt. Die Erklärung zu den diversen Elementen finden Sie unterhalb des Ausschnitts. Es gibt dabei eine Unterteilung in Attribute bzw. Elemente die zwingend notwendig sind und jene die optional sind.

<AvailStatusMessage BookingLimit="5" LocatorID="1">
    <StatusApplicationControl Start="2014-12-08" End="2014-12-15" InvTypeCode="DZ" />
    <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="SetMinLOS" Time="3" />
    </LengthsOfStay>
    <RestrictionStatus Status="Open" />
</AvailStatusMessage>

Zwingend notwendige Elemente

• AvailStatusMessage
  Ist das zentrale Element, welches 1...n mal angeführt werden muss und jeweils die Daten der Freimeldung enthält. Das Attribut BookingLimit ist dabei optional und beschreibt die Anzahl der verfügbaren Zimmer. Es sind nur positive ganze Zahlen (inkl. 0) erlaubt. Ist das Element BookingLimit nicht angeführt sprechen Sie automatisch alle Zimmer der Kategorie an. Bei bookingLimit = 0 werden automatisch alle Zimmer auf belegt gesetzt.
• StatusApplicationControl
  Dieses Element beinhaltet nun die Informationen auf welchen Zeitraum und auf welche Kategorie sich die Freimeldung bezieht. Der Zeitraum wird anhand der Elemente "Start" und "End" definiert. Das Enddatum wird in die Freimeldung miteinbezogen. Zum Beispiel End="2014-12-15" bedeutet, dass die Freimeldung bis inklusive der Übernachtung von 15.Dezember 2014 auf den 16.Dezember 2014 gilt. Das Datum muss in folgendem Format angegeben werden: "yyyy-MM-dd" (siehe oben). Maximal 749 Tage in die Zukunft. Ein Datum in der Vergangenheit ist ebenfalls nicht erlaubt.
  Als drittes zwingendes Attribut muss "InvTypeCode" angeführt werden. Hier ist die Kategorie anzugeben welche aktualisiert werden soll. Welches Zimmer zu welcher Kategorie gehört definieren Sie in den jeweiligen Kategorie-Einstellungen im CapCorn Webinterface oder in der Schnittstellen-Codes Übersicht. Diese finden Sie unter im Webinterface unter "Channel Manager" -> "Schnittstellen-Codes". Wichtig: Für Zeiträume in denen ihr Betrieb im CapCorn Webinterface auf geschlossen gesetzt ist, werden die Verfügbarkeiten ignoriert! Der Betrieb bzw. das Zimmer bleibt geschlossen!

Optionale Elemente

• LocatorID
  Die LocatorID ist ein optionales Attribut der AvailStatusMessage. Es stellt eine aufsteigende Nummerierung der "AvailStatusMessage" 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 leichter lokalisieren.
• LengthsOfStay
  Gilt als Container für "LengthOfStay" Elemente. Möchte man eine Mindestaufenthaltsdauer definieren, bedient man sich diesem Element. Wenn man ein "LengthOfStay" Element anführt, dann verlangt es zwei zwingend notwendige Attribute. Zum einen das Attribut "Time", welches einen positiven ganzen Wert größer 1 beinhalten sollte. Es entspricht nämlich der Anzahl der Nächte die ein Gast mindestens bleiben muss um überhaupt buchen zu können. Als "MinMaxMessageType" ist stets "SetMinLOS" (set minimum length of stay) anzugeben.
• RestrictionStatus
  Wie die Bezeichnung verrät dient der RestrictionStatus dazu um Restriktionen festzulegen bzw. um eine Kategorie zu sperren. Das Attribut Status ist dabei ein zwingend notwendiges und kann die Werte "Close" bzw. "Open" annehmen. Ist nur dieses Element angeführt kann man die Kategorie bzw. ein Zimmer für Buchungen sperren (Close) oder für Buchungen freigeben (Open). Wenn in einer "AvailStatusMessage" kein "RestrictionStatus" angegeben ist wird der Status "Open" als default angenommen.Achtung: Zimmer sperren ("Close") funktioniert bei der Freimeldung nach Kategorien immer nur für die gesamte Kategorie im angegebenen Zeitraum. Also einen Teil der Zimmer zu sperren macht keinen Sinn, melden Sie stattdessen wie viele Zimmer verfügbar sind. Führen Sie Status="Close" an um das Zimmer zu sperren, dann wird natürlich auch jegliche LengthOfStay Einstellung ignoriert. Zimmer/Kategorie sperren hat die höchste Priorität.
  Als zweites optionales Attribut gibt es noch "Restriction". Diese Attribut kann die Werte "Arrival", "Departure" oder "ArrivalAndDeparture" annehmen und dient in Kombination mit dem Attribut "Status" zum sperren der Anreise bzw. der Abreise. Zur Verdeutlichung folgen nun sämtlich Möglichkeiten die Ihnen der "RestrictionStatus" bietet.

  1. Normale Freigabe für Buchungen (muss nicht zwingend angeführt werden)

     <RestrictionStatus Status="Open" />

  2. Zimmer / Kategorie sperren (sperrt immer gesamte Kategorie -> BookingLimit wird ignoriert)

     <RestrictionStatus Status="Close" />

  3. Keine Anreise erlauben

     <RestrictionStatus Restriction="Arrival" Status="Close" />

  4. Keine Abreise erlauben

     <RestrictionStatus Restriction="Departure" Status="Close" />

  5. Keine An- und Abreise erlauben

     <RestrictionStatus Restriction="ArrivalAndDeparture" Status="Close" />

  Wichtig: Wenn der Mindestaufenthalt nicht explizit angegeben wird, bleibt der Wert der hinterlegt ist unverändert.
  Möchten Sie An- und Abreisesperren ebenfalls immer beibehalten bzw. im System manuell warten, dann müssen
  Sie diese Option vom CapCorn-Support Team aktivieren lassen (bei Sytemen die An-/Abreisesperren nicht übertragen
  ist dies hilfreich).

Freimeldung nach Zimmernummer

Ein Beispiel für eine Freimeldung nach Zimmernummern sehen Sie im folgenden Ausschnitt.

<AvailStatusMessage LocatorID="1">
    <StatusApplicationControl Start="2014-12-08" End="2014-12-15" InvCode="109" />
    <LengthsOfStay>
        <LengthOfStay MinMaxMessageType="SetMinLOS" Time="3" />
    </LengthsOfStay>
    <RestrictionStatus Restriction="Departure" Status="Close" />
</AvailStatusMessage>

Es gilt grundsätzlich das selbe Prinzip wie oben beschrieben für die Freimeldung nach Kategorien. In zwei Punkten gibt es jedoch einen entscheidenden Unterschied:

1. BookingLimit
   Das Element BookingLimit darf nicht mehr angeführt werden. Bei der Freimeldung nach Zimmer bezieht sich jede "AvailStatusMessage" auf ein spezielles Zimmer. Eine Mengenangabe ist somit sinnlos.
2. InvCode statt InvTypeCode
   Im Element "StatusApplicationControl" entfällt das Attribut "InvTypeCode" und wird durch das Attribut "InvCode" ersetzt. Hier muss jene Zimmernummer angeführt werden, welche im CapServer Webinterface in den Zimmereinstellungen hinterlegt ist bzw. die Sie in der Schnittstellen-Codes Übersicht vorfinden (siehe Webinterface unter "Channel Manager" -> "Schnittstellen-Codes").

Der Response

Success

Bei fehlerfreien Meldungen sieht die Antwort des Services immer folgendermaßen aus:

<OTA_HotelAvailNotifRS Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <Success />
</OTA_HotelAvailNotifRS>

Warnings

Es besteht die Möglichkeit, dass Warnungen auftreten. Dies ist zum Beispiel der Fall wenn Sie in Ihrer Freimeldung nach Kategorien in der Variable BookingLimit mehr Zimmer angeben als eigentlich im System angelegt sind. Die Antwort des Services enthält zwar ein Success-Element, zusätzlich sind aber alle Warnungen angeführt die aufgetreten sind (siehe folgendes Beispiel).

<OTA_HotelAvailNotifRS Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <Success />
    <Warnings>
        <Warning ShortText="Too many rooms/units, only 3 matching rooms found on CapServer!" Code="106" Status="Complete" RecordID="13" />
        <Warning ShortText="Too many rooms/units, only 2 matching rooms found on CapServer!" Code="106" Status="Complete" RecordID="21" />
    </Warnings>
</OTA_HotelAvailNotifRS>

Die Werte werden wie folgt interpretiert:

1. ShortText
   Eine kurze Beschreibung der Warnung.
2. Code
   Fehlercode laut opentravel.org Error-Codes.
3. 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 Anfrage fehlerhaft ist.
4. 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 viele mögliche Gründe wie etwa ein falsches Datum, eine falsche Kategorie, falsche Zimmernummer usw. Wenn ein Fehler auftritt, werden automatisch keine Änderungen übernommen! Wie so eine Antwort aussehen kann sehen Sie im folgenden Beispiel.

<OTA_HotelAvailNotifRS Version="1.0" xmlns="http://www.opentravel.org/OTA/2003/05"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <Errors>
        <Error ShortText="No match found with InvTypeCode EZ." Code="425" Status="NotProcessed" RecordID="21" />
    </Errors>
</OTA_HotelAvailNotifRS>