Zum Inhalt

OTA_HotelAvailGetRQ

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

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

Je nach gesendeten Parametern gibt es 2 unterstützte Varianten

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

Siehe auch Entwicklerhandbuch - Verfügbarkeiten Push API

OTA_HotelAvailGetRQ - Anfrage per POST

Endpunkt für POST Request:

POST /ota/api/HotelAvailGet

Verwendete Parameter

Parameter für Authentifizierung und Hotel:

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

Parameter für Verfügbarkeiten:

Wir verarbeiten die nur Anfrage zu Verfügbarkeiten im Zeitraum

  • HotelAvailRequest@SendBookingLimit - immer = 1
  • HotelAvailRequest@BookingLimitMessageType - immer Wert SetLimit

bspw.

<HotelAvailRequest SendBookingLimit="1" BookingLimitMessageType="SetLimit">

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

  • DateRange@Start - Datum (DateFormat YYYY-MM-DD)
  • DateRange@End - Datum (DateFormat YYYY-MM-DD)
  • RoomTypeCandidate@RoomTypeCode - Zimmer-ID

Optionale Parameter für RatePlanCandidates:

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

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 verarbeiten die erforderlichen Blöcke DateRange, HotelRef, RoomTypeCandidates und ggf. RatePlanCandidates

  • wir ignorieren RestrictionStatusCandidates
  • wir ignorieren LengthsOfStayCandidates
  • wir ignorieren BestAvailableRateCandidate usw.

Validierung eingehender Daten

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

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

Validierung sonstiger Parameter:

  • Zimmer-ID gültig und Zimmer ist online / aktiv
  • mindestens ein Angebot ist online
  • Zimmer-ID und Angebots-ID in Kombination gültig und das 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 oder Fehler als Antwort gesendet.

Beispiel für Anfrage

Beispiel OTA_HotelAvailGetRQ Request zum Abfragen von Verfügbarkeiten auf Zimmerebene für 3 ZimmerTypen

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailGetRQ 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>
    <HotelAvailRequests>
      <HotelAvailRequest SendBookingLimit="1" BookingLimitMessageType="SetLimit">
        <HotelRef HotelCode="4"/>
        <DateRange Start="2022-05-01" End="2022-05-31"/>
        <RoomTypeCandidates>
          <RoomTypeCandidate RoomTypeCode="2625"/>
          <RoomTypeCandidate RoomTypeCode="9143"/>
          <RoomTypeCandidate RoomTypeCode="5306"/>
        </RoomTypeCandidates>        
      </HotelAvailRequest>
    </HotelAvailRequests>
</OTA_HotelAvailGetRQ>
Beispiel OTA_HotelAvailGetRQ Request zum Abfrage von Verfügbarkeiten auf Zimmer- und Angebotsebene mit verwendeten Attributen @RatePlanID oder @RatePlanCode

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailGetRQ 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>
  <HotelAvailRequests>
    <HotelAvailRequest SendBookingLimit="1" BookingLimitMessageType="SetLimit">
      <HotelRef HotelCode="4"/>
      <DateRange Start="2022-05-01" End="2022-05-31"/>
      <RoomTypeCandidates>
        <RoomTypeCandidate RoomTypeCode="2625"/>
        <RoomTypeCandidate RoomTypeCode="9143"/>
        <RoomTypeCandidate RoomTypeCode="5306"/>
      </RoomTypeCandidates>
      <RatePlanCandidates>
        <RatePlanCandidate RatePlanCode="20540" />
      </RatePlanCandidates>
    </HotelAvailRequest>
  </HotelAvailRequests>
</OTA_HotelAvailGetRQ>

OTA_HotelAvailGetRS - Versionen der Response

Normalerweise wird ein <Success/> und eine Liste der AvailStatusMessages für alle angefragten Zimmer im Zeitraum als Antwort gesendet oder entsprechende Fehlermeldungen und / oder Warnungen

Beispiel OTA_HotelAvailGetRS Response

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailGetRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     EchoToken="1df535f9bdcbe483d243d4cbfc890faa" PrimaryLangID="de"
                     TimeStamp="2022-04-28T14:38:03+02:00" Target="Production" Version="2.01">
  <Success/>
  <AvailStatusMessages HotelCode="4">
    <AvailStatusMessage BookingLimit="0" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-01" End="2022-05-02" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="10" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-03" End="2022-05-09" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="8" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-10" End="2022-05-15" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="10" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-16" End="2022-05-27" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="5" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-28" End="2022-05-28" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="10" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-29" End="2022-05-31" InvCode="2625"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="2" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-01" End="2022-05-31" InvCode="9143"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="0" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-01" End="2022-05-01" InvCode="5306"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="3" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-02" End="2022-05-02" InvCode="5306"/>
    </AvailStatusMessage>
    <AvailStatusMessage BookingLimit="4" BookingLimitMessageType="SetLimit">
      <StatusApplicationControl Start="2022-05-03" End="2022-05-31" InvCode="5306"/>
    </AvailStatusMessage>
  </AvailStatusMessages>
</OTA_HotelAvailGetRS>

Warnungen

Aktuell werden keine Warnungen verwendet, sondern immer Fehler als Antwort auf den Request erzeugt

Fehlermeldungen

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

Sofern ein 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

oder

HotelAvailGetRS cannot processed. Hotel is using RoomType/RatePlan based AvailStatusMessage

Wenden Sie sich dann an das Service oder Connectivity Team von Kurzurlaub.de

Hier eine Liste gängiger Fehlermeldungen beim Abfragen 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 schwerem 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)"/>

Sonderfall einer Fehlermeldung bei falschen Settings im Hotel

Sofern ein Hotel RoomType/RatePlan basierte Daten verwendet, müssen diese auch so abgefragt werden. Alternativ wird eine Fehlermeldung ausgegeben.

<?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="f69731819d6c0899ef49fdac499a5c22" PrimaryLangID="de" TimeStamp="2022-04-28T14:18:03+02:00" 
             Target="Production" Version="1.000" 
             ErrorCode="550" 
             ErrorMessage="CustomError - HotelAvailGetRS cannot processed. Hotel is using RoomType/RatePlan based AvailStatusMessage)"/>

Beispiel OTA_HotelAvailGetRS Response mit Fehler

falsche Zimmer-ID angefragt oder das Zimmer ist nicht online

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelAvailGetRS 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="230" Type="2">Invalid requested RoomId (6736)</Error>
  </Errors>
</OTA_HotelAvailGetRS>