Skip to content

OTA_HotelAvailNotifRQ

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

We describe the OTA_HotelAvailNotifRQ Request (RQ) and Response (RS) using the example of the test hotel. The data is always sent 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_HotelAvailNotifRQ - Request via POST

Endpoint for POST Request:

POST /ota/api/HotelAvailNotif

Parameters used

Authentication and hotel parameters:

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

Availability parameters:

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

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

  • @InvTypeCode - room ID or alternatively @InvCode possible

  • @BookingLimit - number of free rooms (value >= 0)

Optional parameters:

  • @RatePlanCode - optional for offer or rate plan code

  • @RatePlanID - optional for rate / offer ID

  • @RatePlanCode - optional für Angebots-Code

  • @RatePlanID - optional für Angebots-ID

Optional parameters for booking rules/restrictions

  • RestrictionStatus@Status - possible values: Open / Close
  • LengthOfStay@MinMaxMessageType - possible values: SetMinLOS / SetMaxLOS

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 ignore BestAvailableRates - we normally ignore LengthOfStay but can process it if desired - Example <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/> - we process the attribute Restriction in RestrictionStatus with Open / Close e.g. - 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"/>

Validation of incoming data

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

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

Validation of other parameters:

  • no more than 4000 lines per request
  • BookingLimit - number of free rooms as integer >= 0
  • Room-ID valid and room is online/active
  • 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.

In general, lines with availability are considered individually, i.e. an error in the InvTypeCode or in the date format, date range is only sent as a warning for this one line. All other lines are processed independently.

For example, each message contains one or more StatusApplicationControl elements for one or more rooms of a hotel (RequestorID@ID).

Example for request

Example OTA_HotelAvailNotifRQ Request to send availability at room level

<?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="2023-01-01" End="2023-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>

Example OTA_HotelAvailNotifRQ Request to send room and rate level based availabilities with used attributes @RatePlanID or '@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="2023-01-21" End="2023-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>

Example of request with optional RestrictionStatus

Example OTA_HotelAvailNotifRQ Request to send booking rules and RestrictionStatus

  1. If rooms are available (BookingLimit="10"), a RestrictionStatus with master Open is usually sent (<RestrictionStatus Status="Open"/>)
  2. If rooms are not available (BookingLimit="0"), a RestrictionStatus with master Close is usually sent (<RestrictionStatus Status="Close"/>)
  3. LengthOfStay (SetMinLOS or SetMaxLOS) can be sent optionally
<?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 - Versions of Response

Usually a <Success/> is sent in response or appropriate error messages and/or warnings

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

Warnings

Each line sent with availabilities is viewed and processed individually, therefore errors in the validation of parameters are only sent as a warning for this one line. (See also list of common error messages)

All other lines are processed independently.

The attributes used for checking are also output for each warning.

If there are warnings, the number of successfully processed lines is sent at the end as a separate notice. e.g.

1 of 3 incoming AvailStatusMessage processed. See warnings before

Example OTA_HotelAvailNotifRS Response with warnings

<?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 (2022-04-01 - 2023-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 AvailStatusMessages processed. See warnings before</Warning>
    </Warnings>
</OTA_HotelAvailNotifRS>

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

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

Example OTA_HotelAvailNotifRS Response with error

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