Zum Inhalt

OTA_HotelAvailNotifRQ

Methode zum Senden von Verfügbarkeiten auf Zimmerebene (RoomType only) und optional auch auf Angebotsebene (RoomType/RatePlan Kombination) an Kurzurlaub.de.

Wir beschreiben den OTA_HotelAvailNotifRQ Request (RQ) und Response (RS) am Beispiel des Testhotels. Das Senden der Daten erfolgt immer per POST Request.

Je nach gesendeten Parametern gibt es 2 Varianten

  1. Verfügbarkeiten auf Zimmerebene
  2. Verfügbarkeiten auf Zimmer- und Angebotsebene in Kombination

Siehe auch Entwicklerhandbuch - Verfügbarkeiten Push API

OTA_HotelAvailNotifRQ - Anfrage per POST

Endpunkt für POST Request:

POST /ota/api/HotelAvailNotif

Verwendete Parameter

Parameter für Authentifizierung und Hotel:

  • @AgentDutyCode - Agent-ID: 1 (optional)
  • RequestorID@ID - Hotel-ID: 4
  • AvailStatusMessages@HotelCode - Hotel-ID: 4

Parameter für Verfügbarkeiten:

Erwartet wird eine Zimmer-ID und ein Zeitraum (Datum von/bis) als AvailStatusMessage

  • @Start - Datum (DateFormat YYYY-MM-DD)
  • @End - Datum (DateFormat YYYY-MM-DD)

  • @InvTypeCode - Zimmer-ID oder alternativ auch @InvCode möglich

  • @BookingLimit - Anzahl freier Zimmer (Wert >= 0)

Optionale Parameter:

  • @RatePlanCode - optional für Angebots-Code
  • @RatePlanID - optional für Angebots-ID

Optionale Parameter für Buchungsregeln / Restriktionen

  • RestrictionStatus@Status - mögliche Werte: Open / Close
  • LengthOfStay@MinMaxMessageType - mögliche Werte: SetMinLOS / SetMaxLOS

Bei Verwendung der optionalen Parameter @RatePlanCode oder @RatePlanID werden die Verfügbarkeiten auf Zimmer- und Angebotsebene in Kombination verarbeitet.

Als @RatePlanCode kann entweder ein String (BEST-BAR) oder alternativ auch eine Angebots-ID (Integer Wert) gesendet werden. Der Raten-Code kann im Kurzurlaub.de Backend der Hoteliers je Angebot hinterlegt werden, um Angebote und Raten im OTA Backend oder Hotel Software besser und übersichtlicher zu mappen.

Hinweis: - wir ignorieren BestAvailableRates - wir ignorieren normalerweise LengthOfStay können es aber auf Wunsch verarbeiten - bspw. <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/> - wir verarbeiten das Attribut Restriction im RestrictionStatus mit Open / Close bspw. - Master <RestrictionStatus Status="Close"/> oder <RestrictionStatus Status="Open"/> - Close to arrival - CTA <RestrictionStatus Status="Close" Restriction="Arrival"/> - Close to departure - CTD <RestrictionStatus Status="Close" Restriction="Departure"/>

Validierung eingehender Daten

Validierung der eingehenden Parameter für Datumsbereich (Datum von/bis):

  • eine gültige DatumsPeriode (@Start - @End)
  • ein gültiges DatumsFormat (YYYY-MM-DD)
  • nicht in der Vergangenheit
  • nicht mehr als 2 Jahre im Vorraus
  • nicht mehr als 3 Monate als zusammenhängender Zeitraum

Validierung sonstiger Parameter:

  • nicht mehr als 4000 Zeilen pro Anfrage
  • BookingLimit - Anzahl freier Zimmer als integer >= 0
  • Zimmer-ID gültig und Zimmer ist online / aktiv
  • Zimmer-ID und Angebots-ID in Kombination gültig und Angebot ist online / aktiv (nur bei Verfügbarkeiten auf Zimmerebene und Angebotsebene)

Hinweis:

Die vom OTA-Partner gesendeten Daten werden nur für Zimmer akzeptiert, die *aktiv und online* sind, alternativ werden Warnungen als Antwort gesendet.

Generell werden Zeilen mit Verfügbarkeiten einzeln betrachtet, d.h. ein Fehler im InvTypeCode oder im Datumsformat, Datumsbreich wird nur für diese eine Zeile als Warnung gesendet. Alle weiteren Zeilen werden unabhängig davon bearbeitet.

Jede Nachricht enthält bspw. ein oder mehrere StatusApplicationControl-Elemente für ein oder mehrere Zimmer eines Hotels (RequestorID@ID).

Beispiel für Anfrage

Beispiel OTA_HotelAvailNotifRQ Request zum Senden von Verfügbarkeiten auf Zimmerebene

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" 
                       EchoToken="e29df571-e436-4d8f-a2e6-bb874b54051f" 
                       TimeStamp="2021-07-21T13:17:00+00:00" Version="1.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID Type="1" ID="4"/>
        </Source>
    </POS>
    <AvailStatusMessages HotelCode="4">
        <AvailStatusMessage BookingLimit="10">
            <StatusApplicationControl InvTypeCode="5306" Start="2024-01-01" End="2024-01-31" />
            <RestrictionStatus Status="Open"/>
        </AvailStatusMessage>
        <AvailStatusMessage BookingLimit="0">
            <StatusApplicationControl InvCode="5306" Start="2022-10-01" End="2022-10-03" />
            <RestrictionStatus Status="Close"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Beispiel OTA_HotelAvailNotifRQ Request zum Senden von Verfügbarkeiten auf Zimmer- und Angebotsebene mit verwendeten Attributen @RatePlanID oder '@RatePlanCode'

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="e29df571-e436-4d8f-a2e6-bb874b54051f" TimeStamp="2021-07-21T13:17:00+00:00" Version="1.0">
    <POS>
        <Source>
            <RequestorID Type="1" ID="4"/>
        </Source>
    </POS>
    <AvailStatusMessages HotelCode="4">
        <AvailStatusMessage BookingLimit="2">
            <StatusApplicationControl InvTypeCode="5306" Start="2024-01-21" End="2024-01-24" RatePlanID="20540"/>
            <RestrictionStatus Status="Open"/>
        </AvailStatusMessage>
        <AvailStatusMessage BookingLimit="2">
            <StatusApplicationControl InvCode="5306" Start="2022-10-01" End="2022-10-03" RatePlanCode="20540"/>
            <RestrictionStatus Status="Open"/>
        </AvailStatusMessage>
        <AvailStatusMessage BookingLimit="0">
            <StatusApplicationControl InvCode="5306" Start="2022-10-10" End="2022-10-11" RatePlanCode="BEST-BAR"/>
            <RestrictionStatus Status="Close"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

Beispiel für Anfrage mit optionalem RestrictionStatus

Beispiel OTA_HotelAvailNotifRQ Request zum Senden von Buchungsgregeln / Restriktionen

  1. Wenn Zimmer verfügbar sind (BookingLimit="10"), wird normalerweise ein RestrictionStatus mit Master Open gesendet (<RestrictionStatus Status="Open"/>)
  2. Wenn Zimmer nicht verfügbar sind (BookingLimit="0"), wird normalerweise ein RestrictionStatus mit Master Close gesendet (<RestrictionStatus Status="Close"/>)
  3. LengthOfStay (SetMinLOS oder SetMaxLOS) kann optional gesendert werden
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" 
                       EchoToken="e29df571-e436-4d8f-a2e6-bb874b54051f" 
                       TimeStamp="2021-07-21T13:17:00+00:00" Version="1.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID Type="1" ID="4"/>
        </Source>
    </POS>
    <AvailStatusMessages HotelCode="4">
        <AvailStatusMessage BookingLimit="10">
            <StatusApplicationControl InvTypeCode="5306" Start="2024-01-01" End="2024-01-31" />
            <!-- Master open -->
            <RestrictionStatus Status="Open"/>
        </AvailStatusMessage>
        <AvailStatusMessage BookingLimit="0">
            <StatusApplicationControl InvCode="5306" Start="2024-10-01" End="2024-10-03" />
            <!-- Master close -->
            <RestrictionStatus Status="Close"/>
        </AvailStatusMessage>
        <AvailStatusMessage>
          <StatusApplicationControl InvCode="5306" Start="2024-10-01" End="2024-10-03" />
          <RestrictionStatus Restriction="Arrival" Status="Close"/>
          <RestrictionStatus Restriction="Departure" Status="Open"/>
          <!-- optional -->
          <LengthsOfStay>
            <LengthOfStay MinMaxMessageType="SetMinLOS" Time="1"/>
            <LengthOfStay MinMaxMessageType="SetMaxLOS" Time="7"/>
          </LengthsOfStay>
        </AvailStatusMessage>
        <AvailStatusMessage BookingLimit="2">
          <StatusApplicationControl InvCode="5306" Start="2024-10-01" End="2024-10-03" />
          <RestrictionStatus Restriction="Arrival" Status="Open"/>
          <RestrictionStatus Status="Open"/>
        </AvailStatusMessage>
      </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>

OTA_HotelAvailNotifRS - Versionen der Response

Normalerweise wird ein <Success/> als Antwort gesendet oder entsprechende Fehlermeldungen und / oder Warnungen

Beispiel OTA_HotelAvailNotifRS Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       EchoToken="b1e1a4a5cf11520d81fc9edbe781ba12" PrimaryLangID="de"
                       TimeStamp="2022-03-08T16:34:10+01:00" Target="Production" Version="2.01">
    <Success/>
</OTA_HotelAvailNotifRS>

Warnungen

Jede gesendete Zeile mit Verfügbarkeiten wird einzeln betrachtet und verarbeitet, daher werden Fehler in der Validierung von Parametern nur für diese eine Zeile als Warnung gesendet. (Siehe auch Liste gängiger Fehlermeldungen)

Alle weiteren Zeilen werden unabhängig davon bearbeitet.

Für jede Warnung werden die benutzten Attribute zur Kontrolle mit ausgegeben.

Sofern Warnungen vorhanden sind, wird die Anzahl der erfolgreich verarbeiteten Zeilen am Ende als separater Hinweis mit gesendet. bspw.

1 of 3 incoming AvailStatusMessage processed. See warnings before

Beispiel OTA_HotelAvailNotifRS Response mit Warnungen

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          EchoToken="fa9c12edfe5baba3b98deac1138ed5b2" PrimaryLangID="de"
                          TimeStamp="2022-03-08T15:48:27+01:00" Target="Production" Version="2.01">
    <Warnings>
        <Warning Code="240" Type="1">Invalid start date (2022-01-01) is in past</Warning>
        <Warning Code="120" Type="1">AvailStatusMessage validation failed - used attributes (BookingLimit: 5, Start:
            2022-01-01, End: 2022-02-01, InvTypeCode: 2625, RatePlanCode: n/a, RatePlanID: 0)
        </Warning>
        <Warning Code="240" Type="1">Invalid date period (2024-04-01 - 2024-05-01) range is to large (max +12 months)
        </Warning>
        <Warning Code="120" Type="1">AvailStatusMessage validation failed - used attributes (BookingLimit: 5, Start:
            2022-04-01, End: 2023-05-01, InvTypeCode: 2625, RatePlanCode: n/a, RatePlanID: 0)
        </Warning>
        <Warning Code="500" Type="1">1 of 3 incoming AvailStatusMessage processed. See warnings before</Warning>
    </Warnings>
</OTA_HotelAvailNotifRS>

Fehlermeldungen

Wenn schwere Fehler bspw. in der Authentifizierung oder Validierung der Daten auftreten, senden wird diese in einer OTA_ErrorRS Response mit @ErrorCode und @ErrorMessage

Sofern eine Hotel nicht für die Verarbeitung von Verfügbarkeiten auf Zimmer- und Angebotsebene freigeschaltet ist, erhalten Sie eine besondere Fehlermeldung:

we ignore RatePlanID or RatePlanCode for RoomType based AvailStatusMessage

Wenden Sie sich dann an das Service oder Connectivity Team.

Hier eine Liste gängiger Fehlermeldungen beim Senden von Verfügbarkeiten

ErrorCode ErrorMessage
120 we ignore RatePlanID or RatePlanCode for RoomType based AvailStatusMessage
210 HotelNotLinked - Hotel linked to another channel manager
211 HotelNotActivated - Hotel not found
104 InternalError - Empty HotelCode (HotelId) in accepted params (agentdutycode, hotelcode, ...)
220 RoomMappingError - Hotel does not have rooms created or configured
221 RoomMappingError - Hotel does not have rates created or configured
230 RoomMappingError - Invalid room code
231 RoomMappingError - Invalid room quantity
232 RoomMappingError - Invalid rate code (bei Room/Rate Kombinationen)
240 DateRangeError - Invalid date range

Beispiel OTA_ErrorRS Response mit Fehler

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ErrorRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             EchoToken="968209e6b51ffeba7b2953801c4c8fce" PrimaryLangID="de" TimeStamp="2022-03-08T15:57:43+01:00"
             Target="Production" Version="1.000" 
             ErrorCode="211"
             ErrorMessage="HotelNotActivated - Hotel not found (HotelCode 1234 / AgentDutyCode 1)"/>

Beispiel OTA_HotelAvailNotifRS Response mit Fehler

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                       EchoToken="08b99bdc46a0ee67b620ecf88a1f30ac" PrimaryLangID="de" 
                       TimeStamp="2022-03-09T10:46:12+01:00" Target="Production" Version="2.01">
    <Errors>
        <Error Code="120" Type="1">StatusApplicationControl (InvCode="5306" Start="2022-10-01" End="2022-10-03") cannot
            processed. we ignore RatePlanID or RatePlanCode (20540) for RoomType based AvailStatusMessage
        </Error>
    </Errors>
</OTA_HotelAvailNotifRS>