Documentation

Certification process

In this section, we will give you all the necessary information to complete the Certification Process, which will ensure that your integration is ready to go LIVE.

Carefully reading this section and planning the implementation ahead, knowing what is going to be specifically requested to our APIs, can lead to a much better experience and reaching the goal of going LIVE much quicker.

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 integration was properly developed: 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 checklist , let us explain to you how to request the certification process:

How to request the certification process:

Once you have finished your development and reviewed the next sections (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 the 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 establishes the quantity and correct order of calls to the system in order to perform a booking.

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

WorkFlow

The explanation of this workflow is:

In order to book a hotel room or rooms, you need to define at least checkIn date, checkOut date, hotels to be requested, numbers of rooms and passengers. The response of this will inform you on the available options for those criteria. This is performed in the first step: Request availability (/hotels).

Once you get Availability, then you need to perform a 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 the certification process, so please, check it before request certification:

General

2.1 - Are you using the correct workflow?

The correct workflow for a standard booking is as follows:

(1) First send an Availability request, then (2) use CheckRate operation - if applies - and (3) finally call Booking request.

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

Before CheckRate, Availability is called again, and before Booking, Availability and CheckRate are called again. Thus, the operations the client is calling are: (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 is related to section 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, so request as many hotels as possible in the minimum number of Availability calls. Remember that you are able to inform up to 2000 hotels per call.

For example (take special attention to hotels tag):

{
    "sourceMarket": "UK",
    "stay": {
        "checkIn": "2020-06-15",
        "checkOut": "2020-06-16"
    },
    "occupancies": [
        {
            "rooms": 1,
            "adults": 2,
            "children": 0
        }
    ],
    "hotels": {
        "hotel": [
            1067,
            1070,
            [...]
            1074
        ]
    }
}



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

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

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):

{
    "dailyRate": true,
    "sourceMarket": "UK",
    "stay": {
        "checkIn": "2020-06-15",
        "checkOut": "2020-06-16"
    },
    "occupancies": [
        {
            "rooms": 1,
            "adults": 2,
            "children": 0
        },
        {
            "rooms": 1,
            "adults": 3,
            "children": 1,
			"paxes": [
				{
					"type": "CH",
					"age": 7
				}
			]
        }
    ],
    "hotels": {
        "hotel": [
            1067,
            1070
        ]
    }
}



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 at the following example (Availability response) where rateType="BOOKABLE". In case you want to book this rateKey, you can use it and request Booking confirmation:

[…]
    "hotels": {
        "hotels": [
            {
                […]
                "rooms": [
                    {
                        "code": "DBT.SU",
                        "name": "Double or Twin SUPERIOR",
                        "rates": [
                            {
                                "rateKey": "20200615|20200616|W|1|1067|DBT.SU|CG-BAR17HB|HB||1~2~0||N@03~~200ec~-921081655~N~3906F451FAAC4E3159195340961500AAES0000002000000000721acb",
                                "rateClass": "NOR",
                                "rateType": "BOOKABLE",
                                […]
                            }
                        ]
                    }
                ]
            }
        ],
        "checkIn": "2020-06-15",
        "total": 2,
        "checkOut": "2020-06-16"
    […]



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 allows to request up to ten rates, so in case you are going to request more than one rate you can group them on one simple call.

Please, take a look to the following example:

{
    "rooms": [
        {
            "rateKey": "20200812|20200815|W|102|1067|DBL.ST-1|CG-BAR|RO||1~2~0||N@03~~20093~647366240~N~5FB51A926B80422159195633746600AAES000001600000000072337e"
        },
		{
            "rateKey": "20200812|20200815|W|102|1067|DBL.ST-1|CG-BAR|BB||1~2~0||N@03~~200d5~817729600~N~5FB51A926B80422159195633746600AAES00000160000000007221b7"
        }
    ]
}

2.7 - We suggest displaying the rates promotions.

This will help to know whether the selected rate price includes a transfer in Maldives, or a Disney ticket for example.

"promotions": [
   {
       "code": "073",
       "name": "Non-refundable rate. No amendments permitted"
   }
  ],



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 requesting certification.

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 to choose the number of passengers?

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 at the following availability request example requesting one room for two adults and another room for three adults and one child.

{
    "dailyRate": true,
    "sourceMarket": "UK",
    "stay": {
        "checkIn": "2020-06-15",
        "checkOut": "2020-06-16"
    },
    "occupancies": [
        {
            "rooms": 1,
            "adults": 2,
            "children": 0
        },
        {
            "rooms": 1,
            "adults": 3,
            "children": 1,
			"paxes": [
				{
					"type": "CH",
					"age": 7
				}
			]
        }
    ],
    "hotels": {
        "hotel": [
            1067,
            1070
        ]
    }
}



3.3 - Does your system allow to indicate the number of children?

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

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

{
    "dailyRate": true,
    "sourceMarket": "UK",
    "stay": {
        "checkIn": "2020-06-15",
        "checkOut": "2020-06-16"
    },
    "occupancies": [
        {
            "rooms": 1,
            "adults": 3,
            "children": 1,
			"paxes": [
				{
					"type": "CH",
					"age": 7
				}
			]
        }
    ],
    "hotels": {
        "hotel": [
            1067,
            1070
        ]
    }
}



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.

The 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:

[…]
    "rateKey": […],
    "packaging": false,
[…]



3.6 - Does your system use Source market?

Source market is used on requests in order to inform Hotelbeds that you are requesting prices for a specific market. This is useful because some hotels have lower prices depending on the source market of the final client.

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

[…]
"sourceMarket": "UK",
[…]



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:

[…]
	"rooms": {
        "included": true,
        "room": [
            "DBT.ST"
        ]
    },
    "keywords": {
        "keyword": [
            34,
            38
        ]
    },
    "accommodations": [
        "HOTEL",
        "HOSTEL"
    ],
    "boards": {
        "included": true,
        "board": [
            "RO",
            "BB"
        ]
    },
    "reviews": [
        {
            "type": "TRIPADVISOR",
            "maxRate": 5,
            "minReviewCount": 3
        }
    ],
    "filter": {
    	"maxHotels": 10,
        "minRate": 100,
        "maxRate": 170,
        "minCategory": 3,
        "maxCategory": 5,
        "paymentType": "AT_HOTEL",
        "maxRatesPerRoom": 3,
        "packaging": true,
        "hotelPackage": "YES",
        "maxRooms": 2,
        "contract": "CG-FIT B2B"
    }
[…]



3.8 - Does your system show Hotelbeds cancellation policies?

Hotelbeds, through the API, provides the cancellation policies that will be applied to all reservations. However, you are free to display them 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 verify that there are no errors in your implementation, otherwise, please inform us that you are not using it and thus we will not take into account on the certification process.

Cancellation policies are returned on availability response at rate tag:

[…]
"cancellationPolicies": [
	{
		"amount": "50.01",
		"from": "2020-08-10T23:59:00+02:00"
	}
],
[…]



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

IMPORTANTE REMARK: 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:

[…]
"rateCommentsId": "102|166598|0",
[…]



Alternatively, you can obtain the rateComments from the Checkrate operation,for both direct and external product.

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

3.11 - Does your system has the proper Booking Confirmation Response Timeout been set?

Please notice that the Timeout for the Booking Confirmation Response should be set at a minimum of 60 seconds.

3.12 - Does your system use Recommended selling price rates?

If the client is using selling rates, it needs to be checked whether the correct price is shown in the correct situations.

It is recommended to respect the selling rate attribute if it is a hotel mandatory.

[…]
    "rateKey": […],
    "hotelMandatory": false,
[…]
Note: You can not use mandatory words, for legal reasons we only can recommend their use. If case the client does not respect it, then we are going to perform exclusions.


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 a 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 to send it to the final user.

4.2 - Hotel information

Please, check that the following information appears 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 - Passenger information

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

  • Holder name: It has to be the lead passenger included in the booking request
  • At least one pax name per room. In case of reservations with only one room, the holder's name is sufficient.
  • If children are present, children's ages should be informed.

4.4 - Booking information

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

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

4.5 - Payment information

In you booking vouchers is recommended to not show the price of the reservation and show:

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

IMPORTANT REMARK: XXX = Supplier/name (supplier tag), YYY = VAT number (supplier tag) , ZZZ = booking reference.



5 - Content

ContentAPI 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 content?

Please, let us know if you use only HotelBeds hotel content or you have other hotel content providers (source). In case you use both sources, 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 values of category. For example, hotels have from one to five stars as category value, apartments have from one to five keys as category value, etc.

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 request of Content API you can get following 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 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 - Crawler

Implement crawler integration based on the following specification: Crawler specification




5.6 - Other

  • Does your system show the 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 carry out cancellation costs.

IMPORTANT REMARK: Any booking or action that you perform on LIVEenvironment 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!