Pre-Book

13 min

Introduction

This document provides the specification for the Bonotel Pre-Book API method, which would allow customers to verify that a specific hotel, room, rate plan and occupancy is still available and to verify the rate before they attempt the booking. This method bypasses caching and returns the current rate and status. If you have any questions, contact us at: [email protected]

Traffic Volume

Bonotel will be monitoring and tracking the Pre-Book requests per customer per day to ensure that the Pre-Book method is only used right before making a reservation request. For example, if your account normally generates 20 reservation requests in a day, we expect ~20 Pre-Book requests. Any excessive use of the Pre-Book method will be throttled.

Requirements

Before making a Pre-Book request, you would need to have already posted an availability request and extracted out the necessary details from the response to generate a Pre-Book request.

Format

To help customers leverage existing code, we have modeled the Pre-Book method after our reservation method format. The primary difference is that we remove the guest names and comments from the request. The response will include a status per room, the total rate per room and for the booking, and any exclusive hotel fees. A room can have zero or more hotel fees regardless of the fee type.

Request

Endpoint:

/PreBookCheck.do

Parent/Group	Element/ Attribute Name	Type	Req.	Data/Format	Description
preBookRequest		Group	Yes		Root element
preBookRequest	control	Group	Yes		Authentication group
control	userName	Element	Yes	String	Your username
control	passWord	Element	Yes	String	Your password
preBookRequest	requestDetails	Group	Yes		Pre-book request details
requestDetails	timeStamp	Attribute	Yes	ISO 8601	UTC: YYYYMMDDThh🇲🇲ss
requestDetails	checkIn	Element	Yes	MM-DDD-YYY	Check-In date
requestDetails	checkOut	Element	Yes	MM-DDD-YYY	Check-Out date
requestDetails	noOfRooms	Element	Yes	Integer	Number of rooms – 9 max.
requestDetails	noOfNights	Element	Yes	Integer	Number of nights – 30 max
requestDetails	hotelCode	Element	Yes	Integer	hotelCode from Avail Response
requestDetails	total	Element	Yes	Decimal	Total including all rooms
total	currency	Attribute	Yes	ISO 4217	Currency, usually USD
requestDetails	totalTax	Element	Yes	Decimal	Total including all rooms - usually 0.00
totalTax	currency	Attribute	Yes	ISO 4217	Currency, usually USD
requestDetails	roomData	Group	Yes		Room Block, 9 max.
roomData	roomNo	Element	Yes	integer	Room Number, first is 1
roomData	roomCode	Element	Yes	integer	ID from Avail Response
roomData	roomTypeCode	Element	Yes	integer	ID from Avail Response
roomData	bedTypeCode	Element	Yes	integer	ID from Avail Response
roomData	ratePlanCode	Element	Yes	integer	ID from Avail Response
roomData	noOfAdults	Element	Yes	integer	Num of adults: 1 or more
roomData	noOfChildren	Element	Yes	integer	Num of children: 0 or more
roomData	childAges	Group	Yes		Ages for children that are <= 18
childAges	childAge	Element	Yes	Integer	One age per child, only required for children.
roomData	total	Element	Yes	Decimal	Total for current room
total	currency	Attribute	Yes	ISO 4217	Currency, usually USD
roomData	totalTax	Element	Yes	Decimal	Total tax for current room - usually 0.00
totalTax	currency	Attribute	Yes	ISO 4217	Currency, usually USD

Response

Parent/Group	Element/ Attribute Name	Type	Required	Data/ Format	Description
preBookResponse		Group	Yes		Root element
preBookResponse	status	Attribute	Yes	Y/N	Y=1 or more successful, N=none successful
preBookResponse	roomDetails	Group	Yes
roomDetails	room	Element	Yes	Y/N	Room was successful or not. Note, if a room returns with a rate change, it is successful, it just has a new rate.
room	roomNo	Attribute	Yes	Integer	The number of the room, starting with 1.
roomDetails	total	Element	No	Decimal	Total rate for the room. Compare against the availability rate to check for rate changes.
total	currency	Attribute	No	ISO 4217	Currency, usually USD
roomDetails	totalTax	Element	No	Decimal	Total tax for current room - usually 0.00
totalTax	currency	Attribute	No	ISO 4217	Currency, usually USD
roomDetails	hotelFees	Group	No		All hotelFee groups
hotelFees	hotelFee	Group	No		A specific hotelFee with elements
hotelFee	feeType	Element	No	String	Amenity, Cleaning, National Park Entrance, Resort, Security Deposit
hotelFee	feeMethod	Element	No	String	Only "Exclusive" currently
hotelFee	requiredFee	Element	No	Yes/No
hotelFee	feeTotal	Element	No	Decimal	Inclusive of any taxes

Error Response – No Rooms Returned

Parent/Group	Element/ Attribute Name	Type	Required	Data/Format	Description
preBookResponse		Group	Yes		Root element
preBookResponse	Status	Attribute	Yes	Y/N	Y=1 or more successful, N=none successful
preBookResponse	errors	Group	No		Only one error will ever return
errors	code	Element	No	String	See table of Result Codes
errors	description	Element	No	String	Description of result code

Response

<?xml version="1.0" encoding="utf-8" ?>
<preBookResponse status="N">
	<errors>
		<code>P3</code>
		<description>Inventory has expired</description>
	</errors>
</preBookResponse>

Code Example

Request

Method: /PreBookCheck.do

<?xml version="1.0" encoding="utf-8" ?>
<preBookRequest>
	<control>
		<userName>{{username}}</userName>
		<passWord>{{password}}</passWord>
	</control>
	<requestDetails timeStamp="20220120T11:07:33">
		<checkIn>01-Jan-2023</checkIn>
		<checkOut>02-Jan-2023</checkOut>
		<noOfRooms>1</noOfRooms>
		<noOfNights>1</noOfNights>
		<hotelCode>79</hotelCode>
		<total currency="USD">390.10</total>
		<totalTax currency="USD">0</totalTax>
		<roomData>
			<roomNo>1</roomNo>
			<roomCode>131110</roomCode>
			<roomTypeCode>131</roomTypeCode>
			<bedTypeCode>10</bedTypeCode>
			<ratePlanCode>131</ratePlanCode>
			<noOfAdults>1</noOfAdults>
			<noOfChildren>2</noOfChildren>
			<childAges>
				<childAge>4</childAge>
				<childAge>6</childAge>
			</childAges>
			<total currency="USD">390.10</total>
			<totalTax currency="USD">0</totalTax>
		</roomData>
	</requestDetails>
</preBookRequest>

Response

Typical Response

<?xml version="1.0" encoding="utf-8" ?>
<preBookResponse status="Y">
	<roomDetails>
		<room roomNo="1">N</room>
	</roomDetails>
	<roomDetails>
		<room roomNo="2">Y</room>
		<total currency="USD">390.10</total>
		<totalTax currency="USD">0</totalTax>
		<hotelFees>
			<hotelFee>
				<feeType>Resort</feeType>
				<feeMethod>Exclusive</feeMethod>
				<requiredFee>Yes</requiredFee>
				<feeTotal>148.65</feeTotal>
			</hotelFee>
		</hotelFees>
	</roomDetails>
</preBookResponse>

Response With Varying Results

It is possible to see a response where one or more rooms are available and one or more other rooms are not available.

Please take note of this example if you support booking two or more rooms. The top level status setting is ‘Y’ here because at least one of the requested rooms was available:

<?xml version="1.0" encoding="utf-8" ?> <preBookResponse status="Y"> <roomDetails> <room roomNo="1">N</room> </roomDetails> <roomDetails> <room roomNo="2">Y</room> <total currency="USD">390.10</total> <totalTax currency="USD">0</totalTax> <hotelFees> <hotelFee> <feeType>Resort</feeType> <feeMethod>Exclusive</feeMethod> <requiredFee>Yes</requiredFee> <feeTotal>148.65</feeTotal> </hotelFee> </hotelFees> </roomDetails> </preBookResponse>

Error Response

<?xml version="1.0" encoding="utf-8" ?> <preBookResponse status="N"> <errors> <code>P3</code> <description>Inventory has expired</description> </errors> </preBookResponse>

Response Codes

Code	Description
P1	Unspecified error. Please contact customer support.
P2	User ID not supplied or not valid.
P3	Inventory has expired.
P6	Arrival or Departure Date format incorrect.
P7	Erroneous or Incomplete Data in request.
P8	Incorrect Hotel Id / Room Type Id/ Bed Type Id/ Rate Plan Id Combination.
P9	Occupancy Details do not match with the Number of Rooms.
P13	No XML input detected.
P14	This request cannot be confirmed due to restrictions.
P15	The number of nights does not match the check in date and the checkout date.
P16	Access has been suspended.
P18	Room No: (#) cannot be occupied with the given number of adults and children.
P20	Reservations require a minimum of one adult per room.
P21	Exceeding request limit. Please contact support.
P24	Error making this request. Please try again later.
P27	Please check, rate must be more than zero.
P28	Hotel does not have a valid contract for check in and check out date.
P29	Room net rate is less than the threshold value.