1. Getting Started

1.1 Steps

  1. Contact Qunar and obtain the account and password of the open development platform.
  2. Refer to the standard document on the platform for development and use the validation tool of this development platform to test.
  3. Test and run the following case
  4. Conduct the final test on the open platform with the official data to be launched, and prepare to go online.
  5. Contact Qunar to launch a hotel, and Qunar will assist agents to test the complete process online; And arrange follow-up matters for the training.

1.2 Bullet Points

  • Content-Type only support text type, such as Content-Type="text/xml"。Extract the gzip file.
  • charset need to be UTF-8 encoded.
  • do NOT omit the XML header <?xml version="1.0" encoding="utf-8"?> from your response.
  • When transmitting special characters, escape the special characters such as &、<、>、‘、“.

1.3 Reservation Process

Agents accessing Qunar.com need to first understand the search and reservation logic of Qunar.com to better comprehend the API documentation. It is recommended to download the "Qunar Travel" APP to gain a deeper understanding of the reservation process and facilitate subsequent online verification.

Due to differences in devices and versions, the following example images are for reference only.

Reservation Process - Steps Involved

Hotel Search –> Hotel List –> Hotel Detail –> Hotel Booking –> Pay/Order Confirm ..

1. Hotel Search Page (Search Page)

Open the "Qunar Travel" APP, click on the Overseas Hotels channel, and enter the [Hotel Search Page].

tool-manager

Specified input parameters：destination, check-in and check-out dates, number of adults/children, and keywords. Click Start Search to enter the [Hotel List Page].

tool-manager

tool-manager

2. Hotel List Page (List Page)

Specified input parameters: check-in and check-out dates, number of adults/children, and keywords. Clicking on ["Confirm"] will refresh the list of hotel quotes.

Data Source: Locally cached by Qunar or real-time fetched; Agents can configure the cache duration on Qunar. If not configured, the default system duration is 6 hours. When refreshing quotes, if the agent's quotes have not expired, the cached quotes will be used; if the quotes have expired, real-time fetching will occur for the specified check-in and check-out dates, and number of adults/children. Agents can reduce the price change rate by shortening the cache duration or configuring real-time fetching. For specific configuration methods, please communicate with Qunar's sales or operations team.

Upon selecting a hotel, proceed to the [Hotel Details Page].

tool-manager

tool-manager

3. Hotel Details Page (Detail Page)

Hotel Information: Displays hotel images maintained by Qunar, room type images, hotel highlights, introductions, facilities, hotel policies, transportation and surroundings, review information, and other relevant details.

Qunar Room Type - Agent Room Type: One Qunar room type corresponds to multiple agent room type quotes.

tool-manager

tool-manager

Clicking the Book button will take you to the [Order Fill-in Page].

Specified input parameters include check-in date, check-out date, and number of adults/children. By changing these parameters and clicking Confirm, you can refresh the hotel quote data.

Data Source: Locally cached by Qunar or real-time fetched. Agents can configure the cache duration on Quanr. If not configured, the default system duration is 6 hours. When refreshing quotes, if the agent's quotes have not expired, the cached quotes will be used; if the quotes have expired, real-time fetching will occur for the specified check-in and check-out dates, and number of adults/children. Agents can reduce the price change rate by shortening the cache duration or configuring real-time fetching. For specific configuration methods, please communicate with Qunar's sales or operations team.

tool-manager

tool-manager

4. Order Booking Page (Booking Page)

Specified input parameters: Hotel, room type, check-in and check-out dates, number of adults/children, and number of rooms.

Consumers can change the number of rooms on this page, but cannot change the hotel, room type, check-in and check-out dates, or number of adults/children.

Data Source: The quotes on this page are all obtained in real-time. The process from the Detail Page to the Booking Page is referred to as "order progression." Changes in price or timeouts may result in failed order progression.

Clicking the Submit Order button will take the user to the payment page.

Special note：

If the response time exceeds the limit (10 seconds timeout), the booking will fail, which will severely impact the user experience.

tool-manager

5. Order Operations (Payment/Order Confirmation)

After the consumer makes a payment, Qunar will initiate an order request to the agent side.

When the consumer cancels the order, Qunar will initiate a cancellation request to the agent side.

2. Data API

The basic data for the international hotel standard API primarily consists of two parts: hotel basic data (provided by agents) and quotation API data (provided by agents).

2.1 Hotel Basic Data (Provided by Agents)

Qunar obtains the list of hotels from agents by invoking this API.

Data Purpose: For mapping hotel information between agents and Qunar, enabling the aggregation of agent hotels and Qunar hotels.

Update Method: Full update only, no support for incremental updates or pagination.

Update Time: Automatically updated every day at midnight. Alternatively, manual processing is possible.

Update Restriction: If the number of hotels is reduced by three-quarters or more, or if the reduction exceeds 1,000 hotels, only manual processing is allowed.

If hotel aggregation cannot be completed, please refer to the corresponding hotel names and addresses on www.qunar.com and correct the hotel names and addresses provided by the [Hotel Basic Data] API to achieve aggregation.

2.1.1 Request

HTTP URL: https://base_url

HTTP Param: No specific requirements

HTTP Method：GET

The URL is provided by the agent and configured on the Qunar side.

The "base_url" is provided by the agent and can include additional parameters to identify the source of the request.

Examples:

https://test.hotel.com?source=Qunar

https://test.hotel.com

Both are acceptable.

For any subsequent mentions of "base_url" in related APIs, please refer to this explanation.

2.1.2 Response

<?xml version="1.0" encoding="utf-8"?>
<list>
   <hotel id="58283" tel="82-2-771-0500" address="87, Sogong-dong, Jung-gu, Seoul, Korea (100-070) (106, Sogong-ro, Jung-gu, Seoul)" name="The Westin Chosun Seoul" nameCN="首尔威斯汀朝鲜酒店" city="seoul" coordinateProvider="1" longitude="139.44468" latitude="35.54667"></hotel>
   <hotel id="58284" tel="82-2-7711000" address="30, Eulji-ro, Jung-gu, Seoul(EX.1, Sogong-dong, Jung-gu, Seoul, Korea)" name="LOTTE HOTEL SEOUL" nameCN="首尔乐天饭店" city="seoul" coordinateProvider="1" longitude="139.44468" latitude="35.54667"></hotel>
   <hotel id="58285" tel="02-771-2200" address="119, Sogong-ro, Jung-gu, Seoul" name="THE PLAZA HOTEL" nameCN="首尔广场傲途格精选酒店" city="seoul" coordinateProvider="1" longitude="139.44468" latitude="35.54667"></hotel>
   <hotel id="58286" tel="82-2-2233-3131" address="249, Dongho-ro, Jung-gu, Seoul" name="THE SHILLA SEOUL" nameCN="首尔新罗酒店" city="seoul" coordinateProvider="1" longitude="139.44468" latitude="35.54667"></hotel>
   <hotel id="58287" tel="82-2-3216-5656" address="353, Yeonhui-ro, Seodaemun-gu, Seoul" name="GRAND HILTON SEOUL HOTEL" nameCN="首尔希尔顿大酒店" city="seoul" coordinateProvider="1" longitude="139.44468" latitude="35.54667"></hotel>
   ...
</list>
name/key type required/optional description
hotel@id String required unique identifier of a hotel at price provider, 1-16 characters, used in all other APIs
hotel@name String required 1-100 characters；
only English supported；
This item is mandatory for Global hotels and can only be entered in English；
hotel@nameCN String optional 1-100 characters；
only Chinese supported；
This field can increase the aggregation rate of hotel information. Please fill in as much as possible.
This item is an optional item. Hong Kong, Macao and Taiwan hotels can enter Chinese names if they do not have English names.
hotel@address String required 1-150 characters, only English and Chinese are supported
hotel@coordinateProvider Integer required 1-Google，2-Baidu
hotel@longitude String required Hotel longitude
hotel@latitude String required Hotel latitude
hotel@tel String required 1-50 characters；
This field can increase the aggregation rate of hotel information. Please fill in as much as possible.
hotel@hotelRelationships String optional This field can increase the aggregation rate of hotel information. Please fill in as much as possible.
supplier key:ctrip, agoda, booking, expedia, hotelbeds, elong ctrip:xxxx, expedia:xxxx, booking:xxx

2.2 Quote API Data - Single Hotel

Qunar obtains quote information for a specified hotel by invoking this API. The quote information includes basic room attributes, room rates, room availability, and room inventory.

Occurrence Times:

Search Page → List Page, List Page → Detail Page, Detail Page → Booking Page, Booking Page → Pay/Order Confirmation

Differences in Requests:

  1. Without the "roomId" parameter: Search Page → List Page, List Page → Detail Page;
  2. With the "roomId" parameter: Detail Page → Booking Page, Booking Page → Pay/Order Confirmation;
  3. Adults/Children Parameters: If the quote request does not include adults/children parameters, please return available quotes for all occupancy levels;If you are unable to return a full quotation, please contact Qunar through your business manager to configure it and change it to request configuration based on the actual number of users. This strategy will capture quotations based on users' actual requests

2.2.1 request

HTTP URL:http://base_url?xml=xxx

HTTP Param:xml

HTTP Method:GET

Note: The "base_url" is provided by the agent and configured on the Qunar side. The agent can append parameters to identify the source of the request.

Example of "base_url":

https://test.hotel.com?source=Qunar

https://test.hotel.com

Complete Example:

https://test.hotel.com?source=Qunar&xml=xxx

https://test.hotel.com?xml=xxx

Example of Parameter XML:

<?xml version="1.0" encoding="utf-8"?>
<priceRequest>
    <hotelId>16166</hotelId>
    <checkin>2019-09-13</checkin>
    <checkout>2019-09-14</checkout>

    <roomId>199</roomId><!-- only appears at booking page -->
    <numberOfRooms>2</numberOfRooms>
    <customerInfos>
        <customerInfo seq="0" numberOfAdults="2" numberOfChildren="2" childrenAges="8|12" >
        </customerInfo>
        <customerInfo seq="1" numberOfAdults="2" numberOfChildren="0" childrenAges="" >
        </customerInfo>
    </customerInfos>

</priceRequest>
name/key type required/optional description
hotelId String required unique identifier of a hotel at price provider, corresponds to the id attribute of <hotel > in Hotel List API response
checkin String required format is YYYY-MM-DD, eg. 2009-09-03
checkout String required format is YYYY-MM-DD, eg. 2019-09-04
roomId String optional only appears at Qunar Booking page, corresponds to the id attribute of <room> in previous price response
numberOfRooms integer optional only appears at Qunar booking page, the size of <customerInfos> = numberOfRooms (note:first time to enter the order filling page,this value is 1 and without customerInfos node by default)
customerInfo@seq integer optional id, starts from 0.
If there is no adult/child parameter in the quotation request, please return the available quotation for all the numbers.；
customerInfo@numberOfAdults integer optional The maximum of this value is “maxOccupancy ”returned by agent
customerInfo@numberOfChildren integer optional The maximum of this value is “maxOccupancy ”returned by agent
customerInfo@childrenAges String optional '|' separated integers, eg. 4|7 means a 4 year old child and a 7 year old child;
extras String optional If entering the check stage requires passing in quotation request parameters, please return the data of the Extra node in the wrapper quotation. Our company passes in this field through the check request.

2.2.2 response

<?xml version="1.0" encoding="utf-8"?>
<priceResponse hotelId="9987" hotelName="Toyoko Inn Tokyo Machida-eki Odakyu-sen Higashi-guchi" hotelNameCN="东京东横町田站东口小田急森酒店" hotelAddress="1-3-3, Naka-machi, Machida-city, Tokyo"
  hotelPhone="0081-42-7281045" coordinateProvider="1" longitude="139.44468" latitude="35.54667" checkin="2019-09-13" checkout="2019-09-14" currencyCode="USD" >
  <rooms> <!-- one or more <room> -->
    <room id="P_1" physicRoomId=7572685 name="Double（breakfast）" nameCN="标准房（含早）" payType="PREPAY" prices="200|200" status="ACTIVE|DISABLED" counts="5|5"
    roomRate="180|180" taxAndFee="20|20" broadband="FREE" maxOccupancy="2" occupancyNumber="2"
    freeChildrenNumber="1" freeChildrenAgeLimit="8" instantConfirmRoomCount="3|3" wifi="FREE" window="1"
        checkinTime="12:00" checkoutTime="12:30" area="" guestType="ALL_GUEST" >
        <!-- constraint: for each day prices = roomRate + taxAndFee -->
      <bookingRule userProperty="101,102,103" ip="1" >
            <bookingTime maxAdvanceDays="8" minAdvanceDays="2" minAdvanceHours="6" />
      </bookingRule>
      <bedType>
        <beds code="DOUBLE" desc="大床" count="1" size="1.8m*2m" >
        </beds>
      </bedType>
      <meal>
        <breakfast count="2|2" desc="日式早餐" />
        <lunch count="0|0" desc="" />
        <dinner count="0|0" desc="" />
      </meal>

      <refund returnable="true" timeZone="GMT+9" > <!-- timeZone -->
        <refundRules>
            <refundRule before="29" type="DEDUCT_BY_AMOUNT" value="50" />
            <refundRule before="25" type="DEDUCT_BY_PERCENT" value="70" />
        </refundRules>
      </refund>

      <remarks><!-- optional -->
         <remark seq="1" value="the weather will be rainy in July, please prepare rain gears by yourself"/>
         <remark seq="2" value="no pets allowed please"/>
         <remark seq="3" value="free parking, but cannot make sure available parking lots any time"/>
      </remarks>

      <extras><!-- optional -->
        <property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
        <property key="OTHER_KEY" value="XXXYYY" />
      </extras>

      <taxes><!-- optional -->
        <tax id="51" type="IncludedInTotalPrice" amount="100|100" currency="CNY" />
      </taxes>

    </room>
  </rooms>
</priceResponse>

please return <priceResponse/> if you have no room(s) available for the specific <priceRequest>.

<priceResponse>

field name type required/optional description/constraint
hotelId String required corresponds to hotelId in the request，Cannot repeat
hotelName String required Please keep in line with the hotelName of Hotel List (Provided by Agents)
hotelNameCN String required Please keep in line with the hotelNameCNof Hotel List (Provided by Agents)
hotelAddress String required Please keep in line with the hotelAddress of Hotel List (Provided by Agents)
coordinateProvider Integer required 1-Google，2-Baidu
longitude String required Hotel longitude
latitude String required Hotel latitude
checkin String required yyyy-MM-dd, must be the same with <checkin> in request
checkout String required yyyy-MM-dd, must be the same with <checkout> in request
currencyCode String required The currency code for room type pricing is as follows, with the currently supported currencies being USD ("US Dollar"), EUR ("Euro"), JPY ("Japanese Yen"), CNY ("Chinese Yuan"), HKD ("Hong Kong Dollar"), MOP ("Macao Pataca"), TWD ("Taiwan Dollar"), KRW ("South Korean Won"), SGD ("Singapore Dollar"), THB ("Thai Baht"), GBP ("British Pound"), AUD ("Australian Dollar"), CAD ("Canadian Dollar"), RUB ("Russian Ruble"). This must be consistent with the settlement currency configured in the Qunar backend.

<room>

field name type required/optional description/constraint
id String required 1. The product room type ID under the current hotel.
2. The roomId in the quote request on the order fill-out page originates from this field.
3. The maximum length is 255 characters.
4. The room type ID must be unique and cannot be repeated.
physicRoomId Long required 1. This field needs to transmit the agent's own physical room type ID.
2. This field is used to assist in the aggregation of room types.
name String required The maximum character length for all relevant fields is 255, and the values should be consistent with those on the official website as much as possible.
For overseas hotels, the name field is mandatory and cannot be left empty. It should be entirely in English (including numbers and English punctuation).
For hotels in Hong Kong, Macao, and Taiwan, either name or nameCN must be provided, and neither can be left empty.
nameCN String required
payType enums required PREPAY = requires the consumer pay online
prices String required '|' separated numbers, the quantity must agree with checkin/checkout, eg. checkin=2015-01-21, checkout = 2015-01-23, 100|108 means 100 for first night(2015-01-21), 108 for second night(2015-01-22), the value of each day can not be blank, eg. 100||110 is invalid. for each day price = roomRate + taxAndFee
status String required '|' separated enums, eg. ACTIVE|DISABLED means this room is available for booking for first day, not available for second day
counts String required '|' separated numbers, the available room stock for each day, integers >= 0; eg. 3|5 means 3 available rooms for first day, 5 available rooms for second day
roomRate String required similar with prices;
prices=roomRate+taxAndFee
taxAndFee String required similar with prices;
prices=roomRate+taxAndFee
broadband String required enum values, please refer to FeeMode of enumerations section, not null, if unclear please set to UNKNOWN
wifi String required same with broadband
window Integer required 1-with window 2-no window 3-part of the window 99-unknown
maxOccupancy Integer required positive integer; eg. 4 means this room can fit in 4 people at most.
occupancyNumber Integer required 1)if the price will change as numbers of guests changes. Please add occupancyNumber behind maxOccupany under priceResponse; 2)For example, if the rate is for 1 adult but the max occupancy of this room is 2 adults, please response like this:maxOccupancy="2" occupancyNumber="1".The rate shown on the order filling page is interpreted as 1 adult's rate; 3)the default guest number display rules on order filling page is: A.when occupancyNumber is not null, it shows the value of occupancyNumber, if occupancyNumber is null,and maxOccupancy = 1, then it shows 1;Otherwise, it shows 2; 4)occupancyNumber <= maxOccupancy.
instantConfirmRoomCount String required '|' separated numbers, eg. instantConfirmRoomCount= 5|5, and consumer made an order which asks for 2 rooms every day, then the order will be confirmed successful at Qunar side, agent does not need to confirm this order through Order Operation API, if agent can instantly confirm all of the bookings, instantConfirmRoomCount should be the same with room@counts, if agent cannot instantly confirm any one of the bookings, this should be all zeroes(0|0|...|0) for every day
checkinTime String optional checkin time of this hotel, will be prompted at Qunar's Booking page, eg. 12:00
checkoutTime String optional checkout time of this hotel, will be prompted at Qunar's Booking page, eg. 14:00
area String optional area of this room, eg. 12 means 12 square meters, please fill it in as far as possible, otherwise you will have the risk of compensation when the user has a complaint.
guestType String required enum values, please refer to GuestType of enumerations section
taxes String optional Single tax details, including tax id, type, one night tax and currency

These tags can appear below room: <bookingRule> <bedType> <meal> <refund> <remarks> <guaranteeRules> <customerLimit>

<bookingRule> (bookingRule is an optional node for room)
Restrict the display conditions of quoted prices. 
<bookingRule userProperty="101,102,103" ip="1" >
      <bookingTime maxAdvanceDays="8" minadvanceDays="2" minAdvanceHours="6" />
</bookingRule>
field name type required/optional description/constraint
bookingRule@userProperty String optional Multiple choices. If not specified, it will be visible to all users. Membership status and cross-identity have a logical AND relationship.
Membership Status:
101: Regular Member (New User)
189: Silver Member
102: Gold Member
103: Platinum Member
104: Diamond Member
Cross-Identity:
111: Flight Ticket User
107: Train Ticket User
109: Bus Ticket User
112: Ride-hailing User
108: Ticket User
120: Vacation User

Example: If 189, 102, 111, 107 are specified, it means it is visible to users who are both Silver or Gold Members and Flight Ticket or Train Ticket Users.
bookingRule@ipLimitType Enum optional Single Choice:
0: No Restriction
1: Local vs. Non-local Restriction
In conjunction with bookingRule@locationType, bookingRule@weeklyIndex, bookingRule@start, bookingRule@end, and bookingRule@visible, it controls whether the hotel is visible to users with local or non-local IPs on weekdays or weekends (during specific time ranges).
2: Regional Restriction
In conjunction with bookingRule@countryList, bookingRule@cityList, bookingRule@weeklyIndex, bookingRule@start, bookingRule@end, and bookingRule@visible, it controls whether the hotel is visible to users in specified countries or cities on weekdays or weekends (during specific time ranges).
bookingTime@locationType Enum optional In the case where ipLimitType=1, the following options are mandatory:
1: The user's IP address must be in the same country as the hotel's location.
2: The user's IP address must be in the same city as the hotel's location.
bookingRule@countryList String optional Under the condition of ipLimitType=2, the effective countries are specified as follows:
e.g., countryList="China,Japan"
bookingRule@cityList String optional For the effective cities under the condition of ipLimitType=2, if both countryList and cityList are not empty, cityList takes precedence.
e.g., cityList="i-macau,i-hong_kong"
bookingRule@weeklyIndex String optional Weekdays are represented as "1111100", and non-weekdays as "0000011".
Note: Weekdays refer to Monday to Friday, and non-weekdays to Saturday and Sunday.
bookingRule@start String optional Only numbers ranging from 0 to 24 are supported.
weeklyIndex = "1111100", start = "12", end = "14"; represents the time range from 12:00 to 14:00 on weekdays (Monday to Friday).
weeklyIndex = "0000011", start = "22", end = "23"; represents the time range from 22:00 to 23:00 on non-weekdays (Saturday to Sunday).
weeklyIndex = "1111100,0000011", start = "12,22", end = "14,23"; represents the time range from 12:00 to 14:00 on weekdays (Monday to Friday) and from 22:00 to 23:00 on non-weekdays (Saturday to Sunday).
bookingRule@end String optional Used in conjunction with bookingRule@start, only numbers ranging from 0 to 24 are supported.
bookingRule@visible Boolean required true indicates visible; false indicates invisible.
PS: This only applies to ipLimitType.
bookingRule@ip Enum optional Single choice: if the user's current location cannot be obtained, the user will be invisible.
1: Only visible to mainland IPs.
2: Visible to both mainland and Hong Kong, Macao, and Taiwan IPs.
3. Not visible to local IPs of the hotel
(for overseas hotels, this is at the country level; for Hong Kong, Macao, and Taiwan hotels, this is at the province level.
For example, if a hotel in Tokyo is set to be invisible locally, it will be invisible to Japanese IPs; if a hotel in Hong Kong is set to be invisible locally, it will be invisible to Hong Kong IPs)
bookingTime@maxAdvanceDays Integer optional If there are no restrictions, do not transmit this field. If there are restrictions, this field must be >=0.
If checkin_date=2019-10-10 and maxAdvanceDays=8, then the quote can be booked up to 192 (8x24) hours in advance, starting from 2019-10-11 00:00, which means the quote can be booked after 2019-10-03 00:00 (local time).
bookingTime@minAdvanceDays Integer optional If there are no restrictions, do not transmit this field. If there are restrictions, this field must be >=0.
If checkin_date=2019-10-10, minAdvanceDays=2, and minAdvanceHours=6, then the quote needs to be booked 48+6=54 hours in advance, starting from 2019-10-11 00:00, which means the quote can be booked before 2019-10-08 18:00 (local time).
bookingTime@minAdvanceHours Integer optional If there are no restrictions, do not transmit this field.
If there are restrictions, this field must be within the range of >=0 and <=23.
For example, if checkin_date=2019-10-10, minAdvanceDays=2, and minAdvanceHours=6,
then the quote can be booked 54 hours in advance (48 hours + 6 hours), starting from 2019-10-11 00:00.
This means the quote can be booked before 2019-10-08 18:00 (local time).
bookingTime@last Integer optional If there are no restrictions, do not transmit this field.
If there are restrictions, this field must be >=1, and it defaults to 90 if it exceeds 90.
For example, if checkin_date=2019-10-10, checkout_date=2019-10-11, and last=2, then the quote will be invisible.
However, if checkin_date=2019-10-10, checkout_date=2019-10-12, and last=2, then the quote will be visible.
bookingTime@maxLast Integer optional If there are no restrictions, do not transmit this field.
If there are restrictions, this field must be >=1.
For example, if checkin_date=2019-10-10, checkout_date=2019-10-12, and maxLast=1, then the quote will be invisible.
However, if checkin_date=2019-10-10, checkout_date=2019-10-12, and maxLast=2, then the quote will be visible.
Note: In the context of hotel booking systems, last and maxLast fields are typically used to control the visibility of quotes based on the number of nights stayed. The exact meaning and behavior of these fields may vary depending on the specific system or platform.
bedType Node Attribute *(bedType is a required node for room)
Sometimes a hotel can offer different bed types for the same room type. For instance, the following example provides two bed types. Otherwise, only one <beds> node is needed. 
<bedType relation="OR" >
    <beds seq="1" code="SINGLE" desc="单人床" count="2" size="1.2m*2m" >
    </beds>
    <beds seq="2" code="DOUBLE" desc="大床" count="1" size="1.8m*2m" >
    </beds>
</bedType>
field name type required/optional description/constraint
bedType@relation enums required values AND, OR, can be empty
bedType/beds@seq String required id of this bed offering, will be used in <bedChoice> of Reservation API if more than one <beds> offered
bedType/beds@code enums required refer to BedTypeCode of enumerations section, if unclear set to OTHERS
bedType/beds@count Integer required number of beds in this room
If the number of beds cannot be determined, fill in 1 by default.
bedType/beds@size String required describes size of the bed please fill it in as far as possible, otherwise you will have the risk of compensation when the user has a complaint.eg.1.8m*2m
<meal> is a required sub element of <room>
Please provide "breakfast". 
  <meal>
        <breakfast count="2|2" desc="self-service breakfast" />
        <lunch count="0|0" desc="" />
        <dinner count="0|0" desc="" />
  </meal>
field name type required/optional description/constraint
meal/breakfast@count String required '|' separated numbers, describes breakfast every day, must >=0 , eg. 2|1 means with breakfast for 2 people on day 1, breakfast for 1 people on day2
meal/breakfast@desc String optional describes the meal in detail, can be empty
<refund> is an optional sub element of <room>
if <refund> does not appear, it means reservation of this room can not be canceled by consumer at Qunar end. 
<refund returnable="true" timeZone="GMT+9" > <!-- append timeZone -->
  <refundRules>
      <refundRule before="130" type="NO_DEDUCTION" value="0" />
      <refundRule before="26" type="DEDUCT_BY_AMOUNT" value="20" />
      <refundRule before="8" type="DEDUCT_BY_PERCENT" value="30" />
  </refundRules>
</refund>

The example above means (checkIn = 2019-09-25 checkOut = 2019-10-02)

before type value description/meaning
130 NO_DEDUCTION 0 2019-09-20 14:00:00 there will be no deduct
36 DEDUCT_BY_AMOUNT 20 2019-09-20 14:00:00~2019-09-24 12:00:00 20 currencyCode will be deducted
25 DEDUCT_BY_PERCENT 30 2019-09-24 12:00:00~2019-09-24 23:00:00 30% of the order price will be deducted
2019-09-24 23:00:00 reservation can not be canceled
field name type required/optional description/constraint
refund@returnable boolean required true means reservation of this room can be canceled according to rules below
refund@timeZone String required time zone of the hotel, Qunar will transfer the time point in refund policy to Beijing times according to this timeZone; eg. GMT+9 /GMT+09 for a tokyo hotel,cannot be like this:GMT+09:00
refund/refundRules/refundRule@before Integer required hours before midnight(24:00) of checkin day, eg. checkin=2019-09-23, before = 6 means 2019-09-23 16:00:00, before = 32 means 2019-09-22 14:00:00, before = 50 means 2019-09-21 20:00:00;
Quanr will increase the cancelable time by 2 hours to avoid the cancelable agent side of Q side caused by time difference, system or other factors.
refund/refundRules/refundRule@type Enums required refer to RefundType of enumerations section
refund/refundRules/refundRule@value Number required This field is mandatory when the refund type is either a fixed deduction amount or a percentage deduction of the room rate.

Special Note: In the current production environment logic, the refund rules are limited to three categories: free cancellation, partial refund (interpreted as one segment), and full deduction.

Example of Partial Refund (interpreted as one segment):

Refund rules provided on the agent side:

	<refundRule before="36" type="DEDUCT_BY_AMOUNT" value="20" />
	<refundRule before="25" type="DEDUCT_BY_PERCENT" value="30" />

Qunar will merge these into:

	<refundRule before="36" type="DEDUCT_BY_PERCENT" value="30" />
<remarks> is an optional node for room
It represents booking reminder information. 
<remarks><!-- optional, no more than 5 <remark> -->
    <remark seq="1" value="the weather will be rainy in July, please prepare rain gears by yourself"/>
    <remark seq="2" value="no pets allowed please"/>
    <remark seq="3" value="free parking, but cannot make sure available parking lots any time"/>
</remarks>
field name type required/optional description/constraint
remark@value String required no more than 100 characters.
This item will be displayed under the "Booking Instructions" section on the Booking page for users to view. If there is any information that requires special attention from users, please transmit this information to Quanr through this value to prevent user complaints. For example, what documents users must prepare when checking in at the hotel, whether children are allowed to stay, which fees need to be paid by users at the hotel, etc. Do not fill in information such as phone numbers, email addresses, or websites.
<customerLimit>(is an optional node for room)
Restrictions on Guests' Nationality
field name type required/optional description/constraint
customerLimit@regionLimit Integer required 1.Blacklist 2.Whitelist 3.Unrestricted
customerLimit@regions String required ISO 3166-2 standard 3-digit country codes. In cases of multiple nationalities, separate them with commas, with a maximum of 5 nationalities allowed.
<extras>(is an optional node for room)
  <extras><!-- optional -->
						<property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
						<property key="OTHER_KEY" value="XXXYYY" />
					  </extras>
field name type required/optional description/constraint
property@key String required The maximum length of the field is 100 characters.
Select and fill in the relevant enumerated key value associated with the supplier based on the actual situation.
EAN: Physical room type ID corresponding to the supplier Expedia,
BK: Physical room type ID corresponding to the supplier Booking,
AGODA: Physical room type ID corresponding to the supplier Agoda,
ELONG: Physical room type ID corresponding to the supplier eLong,
GCTRIP: Physical room type ID corresponding to the supplier Ctrip.
property@value String required The maximum length of the field is 100 characters.

Sometimes, agents need to attach additional information to the <room> node, which can be returned during the booking process (within the <bookingRequest>).

<taxes>(is an optional node for room)
<taxes><!-- optional -->
    <tax id="51" type="IncludedInTotalPrice" amount="100|100" currency="CNY" />
</taxes>
field name type required/optional description/constraint
tax@id String required The mapping between the id and the name are as follows:
51: Hong Kong Rent tax
tax@type Enum required IncludedInTotalPrice: tax included in the room.prices and room.taxAndFee
ExcludedFromTotalPrice: tax payable after arrival (not included in the room.prices or room.taxAndFee )
tax@amount String optional Represents the amount of tax for a single room night, and the format refers to price and Tax fee.
tax@currency String optional Tax currency, see currencyCode.

2.3 Room Price for Multiple Hotels (provided by supplier)

Provide prices for multiple hotels by one HTTP transaction.

Only used once a day to get all supplier's room price

2.3.1 request

HTTP URL：http://base_url?xml=xxx

HTTP Param：xml

HTTP Method：GET

Response time : less than 30 sec

<?xml version="1.0" encoding="utf-8"?>
<priceRequest>
    <hotelIds>9987,9988</hotelIds> <!-- , separated Ids -->
    <hotelCity>tokyo</hotelCity>
    <checkin>2019-09-13</checkin>
    <checkout>2019-09-14</checkout>
    <numberOfRooms>2</numberOfRooms>
    <customerInfos>
        <customerInfo seq="0" numberOfAdults="2" numberOfChildren="2" childrenAges="8|12" >
        </customerInfo>
        <customerInfo seq="1" numberOfAdults="2" numberOfChildren="0" childrenAges="" >
        </customerInfo>
    </customerInfos>
</priceRequest>
field type required/optional description
hotelIds String required unique identifier of a hotel at price provider, separated by',', up to 100
checkin String required format is YYYY-MM-DD, eg. 2015-12-21
checkout String required format is YYYY-MM-DD, eg. 2015-12-21
numberOfRooms Integer optional
customerInfo@seq integer optional CustomerInfo id, starts at 0.When customerInfo exists, the number of customerInfo is equal to numberOfRooms
customerInfo@numberOfAdults integer optional
customerInfo@numberOfChildren integer optional
customerInfo@childrenAges integer optional A combination of Numbers separated by'|'. eg, 4|7 means a 4 years old child and a 7 years old child.

2.3.2 response

Please return <list/> if no available <room>s,

the xml elements is identical to those in 2.2 Quote API Data - Single Hotel

response example, 

<?xml version="1.0" encoding="utf-8"?>
<list>
    <priceResponse hotelId="9987"
        ...
    </priceResponse>
    <priceResponse hotelId="9988"
        ...
    </priceResponse>
</list>

3. Order API

3.1 Order Reservation API (Provided by Agent)

After the consumer completes the payment, Qunar will initiate a reservation request to the agent side. Each reservation can only specify one room type.

3.1.1 request

HTTP URL：http://base_url

HTTP Param：xml

HTTP Method：POST

Connection Timeout：The response time should not exceed 10 seconds.

HTTP ContentType：x-www-form-urlencode

The URL is provided by the agent and configured on the Qunar side.

<?xml version="1.0" encoding="utf-8"?>
<bookingRequest>
    <hotelId>16166</hotelId>
    <checkin>2015-02-20</checkin>
    <checkout>2015-02-22</checkout>
    <totalPrice>800</totalPrice><!--  totalPrices = sum(prices) * numberOfRooms  -->
    <currencyCode>USD</currencyCode>
    <rmbPrice>5504</rmbPrice>
    <totalPriceAfterPromotion>5500</totalPriceAfterPromotion>
    <promotionPrice>4</promotionPrice>
    <customerArriveTime>16:00-18:00</customerArriveTime>
    <specialRemarks>PREFER_NON_SMOKING,PREFER_HIGH_FLOOR</specialRemarks> <!-- preference from consumer -->
    <numberOfRooms>2</numberOfRooms>
    <bedChoice>1</bedChoice>
    <instantConfirm>false</instantConfirm>
    <requiredAction>CONFIRM_ROOM_SUCCESS/CONFIRM_ROOM_FAILURE</requiredAction>

    <room id="9986" name="特色房" broadband="FREE" payType="PREPAY"
          prices="200|200" status="ACTIVE|ACTIVE" counts="5|5"
        roomRate="180|180" taxAndFee="20|20" maxOccupancy="2" occupancyNumber="2"
        freeChildrenNumber="1" freeChildrenAgeLimit="8" instantConfirmRoomCount="3|3" wifi="FREE"
        checkinTime="" checkoutTime="" area="" guestType="ALL_GUEST" >

      <bookingRule userProperty="101,102,103" ip="1" >
            <bookingTime maxAdvanceDays="8" minAdvanceDays="2" minAdvanceHours="6" />
      </bookingRule>

      <bedType>
            <beds seq="1" code="SINGLE" desc="单人床" count="2" size="1.2m*2m" >
            </beds>
      </bedType>
      <meal>
            <breakfast count="2|2" desc="self-service breakfast" />
            <lunch count="0|0" desc="" />
            <dinner count="0|0" desc="" />
      </meal>
      <promotionRules>
    		<promotionRule code="FREE_UPGRADE" desc="免费升级" value="0"></promotionRule>
      </promotionRules>

      <extras><!-- optional -->
        <property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
        <property key="OTHER_KEY" value="XXXYYY" />
      </extras>


    </room>
    <customerInfos>
            <customerInfo seq="0" numberOfAdults="2" numberOfChildren="2" childrenAges="8|12" >
                <customer firstName="Ziqiang" lastName="Deng" nationality="CN" gender="male" />
            </customerInfo>
            <customerInfo seq="1" numberOfAdults="2" numberOfChildren="0" childrenAges="" >
                <customer firstName="XoXo" lastName="Li" nationality="CN" gender="male" />
            </customerInfo>
    </customerInfos>
    <qunarOrderInfo>
        <orderNum>j3gm141219163017759</orderNum><!-- unique order id at Qunar  -->
        <hotelSeq>osaka_2202</hotelSeq><!-- unique id for a hotel at Qunar -->
        <hotelName>阪急阪神大阪国际酒店(Hotel Hankyu International)</hotelName>
        <hotelAddress>19-19, Chayamachi, Kita-ku, Osaka 530-0013, Japan</hotelAddress>
        <cityName>大阪</cityName>
        <hotelPhone>0081-6-63772100</hotelPhone>
        <orderDate>2014-12-19 16:30:17</orderDate>
        <contactName>张三</contactName>
        <contactPhone>1381****818</contactPhone>
        <contactEmail>miao.****@Qunar.com</contactEmail>
        <payType>PREPAY</payType>
        <customerIp>103.24.27.9</customerIp>
        <invoiceCode>E</invoiceCode><!-- N=no require Y=paper invoice E=electronic receipt -->
    </qunarOrderInfo>
</bookingRequest>

<room> comes from <priceResponse> generated by price provider

<customerInfos>contains customer information.

<qunarOrderInfo> encompasses some of the order details for this reservation.

field name type required/optional description
totalPrice number required Total price
rmbPrice number required The price paid by the consumer in Chinese yuan.
promotionPrice number required If the room type quotation includes merchant discounts (configured on the Q platform), then this value is the original currency amount of the merchant discount
totalPriceAfterPromotion number required The original currency base price after discount. If the room type quotation includes a merchant discount (configured on the Q platform), then the base price after discount is the value minus the discount amount.
specialRemarks String required Used to label the user name and special instructions for each room; Example: Room 1:Guest 1 - YANG/CHENG,Guest 2 - XU/CHUBO;Room 2:Guest 1 - ZHANG/LUPING,Guest 2 - WANG/XIAOLAN;need smoking room,need adjoining rooms,need quiet room,need high floor room.
bedChoice String optional corresponds with <bedType> separated by , for each room
orderNum String required unique order id of Qunar, agents can use it to query orders
qunarOrderInfo/contactName String required name filled by consumer in order filling page
qunarOrderInfo/contactPhone String required Information is not fully provided at the time of booking, and the agent must confirm the order before he can see the complete content through the [Order Query API (Qunar Provided)]
qunarOrderInfo/contactEmail String required Information is not fully provided at the time of booking, and the agent must confirm the order before he can see the complete content through the [Order Query API (Qunar Provided)]
instantConfirm Boolean required Rooms marked as "true" are instantly confirmed, while "false" indicates that the agent needs to confirm the availability or non-availability of rooms through the [Order Operation API (provided by Qunar)]
requiredAction Enum optional If instantConfirm=false, then requiredAction will be either CONFIRM_ROOM_SUCCESS or CONFIRM_ROOM_FAILURE.

3.1.2 response

<?xml version="1.0" encoding="utf-8"?>
<bookingResponse>
    <qunarOrderNum>j3gm141219163017759</qunarOrderNum>
    <orderId>9987654</orderId>
    <result>SUCCESS</result>
    <msg></msg>
    <extras><!-- optional -->
        <property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
        <property key="OTHER_KEY" value="XXXYYY" />
    </extras>
</bookingResponse>
field name type required/optional description
qunarOrderNum String required Qunar Unique Order Number
orderId String required Order ID on the Agent's Side
result Enum required SUCCESS, FAILURE
msg String required If result="FAILURE", the agent needs to return remark information to facilitate the statistics of order refusals. Please try to return the msg in the following format:
01 - rooms_unavailable; insufficient room inventory
02 - price_mismatch; price does not match
03 - invalid_input; invalid request
04 - service_unavailable; service is not available
05 - unknown_error; unknown error

3.2 Order Operation (provided by qunar)

Sometimes, when the agent does not provide instant confirmation for a room, the agent needs to call this API to confirm whether the reservation is successful.

Agents using the order operation API need to notify Qunar operations to configure the agent's IP whitelist.

3.2.1 request

HTTP URL：http://sub_domain/api/ota/otaOpt?orderNum=xxx&hmac=xxx&opt

HTTP Param：orderNum, hmac, opt

HTTP Method：POST

The sub_domain and signKey are specified by Qunar for use by agents. There are IP and signKey restrictions when agents access this address.

For testing in the Beta environment (open platform), please refer to the open platform operation manual for testing instructions.

name/key type required/optional description
orderNum String required Qunar Order Number
opt enum required Reference OptCode
hmac String required hmac=md5(signKey+orderNum+opt), 32-bit lowercase; Example: signKey=asdf; orderNum=80291; opt=CONFIRM_ROOM_SUCCESS; hmac=md5(asdf80291CONFIRM_ROOM_SUCCESS); hmac=383266846e0d0dc4d17fa9906b28ae5d;
confirmationNumber String optional The number provided by the guest to the hotel upon check-in. If this information is available, please return it to Quanr. If this parameter is returned, the confirmationNumber needs to be added when generating the hmac, i.e.,
hmac=md5(signKey+orderNum+opt+confirmationNumber).

hmac example

package com.qunar.test;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.List;

public class MyHmacUtil {
    public static byte[] hashMD5(String str) {
        return (str == null) ? null : hashMD5(str.getBytes());
    }

    public static byte[] hashMD5(byte[] bytes) {
        try {
            return hash("MD5", bytes);
        } catch (NoSuchAlgorithmException e) {
            return null; // can't happen
        }
    }

    public static byte[] hash(String algorithm, byte[] bytes) throws NoSuchAlgorithmException {
        if (algorithm == null || bytes == null) {
            return null;
        }
        MessageDigest md = MessageDigest.getInstance(algorithm.toUpperCase());
        return md.digest(bytes);
    }

    public static String toHexString(byte[] byteArray, String delim) {
        if (delim == null) {
            delim = "";
        }
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < byteArray.length; i++) {
            if (i > 0) {
                sb.append(delim);
            }
            String hex = Integer.toHexString(byteArray[i] & 0x00ff).toLowerCase();
            if (hex.length() < 2) {
                sb.append("0");
            }
            sb.append(hex);
        }
        return sb.toString();
    }

    public static String toHexString(byte[] byteArray) {
        return toHexString(byteArray, null);
    }

    public static String getHmac(List<String> params) {
        StringBuffer buf = new StringBuffer("");
        for (String param : params) {
            buf.append(param);
        }
        return toHexString(hashMD5(buf.toString()));
    }
}

3.2.2 response

{ "statusCode": 6, "ret": true, "statusDesc": "cancel booking" }

{ "statusCode": 6, "ret": false, "errorMsg": ["订单当前状态不满足对应操作"], "statusDesc": "cancel booking" }
name/key type required/optional description
ret String required True = SUCCESS, false = FAILURE. Please use this value to judge the success of the operation.
errorMsg String optional error message
statusCode number required status code for the order
statusDesc String required status description for the order

3.2.3 important notes-opt

opt features additional characters description
CONFIRM_ROOM_SUCCESS confirm that the room is available for non-instantconfirm room,it needs agent to operate confirmation
CONFIRM_ROOM_FAILURE confirm that the room is not available for stay for non-instantconfirm room,it needs agent to operate confirmation
ORDER_CHANGE order information change confirmationNumber, currently only confirmation number changes are supported

3.3 Order Cancellation API (Provided by Agent)

When a consumer cancels a reservation, the order cancellation API needs to be invoked.

Regarding the cancellation logic for confirmed orders:

When a consumer cancels an order on the order details page, Qunar guarantees that the refund complies with the refund rules stated in the agent's room type quotation.

Sometimes, the refund rules do not allow for reservation cancellations, in which case a forced cancellation can be performed through the Qunar backend, with notification to the agent.

Regarding Order Cancellation:

At this stage, Qunar does not support order modifications. Consumers must first cancel the previous order and then make a new reservation.

Additionally, a <cancelRequest> request signifies the cancellation of the entire order. Qunar does not support the cancellation of partial nights within an order.

3.3.1 request

HTTP URL：http://base_url

HTTP Param：xml

HTTP Method：POST

Connection Timeout：3s, Request Timeout: 100s

The base_url is provided by the supplier and configured on the Qunar side.

<?xml version="1.0" encoding="utf-8"?>
<cancelRequest>
    <qunarOrderNum>j3gm141219163019999</qunarOrderNum>
    <orderId>9987654</orderId>
    <requiredAction>AGREE_UNSUBSCRIBE/REFUSE_UNSUBSCRIBE</requiredAction>
    <reason></reason>
    <extras><!-- optional -->
        <property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
        <property key="OTHER_KEY" value="XXXYYY" />
    </extras>
</cancelRequest>
name/key type required/optional description
qunarOrderNum String required which order to cancel
orderId String required order id of agent
requiredAction enum required when the order is being cancelled in Qunar backstage (condition: not satisfying the refund rule, but consumer requires to cancel the order,and after negotiation, the agent agrees to cancel), requiredAction=AGREE_UNSUBSCRIBE/REFUSE_UNSUBSCRIBE
reason String required reason for cancelling

3.3.2 response

<?xml version="1.0" encoding="utf-8"?>
<cancelResponse>
    <qunarOrderNum>j3gm141219163017759</qunarOrderNum>
    <orderId>9987654</orderId>
    <result>SUCCESS</result>
    <msg></msg>
</cancelResponse>
name/key type required/optional description
result enum required SUCCESS or FAILURE

3.4 Order Query API (Provided by Agent)

In the event of an exception when Qunar invokes the agent's booking API, Qunar needs to access this API with the Qunar order number to confirm whether the agent has successfully generated the order before retrying.

3.4.1 request

HTTP URL：http://base_url

HTTP Param：xml

HTTP Method：GET

Connection Timeout：3s, Request Timeout: 10s

The base_url is provided by the supplier and configured on the Qunar side.

<?xml version="1.0" encoding="utf-8"?>
<wrapperOrderQueryRequest>
    <qunarOrderNum>j3gm141219163017759</qunarOrderNum><!-- required -->
    <orderId>12345678</orderId><!--  orderId optional -->
    <extras><!-- optional -->
        <property key="TOKEN" value="ASDFJJJJ9999XXXXYYY" />
        <property key="OTHER_KEY" value="XXXYYY" />
    </extras>
</wrapperOrderQueryRequest>
name/key type required/optional description
qunarOrderNum String required order id of Qunar
orderId String optional

3.4.2 response

The agent needs to return all node information contained within each bookingRequest.

If there is no corresponding order data, please return an empty node <wrapperOrderQueryResponse/>.

<?xml version="1.0" encoding="utf-8"?>
<wrapperOrderQueryResponse>
    <orderInfo>
        <orderNum>j3gm141219163017759</orderNum><!-- unique order id at Qunar  -->
        <orderId>9987654</orderId><!-- unique order id at wrapper -->
        <payType>PREPAY</payType>

        <status>CONFIRMED_SUCCESS</status>

        <hotelSeq>osaka_2202</hotelSeq><!-- unique id for a hotel at Qunar -->
        <hotelName>阪急阪神大阪国际酒店(Hotel Hankyu International)</hotelName>
        <hotelAddress>19-19, Chayamachi, Kita-ku, Osaka 530-0013, Japan</hotelAddress>
        <cityName>大阪</cityName>
        <hotelPhone>0081-6-63772100</hotelPhone>
        <orderDate>2014-12-19 16:30:17</orderDate>
        <contactName>张三</contactName>
        <contactPhone>1381****818</contactPhone>
        <contactEmail>miao.****@Qunar.com</contactEmail>
        <customerIp>103.24.27.9</customerIp>
        <invoiceCode>E</invoiceCode><!-- N不需要 Y纸质收据 E电子收据 -->
        <invoice type="" title="somebody" content="" dispatch=""
             contactName="" contactPhone="" province="" city="" area="" detailAddress="" fee="" />
        <hotelId>16166</hotelId>
        <checkin>2014-12-29</checkin>
        <checkout>2014-12-30</checkout>
        <totalPrice>400</totalPrice><!--  totalPrices = sum(prices) * numberOfRooms -->
        <currencyCode>USD</currencyCode>
        <room id="9987" prices="200|200" roomRate="180|180" taxAndFee="20|20" >
            <bedType>
                <beds seq="1" code="5" desc="单人床" count="2" size="" />
                <beds seq="2" code="0" desc="大床" count="1" size="" />
            </bedType>
            <meal>
                <breakfast count="2|2" desc="self-service breakfast" />
                <lunch count="0|0" desc="" />
                <dinner count="0|0" desc="" />
            </meal>
            <promotionRules>
    			<promotionRule code="FREE_UPGRADE" desc="免费升级" value="0"></promotionRule>
            </promotionRules>
        </room>
        <customerArriveTime>16:00-18:00</customerArriveTime>
        <specialRemarks>PREFER_NON_SMOKING,PREFER_HIGH_FLOOR</specialRemarks>
        <customerInfos>
                <customerInfo seq="0" numberOfAdults="2" numberOfChildren="2" childrenAges="8|12" >
                    <customer firstName="Ziqiang" lastName="Deng" nationality="CN" gender="male" />
                </customerInfo>
                <customerInfo seq="1" numberOfAdults="2" numberOfChildren="0" childrenAges="" >
                    <customer firstName="XoXo" lastName="Li" nationality="CN" gender="male" />
                </customerInfo>
        </customerInfos>
    </orderInfo>

</wrapperOrderQueryResponse>

3.4.3 ORDER STATUS ENUMERATION

enum value description
NEW_ORDER initial status, means that the agent just received this reservation, waiting for process
CONFIRMED_SUCCESS confirmed room(s) for consumer, ready for checkin
CONFIRMED_FAILURE confirmed no room for consumer, booking failed
CANCELED this reservation is cancelled by agent
CHECKED_IN consumer has checked in
CHECKED_OUT consumer has checked out
NO_SHOW the hotel confirmed consumer no show

3.5 Order Query API (Provided by Qunar)

Special Note: For orders that have not been confirmed as bookable, the consumer's contact information has been mosaicked.

3.5.1 request

HTTP URL：http://sub_domain.qunar.com/api/ota/qunarOrderQuery?orderNums=xxx&hmac=xxx

HTTP Param：orderNums, hmac

HTTP Method：GET

sThe sub_domain is specified by Qunar, and there are IP and signKey restrictions when accessed by agents.

field name type required/optional description
orderNums String required one or more(100 at most) orderNum, eg. j3gm141219163017759,j3gm141219163017760
hmac String required hmac = md5(signKey || orderNums), 32 bit, lowercase, "||" is the connector, eg. signKey=asdf, orderNums=xxxx, hmac = md5(asdfxxxx)

3.5.2 response

<?xml version="1.0" encoding="utf-8"?>
<qunarOrderQueryResponse>
    <orderInfo>
        <orderNum>j3gm141219163017759</orderNum><!-- unique order id at Qunar  -->
        <orderId>9987654</orderId><!-- unique order id at wrapper -->
        <payType>PREPAY</payType>
        <qunarStatus>CONFIRMED_SUCCESS</qunarStatus>
        <roomNum>2</roomNum>
        <cityName>大阪</cityName>
        <hotelSeq>osaka_2202</hotelSeq>
        <hotelName>阪急阪神大阪国际酒店(Hotel Hankyu International)</hotelName>
        <hotelAddress>19-19, Chayamachi, Kita-ku, Osaka 530-0013, Japan</hotelAddress>
        <hotelPhone>0081-6-63772100</hotelPhone>
        <orderDate>2014-12-19 16:30:17</orderDate>
        <contactName>张三</contactName>
        <contactPhone>1381****818</contactPhone>
        <contactEmail>miao.miao@Qunar.com</contactEmail>
        <customerIp>103.24.27.9</customerIp>
        <invoiceCode>E</invoiceCode><!-- N不需要 Y纸质收据 E电子收据 -->
        <hotelId>16166</hotelId>
        <checkin>2014-12-29</checkin>
        <checkout>2014-12-30</checkout>
        <roomId>1010162|327223</roomId>
        <currencyCode>USD</currencyCode>
        <customerArriveTime>16:00-18:00</customerArriveTime>
        <specialRemarks>PREFER_NON_SMOKING,PREFER_HIGH_FLOOR</specialRemarks>
        <customerInfos>
                <customerInfo seq="0" numberOfAdults="2" numberOfChildren="2" childrenAges="8|12" >
                    <customer firstName="Ziqiang" lastName="Deng" nationality="CN" gender="male" />
                </customerInfo>
                <customerInfo seq="1" numberOfAdults="2" numberOfChildren="0" childrenAges="" >
                    <customer firstName="XoXo" lastName="Li" nationality="CN" gender="male" />
                </customerInfo>
        </customerInfos>

    </orderInfo>

    <orderInfo>
        ...
    </orderInfo>
</qunarOrderQueryResponse>

4. Enumerations

4.1 BedType

BedTypeCode
SINGLE
DOUBLE
BUNK
DORM_BED
TATAMI
WATER_BED
ROUND_BED
FOLDING_BED
BABY_COT
CONNECTED_BED
OTHERS

4.2 FeeMode

FeeMode
FREE
CHARGE
NONE
UNKNOWN
PART_CHARGE
PART_SUPPORT_AND_FREE
PART_SUPPORT_AND_CHARGE
PART_SUPPORT_AND_PART_CHARGE

4.3 RefundType

RefundType
NO_DEDUCTION
DEDUCT_BY_PERCENT
DEDUCT_BY_AMOUNT
DEDUCT_FIRST_NIGHT

4.4 UnitOfCharge

UnitOfCharge
PER_TIME
PER_DAY
PER_ITEM
PER_PERSON_TIME
PER_HOUR

4.5 OptCode

OptCode
CONFIRM_ROOM_SUCCESS
CONFIRM_ROOM_FAILURE
ORDER_CHANGE

4.6 GuestType

GuestType
ALL_GUEST
DOMESTIC_GUEST
CHINESE_GUEST
FOREIGN_GUEST

5. notes of timeout auto rejection(local time)

type of order guarantee completion time confirmation time operation button in platform for agent Hota&QTA order log
room of yesterday 00：00-06:00 within 60 minutes agent can confirm or refuse the order in platform for agent
room of yesterday 00：00-06:00 over 60 minutes Automatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming
room of today 9：00---24:00 within 60 minutes agent can confirm or refuse the order in platform for agent
room of today 9：00---24:00 over 60 minutes Automatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming
room of today 00:00---9:00 before 11 a.m. agent can confirm or refuse the order in platform for agent
room of today 00:00---9:00 after 11 a.m. Automatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming
normal room 9:00---17:00 before 11 p.m. agent can confirm or refuse the order in platform for agent
normal room 9:00---17:00 after 11 p.m. Automatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming
normal room 17：00---24:00 before 12 a.m. on the next day agent can confirm or refuse the order in platform for agent
normal room 17：00---24:00 after 12 a.m. on the next day Automatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming
normal room 00:00-9:00 before 12 a.m. checkIn today agent can confirm or refuse the order in platform for agent
normal room 00:00-9:00 after 12 a.m. checkIn today agent can confirm or refuse the order in platform for agentAutomatic confirmation of overtime rejection of orders. There are no "confirm room" and "refuse bill" buttons in the agent's background. The order status changes to "rejection". The order has been rejected. The reason is: automatic rejection because of overtiming

6. How to Conduct Testing

Please use the supplier development platform, and request the platform account from the corresponding Qunar product or operation personnel.

7. FAQ

Question 1: How frequently is the hotel list updated?

It is typically updated once a day, and can also be manually triggered. If you need to update a large amount of hotel information, please contact the relevant personnel.

Question 2: Issues with hotel aggregation?

After Qunar synchronizes the hotels from agents, it aggregates them onto Qunar's basic hotel listings.
Some hotels cannot be aggregated due to reasons such as excessively long or illegal hotel names or addresses.
If aggregation issues arise, please first investigate them on the open platform.
If problems persist, please contact the relevant operations personnel.

Question 3: Why aren't quotes displayed?

Agents should first confirm whether the hotel has been successfully aggregated, and then test whether the quotes meet the requirements on the open testing platform. If there are no issues, please contact the relevant Qunar operations personnel for assistance.

Question 4: Issues with booking conversion rate?

The booking success rate refers to the number of successful entries into the order filling page after clicking on "book" divided by the total number of booking attempts, excluding those where users change the check-in date, room number, or other quote requests after entering the order filling page. If an agent's booking success rate falls below the average of 80%, their product may be taken offline. Therefore, agents should avoid situations such as timeouts and no quotes in this process.

Question 5: Why has the product been taken offline?

The agent's response to quote requests on the order page has timed out (exceeding 10 seconds) or the agent is indeed out of rooms.

Question 6: Why are orders rejected?

There are usually three reasons:

The agent confirms that there are no available rooms.
Qunar places an order with the agent, but fails to call the agent's order reservation API (due to network anomalies, etc.).
Before Qunar places an order with the agent, it performs a quote verification and fails to retrieve the quote.