OTA_HotelResNotifRQ
Method for retrieving bookings from Kurzurlaub.de booking channel.
See also general information for our Reservation API in Developer Guide
Bookings are sent with status
| 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 |
OTA_HotelResNotifRQ - Request via GET - REST API
each method can be called via REST-API using GET. But this should only be done on bookings for development or testing purposes
Parameters used:
AgentDutyCode(optional if IP WhiteList or HTTP Basic Auth is used)HotelCode(mandatory)HotelReservationId(mandatory) a ReservationsId or comma separated IDsId(alternative to HotelReservationId)
Example:
GET /ota/api/HotelResNotif?AgentDutyCode=1&HotelCode=4&HotelReservationId=2129149
or comma separated ReservationsId`s
GET /ota/api/HotelResNotif?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).
OTA_HotelResNotifRQ - Anfrage per POST
OTA_HotelResNotifRQ Request (RQ) and Response (RS) using the example of our test hotel
@AgentDutyCode(Agent-ID): 1RequestorID@ID(Hotel-ID): 4HotelReservationID@ResID_Value(ReservationId): 12345678 or long version R12345678-A1234567-1234
Example OTA_HotelResNotifRQ (Request)
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelResNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Target="Production" Version="1">
<POS>
<Source AgentDutyCode="1">
<RequestorID ID="4" Type="4"/>
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="R1513719-A1234567-1234"/>
</HotelReservationIDs>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResNotifRQ>OTA_HotelResNotifRS - versions of the response
in the older version of the OTA_HotelResNotifRS, which is still used by partners Extra nights are not shown as RoomStays but as a service.
Here the OTA-V2 (new version from 10.2021) is described as a new version of the transmission of booking data with designated RoomStays
- Room costs per RoomStay (offer price per person is converted into room costs per night)
- Extra nights shown as RoomStay (price per person/night for one or more extra nights is converted into room costs per night)
Hints:
there should always be a <Success/> in the response,
<?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="1394da4bfc4daf820437a33cb87de833" PrimaryLangID="de"
TimeStamp="2021-10-28T12:52:38+02:00" Target="Production" Version="1.000">
<Success/>
<HotelReservations>
<HotelReservation LastModifyDateTime="2021-06-21T15:38:33+00:00">
<ResGlobalInfo>
<ResStatus>Modify</ResStatus>
<BookingChannel Primary="1" Type="7">
<CompanyName>Kurzurlaub.de Testagent WBE</CompanyName>
</BookingChannel>
<HotelReservationIDs>
<HotelReservationID ResID_Value="R1513719-190772-4" ResID_Date="2021-06-21T15:38:33+00:00" />
</HotelReservationIDs>
<Total AmountAfterTax="427.40" DecimalPlaces="2" CurrencyCode="EUR"/>
<TimeSpan Start="2021-10-05" End="2021-10-11"/>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Herr</NamePrefix>
<GivenName>Andreas</GivenName>
<Surname>Günther</Surname>
</PersonName>
<Telephone PhoneNumber="0385 1666555111111112" PhoneTechType="1"/>
<Address>
<CompanyName/>
<AddressLine>JS10</AddressLine>
<CityName>Schwerin</CityName>
<PostalCode>19053</PostalCode>
<CountryName Code="DEU">Deutschland</CountryName>
</Address>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGlobalInfo>
<Comments>
<Comment>
<Text><![CDATA[
Test
Gebuchtes Angebot:
- Offer-ID: 190772
- Offer-Name: Testarrangement schönes Schwerin - bitte nicht buchen 2
- RatePlanCode: BAR-190772
- RatePlanId: 190772
- Reservation-ID: 1513719
- Reservation-Code: 45VQK
- Reservation-Number: R1513719-AP190772-9432 / P88
Gebuchte Extras:
2 x Flasche Rotwein / 2 x 5.90 Euro [Per use] = 11.80 Euro total
4 x Testleistung Hukepack [10 Minuten] / 4 x 3.90 Euro [Per person] = 15.60 Euro total
]]></Text>
</Comment>
</Comments>
<RoomStays>
<RoomStay IndexNumber="1">
<RoomTypes>
<RoomType RoomTypeCode="5306">
<RoomDescription Name="Doppelzimmer (20m²)"/>
</RoomType>
</RoomTypes>
<Base AmountAfterTax="200.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="400.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<BasicPropertyInfo HotelCode="4"/>
<ResGuestRPHs>
<ResGuestRPH RPH="0"/>
</ResGuestRPHs>
<RatePlans>
<RatePlan RatePlanCode="BAR-190772" RatePlanID="190772">
<RatePlanDescription>
<Text>Testarrangement! Bitte dieses schöne Arrangement nicht buchen !!!</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RoomTypeCode="5306" RatePlanCode="BAR-190772" RatePlanID="190772" NumberOfUnits="2">
<Rates>
<Rate EffectiveDate="2021-10-05" ExpireDate="2021-10-08" UnitMultiplier="3">
<Base AmountAfterTax="46.67" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="140.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<RateDescription>
<Text>Offer rate (3 overnight stays)</Text>
</RateDescription>
</Rate>
<Rate EffectiveDate="2021-10-08" ExpireDate="2021-10-11" UnitMultiplier="3">
<Base AmountAfterTax="20.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="60.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<RateDescription>
<Text>Extra night rate (3 x Verlängerungsnacht inkl. Frühstück für 2
Doppelzimmer a 2 Personen / Keine Kinder)
</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts IsPerRoom="0">
<GuestCount AgeQualifyingCode="10" Count="4"/>
<GuestCount AgeQualifyingCode="8" Count="0"/>
</GuestCounts>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest ResGuestRPH="1">
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Herr</NamePrefix>
<GivenName>Andreas</GivenName>
<Surname>Günther</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
<ResGuest ResGuestRPH="2">
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Frau</NamePrefix>
<GivenName>Mama</GivenName>
<Surname>Günther</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
<ResGuest ResGuestRPH="3">
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Herr</NamePrefix>
<GivenName>Max</GivenName>
<Surname>Günther</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
<ResGuest ResGuestRPH="4">
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Frau</NamePrefix>
<GivenName>Gerda</GivenName>
<Surname>Günther</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<Services>
<Service ID="2289821" ServiceRPH="1" ServiceInventoryCode="10153" ServicePricingType="Per use"
Quantity="2">
<Price NumberOfUnits="2">
<Base AmountAfterTax="5.90" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="11.80" DecimalPlaces="2" CurrencyCode="EUR"/>
</Price>
<ServiceDetails>
<Comments>
<Comment>
<Text>Flasche Rotwein</Text>
</Comment>
</Comments>
</ServiceDetails>
</Service>
<Service ID="2289822" ServiceRPH="2" ServiceInventoryCode="10154" ServicePricingType="Per person"
Quantity="4">
<Price NumberOfUnits="4">
<Base AmountAfterTax="3.90" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="15.60" DecimalPlaces="2" CurrencyCode="EUR"/>
</Price>
<ServiceDetails>
<Comments>
<Comment>
<Text>Testleistung Hukepack</Text>
</Comment>
</Comments>
</ServiceDetails>
</Service>
</Services>
</HotelReservation>
</HotelReservations>
</OTA_HotelResNotifRS>Specifics - Number of rooms, overnight stays and extra nights
As an Example with 2 booked rooms, please note this news about UnitMultiplier / NumberOfUnits
@UnitMultiplier: Number of nights
refers to the period of the room stay (@EffectiveDate - @ExpireDate)
Example 1
<Rate EffectiveDate="2022-01-26" ExpireDate="2022-01-28" UnitMultiplier="2">Base@AmountAfterTax: price per room / per night
Total@AmountAfterTax: So in the total RoomStay as BaseAmount * UnitMultiplier = TotalAmount
<Rate EffectiveDate="2022-01-26" ExpireDate="2022-01-28" UnitMultiplier="2“>
<Base AmountAfterTax="140.00" DecimalPlaces="2" CurrencyCode="EUR“/>
<Total AmountAfterTax="280.00" DecimalPlaces="2" CurrencyCode="EUR“/>
</Rate>@NumberOfUnits: number of booked Rooms or 1, if Agent is using separate RoomStays for each booked room (if you need this 2 booked rooms as 2 separate RoomStays blocks)
Example 2
- 1 booked room but with additional nights, so we have 2 rate blocks for
- Offer rate (2 overnight stays)
- Extra night rate (2 x)
<RoomRates>
<RoomRate RoomTypeCode="22740" RatePlanCode="TEST-BAR-2N" RatePlanID="131729" NumberOfUnits="1">
<Rates>
<Rate EffectiveDate="2022-01-26" ExpireDate="2022-01-28" UnitMultiplier="2">
<Base AmountAfterTax="140.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="280.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<RateDescription>
<Text>Offer rate (2 overnight stays)</Text>
</RateDescription>
</Rate>
<Rate EffectiveDate="2022-01-28" ExpireDate="2022-01-30" UnitMultiplier="2">
<Base AmountAfterTax="178.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="356.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<RateDescription>
<Text>Extra night rate (2 x Verlängerungsnacht Verlängerungsnacht incl. Frühstück für 1 Doppelzimmer a 2 Personen / Keine Kinder)</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>Number of guests per room and distribution of guests
The number of guests per room and the allocation of guests to the booked rooms is always based on the principle of calculation based on standard room occupancy. There is a standard room occupancy for each room type, e.g.
- Double room with 2 people + children
- Single room with 1 person + children
A different occupancy (e.g. single occupancy) is not calculated for double rooms.
GuestCounts@IsPerRoom: attribute is always 0
All guests are not distributed per room but in total, so if a double room is booked, the number (Count="2") = 2 people in a double room,
for 2 booked double rooms, the number (Count="4"), i.e. 2 x 2 people each in the 2 double rooms.
<GuestCounts IsPerRoom="0">
<GuestCount AgeQualifyingCode="10" Count="4"/>
<GuestCount AgeQualifyingCode="8" Count="0"/>
</GuestCounts>Alternative cost attributes
Alternatively and in addition to the total amount @AmountAfterTax also possible with separate total cost attributes for the following areas
@RoomStaysAmountAfterTax(total amount of room costs / RoomStays)@ServicesAmountAfterTax(total amount of services)@CouponAmountAfterTax(Total value voucher)
Example:
<Total
AmountAfterTax="427.40" DecimalPlaces="2" CurrencyCode="EUR"
RoomStaysAmountAfterTax="400.00"
ServicesAmountAfterTax="27.40"
CouponAmountAfterTax="0.00"
/>Additional services booked - Services and ServicePricingType
All booked additional services are sent as a list in the Services block.
Service@ID(unique ID of the booked additional service)Service@ServiceRPH(consecutive number)Service@ServiceInventoryCode(Unique ID of the hotel's additional service at Kurzurlaub.de)Service@ServicePricingType(PriceType see list of ServicePricingTypes)Service@Quantity(number of booked services 1-n)Price@NumberOfUnits(identical to Quantity)
Example of services
<Services>
<Service ID="2289821" ServiceRPH="1" ServiceInventoryCode="10153" ServicePricingType="Per use" Quantity="2">
<Price NumberOfUnits="2">
<Base AmountAfterTax="5.90" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="11.80" DecimalPlaces="2" CurrencyCode="EUR"/>
</Price>
<ServiceDetails>
<Comments>
<Comment>
<Text>Flasche Wasser</Text>
</Comment>
</Comments>
</ServiceDetails>
</Service>
<Service ID="2289822" ServiceRPH="2" ServiceInventoryCode="10154" ServicePricingType="Per person" Quantity="4">
<Price NumberOfUnits="4">
<Base AmountAfterTax="3.90" DecimalPlaces="2" CurrencyCode="EUR"/>
<Total AmountAfterTax="15.60" DecimalPlaces="2" CurrencyCode="EUR"/>
</Price>
<ServiceDetails>
<Comments>
<Comment>
<Text>Testleistung einmalig pro Person</Text>
</Comment>
</Comments>
</ServiceDetails>
</Service>
</Services>Overview of the ServicePricingTypes
We send the following values for the ServicePricingType attribute.
The default value if something cannot be mapped is Per use.
Per roomPer room per nightPer stay(once per stay)Per personPer person per nightPer night(e.g. extra bed)Per use(per piece or use or also as default value)
Special Shapes
Per day(e.g. bike rental)Per minutePer hour
Error messages
If serious errors occur, e.g. in authentication, they are sent in an OTA_ErrorRS
Response with @ErrorCode and @ErrorMessage
Here is a list of common errors
| ErrorCode | ErrorMessage |
|---|---|
| 210 | HotelNotLinked - Hotel (HotelCode 1234) linked to another channel manager (your AgentDutyCode is 123) |
| 211 | HotelNotActivated - Hotel not found (HotelCode 1234 / AgentDutyCode 123) |
| 104 | InternalError - Empty HotelCode (HotelId) in accepted params (agentdutycode, hotelcode, ...) |
| 550 | CustomError - forbidden to read HotelReservation for ReservationId 12345678 (HotelId 1234) |
| 550 | CustomError - HotelReservation for ReservationId 12345678 not found |
Example OTA_ErrorRS (Response)
<OTA_ErrorRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
EchoToken="29419a3b53ee97680b01c40f377eb98f"
PrimaryLangID="de"
TimeStamp="2022-02-03T15:18:47+01:00"
Target="Production"
Version="1.000"
ErrorCode="550"
ErrorMessage="CustomError - forbidden to read HotelReservation for ReservationId 2109075 (HotelId 6069 vs 4)"
/><Errors> or <Warnings>) are sent within the response without the <Success/>, e.g. ReservationId not found or incorrect date periods specified
Example OTA_HotelResNotifRS (Response) with a reservation and a caught error
<?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="6dbce5c77f9a5be84fae246f97dd02c7" PrimaryLangID="de" TimeStamp="2022-02-03T16:35:43+01:00" Target="Production" Version="1.000">
<Errors>
<Error Code="550" Type="5">forbidden to read HotelReservation for ReservationId 2129150 (HotelId 6504 vs 4)</Error>
</Errors>
<HotelReservations>
<HotelReservation LastModifyDateTime="2022-01-31T11:51:58+01:00">
<ResGlobalInfo>
<ResStatus>Modify</ResStatus>
<BookingChannel Primary="1" Type="7">
<CompanyName>Kurzurlaub.de Testagent WBE</CompanyName>
</BookingChannel>
<HotelReservationIDs>
<HotelReservationID ResID_Value="R2129149-20540-4" ResID_Date="2022-01-31T11:02:30+01:00"/>
</HotelReservationIDs>
<Total AmountAfterTax="1990.00" DecimalPlaces="2" CurrencyCode="EUR"/>
<TimeSpan Start="2022-02-18" End="2022-02-20"/>
...
</OTA_HotelResNotifRS>Cancellation of bookings
If bookings are cancelled, we will send this status <ResStatus>Cancel</ResStatus>
with a cancellation date in the CancellationDate attribute.
Example Cancel and CancellationDate
<?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="6dbce5c77f9a5be84fae246f97dd02c7" PrimaryLangID="de" TimeStamp="2022-05-01T11:43:35+02:00" Target="Production" Version="2.000">
<HotelReservations>
<HotelReservation LastModifyDateTime="2022-05-01T11:43:35+02:00">
<ResGlobalInfo>
<ResStatus>Cancel</ResStatus>
<BookingChannel Primary="1" Type="7">
<CompanyName>Kurzurlaub.de Testagent WBE</CompanyName>
</BookingChannel>
<HotelReservationIDs>
<HotelReservationID ResID_Value="R2129149-20540-4" ResID_Date="2022-01-31T11:02:30+01:00" CancellationDate="2022-05-01T11:43:35+02:00"/>
</HotelReservationIDs>
...
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResNotifRS>