Certification process

The following is a quick reference to the certification process. In this section we will give you all necessary information to complete the Certification process, which will ensure that your integration is ready to go Live.

Please, consider that carefully reading this section and planning you implementation ahead knowing what is going to be specifically requested by us, can lead to a much better experience and a sooner reaching of the goal: Being Live and ready to sell.

Of course, you can contact us with any doubts or questions at: apitude@hotelbeds.com.

Certification goals

The Certification process intention is to test and ensure that your XML integration is performed correctly, this means, that functionality and implementation of the relevant and mandatory information are done correctly and without errors. All of this is focused to avoid issues with the final consumer, or he/she being misled by any incorrect information or not desirable API uses.

Before starting the certification process, make sure you have followed the Best Practices. This will speed up the process and avoid problems afterwards. 

Having said that, our certification process will look at 5 different areas:

  1. Technical
  2. Workflow
  3. Availability, CheckRate and Confirmation
  4. Voucher
  5. Content
  6. Live environment

The next sections will explain each of these points, but before we start with the check list , let us explain you how to request the certification process:

How to request certification process:

Once you have finished you development and review next sections of (Workflow, Availability, CheckRate and Confirmation, Content, Voucher and Live environment) , you should contact us (apitude@hotelbeds.com) and request the certification process. Remember to send us following information on your request:

  • Workflow or your integration with us. If your system has more than one distribution channel, please explain each channel workflow in case there is any difference between them.
  • Commercial decisions: It is important that we are made aware of commercial decisions before the verification process begins like: Don't include specific destinations, room types, board types, hotels or whatever on availability results or booking confirmation.
  • URL for the certification.
  • User and password if it is needed.
  • Payment information if it is needed.
  • In case that there isn’t common language, provide a guide.
  • In case there you are integrated with more suppliers, let us know how to check only Hotelbeds product.
  • Other aspects to consider import on certification process.

1 - Technical

The technical implementation review is very simple: we will review how you have configured your requests and how well you are using GZIP compression. The controls here are to ensure that you are performing and executing the requests in an expected manner.

2 - Workflow

The workflow stablishes the quantity and correct order of calls to the system in order to perform different operations available.

Take a look to the following diagram with the simplest workflow possible:

The explanation of this workflow is:

If a client would like to reserve an hotel, there are some basic information that it is needed in order to allow response him, so by knowing some bases like checkIn, checkOut, hotels and paxes, then you should ask APITude what availability and prices are for these criteria. This is performed by the first step: Request availability (/hotels).

Once you get availability, then you should perform CheckRate call only when the rate selected is "rateType = RECHECK" otherwise you should avoid this call (/checkrates).

Finally, the confirmation is done by the Confirmation call (/bookings).

Following points will be reviewed on certification process, so please, check it before request certification:


2.1 - Are you using the correct workflow?

The correct workflow for a standard booking is as follows:

(1) First send an availability call, then (2) use checkrates call - if applies - and (3) finally call booking request.

A typical error that is not allowed and is checked on the certification is:

Before checkrates, availability is called again. In the same way before booking request, availability and checkrates are calling againg. Thus, the client is calling our system like: (1) Availability, (2) Availability, (3) checkrate, (4) Availability, (5) checkrate, (6) Booking.

Please, avoid this behavior.

Minimize Availability requests  

2.2 - The availability request should not be repeated in the remaining steps to make a reservation (CheckRate and Booking request)

The correct workflow minimizes availability requests. Please, do not repeat the same availability request after checkrate of booking request. This point is related to 1.1

2.3 - As many hotels as possible should be reported in the same call, without exceeding the limit of 2000 hotels per call.

The correct workflow minimizes availability requests. Please, inform on the availability call as many hotels as possible. Remember that you are able to inform up to 2000 hotels per call.

For example (take special attention to hotels tag):

<availabilityRQ […] sourceMarket="UK">
	<stay checkIn="2016-06-15" checkOut="2016-06-16"/>
		<occupancy rooms="1" adults="2" children="0"/>

2.4 - All rooms requested for a reservation must be reported on the same call.

Please, inform on the same availability call all the rooms required for a booking.

For example (take a look to occupancies tag. This example request one room for two adults and another room for three adults and one child):

<availabilityRQ […] dailyRate="true" sourceMarket="UK">
	<stay checkIn="2016-06-15" checkOut="2016-06-16"/>
		<occupancy rooms="1" adults="2" children="0"/>
		<occupancy rooms="1" adults="3" children="1">
				<pax type="CH" age="7"/>

Minimize CheckRates request  

2.5 - CheckRate call should only be made in case the rate selected is "rateType=RECHECK"

On availability response, all rates has the attribute rateType. Then if it contains “RECHECK”, then it is required to perform a CheckRate call, otherwise it is not required this call.

Please, take a look to the following example (availability response) where rateType="BOOKABLE". In case  you would like to book this rateKey, then you can call directly to booking confirmation:

<availabilityRS [..]>
	<hotels checkIn="2017-05-17" total="1" checkOut="2017-05-18"><hotel code="200728" […]>
			<room code="DBL.SU" name="DOUBLE SUPERIOR">
					<rate rateKey="20170517|20170518|W|296|200728|DBL.SU|CGW-TODOS RO|RO||1~2~0||N@33F4BEFBBB5E405780BA1A26045EDE22" rateClass="NOR" rateType="BOOKABLE" […]>

2.6 - It should be informed as most rates as possible at the same call, without exceeding the limit of 10 rates per call.

CheckRate allow introduce until ten rates, so, in case you have more than one rate that you need to call checkrate, you can group it on one simple call.

Please, take a look to the following example:

<checkRateRQ […]>
   <room rateKey="20170517|20170518|W|296|200728|DBL.SU|CGW-TODOS RO|RO||1~2~0||N@91FC721D47814E5E9439479C8D741314"/>
   <room rateKey="20170517|20170518|W|296|200728|JSU.ST|CGW-TODOS RO|RO||1~2~0||N@91FC721D47814E5E9439479C8D741314"/>

3 - Availability, CheckRate and Confirmation

This section will show you some peculiarities, best practices and other rules that are focused to obtain a better booking conversion or system performance. Some of these points are mandatory (indicated) to be accomplished, and others are just a recommendation. Please take a look to it before request certification process

3.1 - Does your system show all "basic" information?

Check that the entire product that we offer is correctly displayed; including prices, number of rooms, dates, hotels, type of board, type of room, hotel rate (stars, keys, villas, residence), and also the correct implementation and display of pagination.

It is important that we are aware of any commercial reason for not including all room types, all board types and all hotels in order to prevent highlighting this as an issue.

3.2 - Does your system allow choose number of paxes?

This point is not mandatory to accomplish, but it is nice to have if you would like to increase your booking ratio conversion.

Please, take a look to the following availability request example that request one room for two adults and another room for three adults and one children. 

<availabilityRQ […] dailyRate="true" sourceMarket="UK">
	<stay checkIn="2016-06-15" checkOut="2016-06-16"/>
		<occupancy rooms="1" adults="2" children="0"/>
		<occupancy rooms="1" adults="3" children="1">
				<pax type="CH" age="7"/>

3.3 - Does your system allow indicate number of children?

This point is not mandatory to accomplish, but it case you implement it, it is mandatory to indicate the children age.

Please note the attribute age given on the child pax node of the following example:

<availabilityRQ […] dailyRate="true" sourceMarket="UK">
	<stay checkIn="2016-06-15" checkOut="2016-06-16"/>
		<occupancy rooms="1" adults="3" children="1">
				<pax type="CH" age="7"/>

3.4 - Does your system allow multi-room bookings?

Multi-room booking means confirm more than one room at same booking, it is, performs a booking with different kind of rooms.

Use "availabilityRQ/occupancies/occupancy/@rooms" for a multiple room request of the same occupancy.

We recommend splitting the occupancy nodes in case of rooms with different occupancy or rooms with the same occupancy with children ranging in different age. In these cases, the occupancy node needs to be duplicated. 

3.5 - Does your system use opaque rates?

Opaque rates only should be used when they are combined with other products like fly ticket, transfers, car rental…it is, when booking price cannot be determined as it includes other services.

Certification process verifies that, in case you use the opaque rates, you follow this rule. So this is a mandatory point to be accomplished in case you use opaque rates.

Note: An opaque rate is that one that contains attribute packaging of rate tag set to true. Example:

<rate rateKey="[…]" packaging="true" […]>

3.6 - Does your system use Source market?

Source market is used on request call in order to inform Hotelbeds that you are requesting prices for specific market. This is useful because there are hotels that has lower prices depending of the source market of final client.

This tag should be informed at availability request in case you would like to obtain this information:

<availabilityRQ sourceMarket="XX" […]>

Certification process verifies that, in case you request it, you are using this prices only for the source market requested. For instance you cannot give at Spanish market prices obtained with the source market of United Kingdom.

3.7 - Does your system use filters?

APITude has a huge range or filters that you are able to use. Implement all of theme it is not mandatory, but it is recommended at least has some of theme. Certification process will check that are working correctly only those filters that you implement.

Following there is an example of a availability call with almost all available filters:

<geolocation longitude="2.646633999999949" latitude="39.57119" radius="20" unit="km"/>
<boards included="true">
<rooms included="TRUE">
	<review type="TRIPADVISOR" maxRate="5" minReviewCount="3"/>
	contract="CG-FIT B2B"/>

3.8 - Does your system show Hotelbeds cancellation policies?                                              

Hotelbeds, through the XML integration, provides cancellations policies that will be applied to all reservations. However, you are free to display them and / or apply them to reservations with your clients without altering or modifying such policies with Hotelbeds.

In case you would like to use Hotelbeds cancellation policies, we are going to check it in order to verity that there is no errors on your implementation, otherwise, please inform us that you are not using it and thus we will not take into account on certification process.

Cancellation policies are returned on availability response at rate tag:

	<cancellationPolicy amount="50.01" from="2017-05-14T23:59:00-05:00"/>

Notice that those rates that the attribute rateType is “RECHECK" then you need to perform a CheckRate call to obtain its cancellation policies.

NOTE: The dates and times used to determine  cancellation fees  depend on the destination of the booking, not the customer’s local time.

3.9 - Does your system show rate comments or contact remarks?

An example of ratecomment is: “Hotel insurance has a cost, and must be paid voluntarily in the hotel…”.

Certification checks that these comments are shown to final client in any step before the confirmation.

You are getting it at the availability response at rate tag with the attribute “rateCommentsId”. Then you should use the ratecomments of ContentAPI in order to know what these identifications returned at rateCommentsId tag means.

For example:

<rate rateCommentsId="296|5096|0" […]>

Notice that those rates that the attribute rateType is “RECHECK" then you need to perform a CheckRate call to obtain its rate comments.

3.10 - Does your system work with Liberate?

Liberate model means that the booking is paid by final customer at hotel. Not all hotels or rates has this feature, but when for those that use it ("paymentType" = "AT_HOTEL"), it is mandatory accomplish following points (only for Liberate model/rates):

  • Show that the booking is payable at destination.
  • Show along the booking process same price.
  • The hotel currency.
  • Show the final price that should be paid at destination.

4 - Voucher

For all confirmed reservations, it is mandatory to generate a voucher containing all the information regarding the reservation and allow the client (either if it's B2B or B2C) to get it easily.

4.1 - Does your system send voucher for confirmed bookings?

The voucher is the document that the final user uses to confirm or witness (vouch) of its booking, so, it is mandatory send it to final user.

4.2 - Hotel information

Please, check that the following information appear at the voucher (and it is correctly informed):

  • Hotel name (mandatory).
  • Hotel category (recommended).
  • Hotel address (mandatory).
  • Hotel destination name (recommended).
  • Hotel phone number (recommended).

4.3 - Paxes information

Please, check that the following information appear at the voucher (and it is correctly informed). All fields are mandatory:

  • Holder name.
  • At least one pax name per room. In case of reservations with only one room, the holder name is sufficient            .
  • If children are present, children ages should be informed. 

4.4 - Booking information

Please, check that the following information appear at the voucher (and it is correctly informed):

  • Hotelbeds booking reference (mandatory).
  • Agency reference (recommended).
  • CheckIn date (mandatory).
  • CheckOut date (mandatory).
  • Room type (mandatory)
  • Board type (mandatory).
  • Rate comments (mandatory if applicable).

4.5 - Payment information

For non Liberate bookings:     

  • Don’t show the price of the reservation (recommended)
  • Shown:

Payable through XXX, acting as agent for the service operating company, details of which can be provided upon request. VAT: YYY Reference: ZZZ" (mandatory).

Please, substitute XXX, YYY and ZZZ for the correct value.

For Liberate bookings:

  • Show the following message:

Total amount to be paid at the hotel: XXX.XX EUR.

The payment will be done in the currency stated. As a reference, the Final Sales Price in the client currency is YYY.YY GBP (shown for informational purposes only and calculated at booking creation date).

The total amount of the stay will be due at the hotel in the indicated currency. Any complaint needs to be reported directly to the hotel. During the reservation process, a verification of the credit card has been done by charging 1EUR, which will automatically be refunded at the confirmation of the reservation.

Taxes: VAT included, Supplement per service included, local/touristic taxes not applicable.

The accommodation establishment may verify the validity of the credit card by (pre) authorizing for the amount of the cancellation fees or may charge the applicable cancellation fees as a guarantee from the moment those apply. If no cancellation is made, these fees will be discounted from the payment at the hotel.

If the hotel cannot verify the credit card, it has the right to cancel the booking. If the booked rate has a Non Refundable Rate, the hotel is entitled to charge the entire amount of the booking on the credit card upon receipt of the booking confirmation. Non Refundable bookings cannot be amended nor cancelled and will be charged for the entire amount of the booking.

Please, substitute XXX, and YYY for the correct value.

5 - Content

Content API provides the right information regarding hotel content. It includes category, images, descriptions, facilities, contract remarks, room types and much more content information. Hotelbeds encourages you to use it, but it is not mandatory. Please, let us know what aspects of our content API you have implemented in order to check its right performance. 

Take into account that data provide by ContentAPI must be stored in your system. Of course you can update it as frequently as required but we recommend updating your system database at least once a week.

Note that if a hotel does not appear on your database because it was created after the last ContentAPI update of your database, use the hotel detail function to display all information about a hotel (address, descriptions, facilities, images, room facilities, etc.), including facilities with an extra fee.

5.1 - Do you use only HotelBeds contet?

Please, let us know if  you use only HotelBeds hotel content or you have other hotel content providers (source). In case you use both soruces, we need to know what kind of content from Hotelbeds are you using in order to certificate only this information.

5.2 - Category

  • Does your system show different category types?

Content API provides different categories like stars, keys, apart-hotels.

  • Does your system show different category values?

Content API provides different categories values. For example, hotels has from one to five stars, or apartments from one to five keys.

5.3 - Images

  • Does your system show images?
  • Are these images correct (showing the images of the same hotel of the description)?
  • How many images is your system showing (are you showing all available images)?

5.4 - Facilities

  • Does your system show hotel facilities?
  • Does your system show payment facilities?

For example, at hotel call of Content API you can get follow information:

	"facilityCode": 330,
	"facilityGroupCode": 70,
	"description": {
		"content": "Garage"
	"order": 1,
	"indFee": true,
	"indYesOrNo": true

This example, extract from the hotel code 271, the indFee = true indicates it's a paid facility.

  • Does your system show "Mandatory" facilities?

A "Mandatory" facility is always returned on XML Content API (we always request our hotels to inform it if they have it or not) and it can be present or not at the hotel. For example:

	"facilityCode": 250,
	"facilityGroupCode": 70,
	"description": {
		"content": "Wired Internet"
	"order": 1,
	"indFee": false,
	"indYesOrNo": false

At this example, as tag indYesOrNo is shown, it means that this facility (wired interned) always is returned for all hotels, but at this case, it is not a facility of the hotel (it is not present) due to its value is false.

5.5 - Other

  • Does your system show hotel description?
  • Does your system show contract remarks?
  • Does your system show Room types?
  • Does your system show board types?
  • Does your system show points of interest?

6 - Live environment

Once you are certificated, everything is ready to sell and it is the moment for last check:

6.1 - Are you able to perform a booking on live environment?

Once you have live APIkeys, please confirm a reservation in live environment (dates six months in advance, 2 adults/2 children) and send us both voucher and price. Bear in mind that you will have to cancel the booking afterwards, otherwise you would be charged. Check with us before cancelling (point 5.2).

For this booking, do not select a NRF contract or any other rate that carryout cancelation fees as NRF rates carryout cancellation cost.

IMPORTANT REMARK: Any booking or action that you perform on live environment is real, it is, hotel will be informed about it and in case it has cancellation policies, they will be charged if you cancel it. So don't do this test with a booking that will carry out cancelations fees.

6.2 - Are you able to cancel the live booking (booking done at point 5.1)?

Now that we are able to generate bookings on live, we should cancel the booking that we have done at point 5.1.

Please, cancel it (otherwise you would be charged).

6.3 - Do you support non-breaking changes?

A non-breaking change means that we are able to change some aspects of the API and it should not affect your integration. Note that APItude is conceived to use without xsd, so changes at API level like:

  • Adding new response fields.
  • Adding new endpoints / operations.
  • Adding new optional parameters in the requests.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of strings. 

Should not carry out any inconvenience of your integration.

Remember that certification is done on test environment, so when Hotelbeds give you live access, this prove is essential in order to verify that we are ready and everything is working on live!

Docs Navigation