Skip to content

OTA_HotelAvailGetRQ

Method for reading availability at room level (RoomType only) and optionally also at offer level (RoomType/RatePlan combination) from Kurzurlaub.de.

We describe the OTA_HotelAvailGetRQ Request (RQ) and Response (RS) using the example of the test hotel. The data is always queried via POST request.

Depending on the parameters sent, there are 2 variants

  1. Room-level availabilities
  2. Combined availability at room and rate plan level

See also Developer Guide - Inventory Push API

OTA_HotelAvailGetRQ - Request via POST

Endpoint for POST Request:

POST /ota/api/HotelAvailGet

Parameters used

Authentication and hotel parameters:

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

Availability parameters:

We only process the request for availability in the period

  • HotelAvailRequest@SendBookingLimit - always = 1
  • HotelAvailRequest@BookingLimitMessageType - always SetLimit

e.g.

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

A room ID and a period (date from/to) are expected as DateRange

  • DateRange@Start - Date (DateFormat YYYY-MM-DD)
  • DateRange@End - Date (DateFormat YYYY-MM-DD)
  • RoomTypeCandidate@RoomTypeCode - room ID

Optional parameters for RatePlanCandidates:

  • RatePlanCandidate@RatePlanCode - optional for offer or rate plan code
  • RatePlanCandidate@RatePlanID - optional for rate / offer ID

When using the optional parameters @RatePlanCode or @RatePlanID, the Combined room and rate level availabilities processed.

The @RatePlanCode can either be a string (BEST-BAR) or alternatively an offer ID (integer value) to be sent. The rate plan code can be stored in the Kurzurlaub.de backend of the hotelier for each offer, to map offers and rates in the OTA backend or hotel software better and more clearly.

Notice:

We process the required blocks DateRange, HotelRef, RoomTypeCandidates and possibly RatePlanCandidates

  • we ignore RestrictionStatusCandidates
  • we ignore LengthsOfStayCandidates
  • we ignore BestAvailableRateCandidate etc

Validation of incoming data

Validation of incoming parameters for date range (date from/to):

  • a valid date format (YYYY-MM-DD)
  • a valid date period (@Start - @End)
  • not in the past
  • no more than 2 years in advance
  • no more than 3 months as a continuous period

Validation of other parameters:

  • Room-ID valid and room is online/active
  • at least one offer is online
  • Room-ID and RatePlan-ID are valid in combination and offer is online / active (only for room and rate level based availabilities)

Notice:

The data sent by the OTA partner will only be accepted for rooms that are *active and online*, alternatively warnings will be sent in response.

Example for request

Example OTA_HotelAvailGetRQ Request to read availability at room level

<?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>

Example OTA_HotelAvailGetRQ Request to read room and rate level based availabilities with used attributes @RatePlanID or '@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 - Versions of Response

Normally a <Success/> and a list of AvailStatusMessages for all requested rooms in the period will be sent in response or corresponding error messages and/or warnings

Example 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>

Warnings

No warnings are currently used, but errors are always generated in response to the request

Error messages

If serious errors occur, e.g. in the authentication or validation of the data, they are sent in an OTA_ErrorRS Response with @ErrorCode and @ErrorMessage

Unless a hotel is not allowed for processing room and rate level based availability, you will get a special error message:

we ignore RatePlanID or RatePlanCode for RoomType based AvailStatusMessage

or

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

Then contact the service or connectivity team.

Here is a list of common error messages when sending availabilities

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

Example OTA_ErrorRS Response with error

<?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)"/>

Special case of an error message with wrong settings in the hotel

If a hotel uses RoomType/RatePlan-based data, these must also be queried in this way. Alternatively, an error message is output.

<?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)"/>

Example OTA_HotelAvailGetRS Response with error

Wrong room ID requested or the room is not 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>