Developer Guide - Reservation API

The connected OTA partner uses the official OTA message OTA_HotelResNotifRQ to retrieve reservations from the Kurzurlaub.de channel. Kurzurlaub.de responds with OTA_HotelResNotifRS as confirmation of success or failure in processing the request.

We support 2 ways of communication: 1. Reservations can be requested and retrieved (PULL) 2. Reservations can be sent (PUSH)

General information

Needed information

Kurzurlaub.de follows the official OTA reservation specification and allows sending a lot of information about reservations. Not all of this information is mandatory for the OTA partner to process the reservation.

Please refer to the reservation specifications to see what information is mandatory.

EchoToken

EchoTokens (usually a GUID) are essential for all requests (especially OTA_HotelResNotifRQ) to identify the data. EchoTokens ensure that each request can be uniquely identified for troubleshooting purposes in both test and production environments.

All requests/responses you send from Kurzurlaub.de should contain an EchoToken and the response (from Kurzurlaub.de) will contain the same EchoToken that you sent in the request.

If no special EchoToken is sent, we deliver a GUID - Globally unique identifier (V4) as the EchoToken.

Delivery of reservations

The status of the reservation is determined by the attribute OTA_HotelResNotifRQ ResStatus, for which the values Book, Modify and Cancel are allowed.

Kurzurlaub.de allows only one hotel code per reservation. If a channel allows multiple hotels per reservation, one reservation per hotel must be sent.

Multiple rooms and rates are allowed in one reservation request.

Status of bookings

Bookings are sent with current status unless the status of bookings is changed by Booking changes (Modify) or cancellations (Cancel) we send a new push notification to the partner.

States	Description
Book	New bookings, this status is used only once when first sent, after that all further responses to a booking ID are always sent with status Modify
Modify	Booking changes or retrieval of a booking that has already been sent before via `ResID_Value` or by date range
Cancel	Cancellations

The reservation number (ResID_Value)

The value of the reservation number consists of:

R{Booking ID}-{Offer ID}-{Hotel ID}

e.g. R12345678-1234567-12345

or also with (A) R12345678-A1234567-12345 / (AP) R12345678-AP1234567-12345

For any inquiries you only need the booking number (Booking ID). Of course, the complete composition is also helpful.

The hotelier knows the complete value from his own administration area and the e-mails. He may need the offer number (Offer ID) to assign the included services to the offer.

If there is an important change to an entry, e.g. changing the number of rooms or the travel date, the status of the reservation Book is changed to Modify.

Reservation confirmation

It is important to note that Kurzurlaub.de acts as the authority when it comes to allowing or denying a reservation.

The OTA_HotelResNotifRS response from the partner (Success or Error) shows us, whether the partner has received the reservation delivery message/notification request or not.

With this in mind, the pair OTA_HotelResNotifRQ ↔ OTA_HotelResNotifRS, that sends the reservation message/notification to the OTA partner cannot be linked in a front-end customer booking process.

The customer/agent making a reservation through your booking channel should be able to make a reservation, regardless of the response (or lack thereof) he will receive back from an OTA partner.

Please note:

Kurzurlaub.de allows only one 1 hotel code per reservation. If a partner allows multiple hotels per reservation, 1 reservation per hotel must be submitted.
Kurzurlaub.de allows multiple reservations per request sent.
If reservations are requested via ResID_Value, you should request only 1 reservation.

Error handling

If the response of type OTA_HotelResNotifRS contains an error message, the reservation request cannot be processed, because some data/parameters are invalid.

This could be the case, for example, if required data is missing or if the login information or hotel code is incorrect and the reservation is not processed until the error is corrected. If the error is that required elements or attributes are missing, the implementation must be adjusted to send the required data.

If the error is related to credentials, verify that the correct username/password is being sent. If the error is an invalid hotel code, contact the hotel to ensure the interface is set up correctly to receive reservations.

Examples of common sources of error:

Partner credentials (AgentDutyCode)
invalid HotelCode
Hotel not online / not connected to the partner
invalid reservation ID (ResID_Value)

An XML response with ErrorCode and ErrorMessage is also always sent for error messages, with a Status 200 - OK .

See our implemented [OTA ErrorCodes]/(/error_handling) in the section [Error Handling]/(/error_handling)

A Status 401 - Forbidden is only sent if there are errors in the authentication (problem with AgentDutyCode or HotelCode).

If the response is an HTTP error response code in the Status 500 range, the connecting OTA partner is expected to retry requesting the reservation, until it is successfully delivered or a predefined timeout period is reached.

If a reservation cannot be retrieved, a problem should be reported to the Kurzurlaub.de support team.

Retrieve reservations (PULL)

Overview of available messages

Various official OTA messages for retrieving (PULL) bookings are supported by Kurzurlaub.de

OTA_HotelResNotifRQ (default OTA Message)
OTA_HotelResRQ
OTA_ReadRQ
OTA_GetBookingRQ (custom)

In order to achieve the goal of a complete 2-way integration between the Kurzurlaub.de booking channel and a channel manager, it is advantageous to use the PUSH method for sending the booking data.

Send reservations to OTA partners (PUSH)

We'll keep you up to date!

When the hotelier receives a booking, we can send you a simple push to request new booking details by Reservation ID. The same applies to changes and cancellations. For example, the push can be formed like this:

GET your.exampledomain.com/push.php?requestor_id=12345&resid_value=R12345678-1234567-123456&resstatus=new

3 parameters sent: - requestor_id - resid_value - resstatus

The exact composition and designation of the parameters is up to you, possible parameters are e.g. the RequestorID, ResID_Value and ResStatus. In order to authorize us for your service, additional necessary parameters can be appended.

XML with booking data can also be sent, but we prefer it if you send the booking data after the push via ResID_Value and Get Message OTA_HotelResNotifRQ.

For more information and to set up the PUSH, contact the connectivity team directly.

Query bookings via GET - REST-API

Each supported OTA message can also be called via REST-API using GET. But this should only be done on bookings for development or testing purposes

General parameters used:

AgentDutyCode (optional if IP WhiteList or HTTP Basic Auth is used)
HotelCode (mandatory)

Reading bookings with ReservationsId

Parameters used:

HotelReservationId (mandatory) a ReservationsId or comma separated IDs
Id (alternative to HotelReservationId)

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&HotelReservationId=2129149

or comma separated ReservationsId`s

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&HotelReservationId=2129149,2129150,2129151

Alternatively, you can also specify the entire ResID_Value (R12345678-A123456-1234, e.g. R2129149-A20540-4).

Read transactions with date range (date from/to)

Parameters used:

DateFrom
DateTo

A DateFormat or DateTimeFormat is expected - DateFormat (YYYY-MM-DD) - DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS)

All bookings are delivered in the date range from/to (00:00:00 - 23:59:29) or with the specifically requested time range via DateTimeFormat

Example

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&DateFrom=2022-01-01&DateTo=2022-02-01

or in DateTime format

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&DateFrom=2022-02-01T15:30:00&DateTo=2022-02-01T16:45:00

Read postings with date (PurgeDate)

Parameter used:

PurgeDate Expected a DateFormat (YYYY-MM-DD)

delivers all bookings from the requested date

Example

GET /ota/api/Read?AgentDutyCode=1&HotelCode=4&PurgeDate=2022-02-01

Query bookings via POST

General parameters used:

@AgentDutyCode (agent ID): (optional)
RequestorID@ID (Hotel ID): (mandatory)

Reading bookings with ReservationsId

Parameter used:

UniqueID@ID (mandatory) a ReservationsId

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <!-- send booking for this ReservationId -->
    <UniqueID Type="RES" ID="12345678" />
    <HotelReservations>
        <HotelReservation />
    </HotelReservations>
</OTA_ReadRQ>

Alternatively

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <UniqueID Type="RES" ID="1513695" />
</OTA_ReadRQ>

Read transactions with date range (date from/to)

Is expected from the parameters

a valid DatePeriod (@Start - @End)
a valid DateFormat or DateTimeFormat
Date format (YYYY-MM-DD)
DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS)

Variant 1 - parameters used:

SelectionCriteria@Start (mandatory)
SelectionCriteria@End (mandatory)

Example:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="3.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
    <ReadRequests>
        <HotelReadRequest HotelCode="4">
            <SelectionCriteria Start="2022-01-01" End="2022-01-30"/>

            <!-- alternative DateTimeFormat
            <SelectionCriteria Start="2022-01-27T11:30:00" End="2022-01-27T11:37:00"/>
            -->
        </HotelReadRequest>
    </ReadRequests>
</OTA_ReadRQ>

Variant 2 - parameters used:

GlobalReservationReadRequest@Start (mandatory)
GlobalReservationReadRequest@End (mandatory)

Example:

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="3.0">
<POS>
    <Source AgentDutyCode="1">
        <RequestorID ID="4" Type="4"/>
    </Source>
</POS>
<ReadRequests>
    <HotelReadRequest HotelCode="4"/>
    <GlobalReservationReadRequest Start="2020-10-01" End="2020-11-30"/>

    <!-- alternative DateTimeFormat
    <GlobalReservationReadRequest Start="2022-01-27T11:30:00" End="2022-01-27T11:31:00"/>
    -->
</ReadRequests>
</OTA_ReadRQ>

Read postings with date (PurgeDate)

is not offered in the OTA_ReadRQ message for POST requests because it is not intended according to the OTA specification.

Read new bookings (PULL)

if no parameters are given, we deliver all new bookings that have never been sent. Attention: this only happens exactly once!

Parameters used:

none

<?xml version="1.0" encoding="UTF-8"?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="2.0">
    <POS>
        <Source AgentDutyCode="1">
            <RequestorID ID="4" Type="4"/>
        </Source>
    </POS>
</OTA_ReadRQ>

OTA_HotelResNotifRS - versions of the response

The reservation data is output identical to the OTA format and in the form the standard message

OTA_HotelResNotifRQ - see more information about the output format

Notice:

If there are no reservations for the requested parameters, you will get a response with a <Success/> (so there were no errors in the sent parameters) and an empty <HotelReservations/> block.

Example: no reservations available

<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResNotifRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" EchoToken="5915874940c61a0f496dd31928e85672" PrimaryLangID=" en" TimeStamp="2022-02-04T15:48:17+01:00" Target="Production" Version="1.000">
  <Success/>
  <HotelReservations/>
</OTA_HotelResNotifRS>

Error messages

If serious errors occur, e.g. in authentication, they are sent in an OTA_ErrorRS response with @ErrorCode and @ErrorMessage

See the standard message documentation for a list of common errors OTA_HotelResNotifRQ

and in our implemented [OTA ErrorCodes]/(/error_handling) in the [Error Handling]/(/error_handling) area

Special note on format errors:

A special error message refers to the incorrect format of the parameters DateFrom, DateTo or at PurgeDate

A DateFormat (YYYY-MM-DD) or DateTimeFormat (YYYY-MM-DD(T)HH:MM:SS) is expected

Example: ErrorMessage

<?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="f3de3733d5095b49a5c774b99f467e57" PrimaryLangID=" en" TimeStamp="2022-02-04T12:15:46+01:00" Target="Production" Version="1.000"
ErrorCode="500"
ErrorMessage="InternalError - Internal OTA Error: wrong format for param DateFrom (2022-02-01T15:30:00) or param DateTo (2022-02-01T16:45:0) in GET method ErrorRS (allowed format: YYYY-MM -DD or YYYY-MM-DD HH:MM:SS)"
/>