Dynamic API

Workflow

HProTravel API (Coral) has 4 steps of flow. Please do not forget that all steps are must.

Coral Workflow

Destination Structure

In order to supply maximum level of destination hierarchy in human readable format (national, regional, sub-regional, local and sub-destination based), Platform 2 provides multi-level destination structure by parent-child relation with more-to-more connectivity.

Below chart shows structure sample of destination to sub-destination relation :

Subdestinations

Sub-destination’s parent destination code refers higher destination that covers sub destination.

More-to-more structure gives best application of destinations and creates destination matrix in order to provide ability to reach sophisticated certain destination that have complex relation with destination network.

More than one sub-destination can be connected to single destination.
Sub-destination can be connected to more than one destinations.
Maximum level of sub-destination count from highest level destination to lowest level destination is non-limited.
If a destination doesn’t have a parent id, this destination is a city.
For US, Canada, Brasil, Mexico and Australia, province regions refers to states.

Below chart shows destination structure of static database :

Destinations

A standard hotel booking progress starts with "search" action and the general flow continues as "search -> check availability -> provision -> booking" steps. During this flowing process, for each step, unique codes must be carried to the next step.

Search

This method is used for getting hotel information and properties on a specific date range (check-out - check-in), with a designated amount of people (pax) from /search endpoint.

Example(1): GET /api/v2/search/?pax=3&checkout=2017-01-25&checkin=2017-01-20&hotel_code=10e6cc&client_nationality=tr&currency=EUR

Response:

{
  "count": 1,
  "code": "20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "10e6cc",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206e4",
      "products": [
        {
          "code": "10e6cc_56305817968661_0_3_2_2_0_1_2406044196_0_3-0-0.20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "357.21",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 3
              },
              "room_category": "Standard",
              "room_description": "Triple Room",
              "nightly_prices": {
                "2017-01-20": "71.44",
                "2017-01-21": "71.44",
                "2017-01-22": "71.44",
                "2017-01-23": "71.44",
                "2017-01-24": "71.44"
              },
              "room_type": "TB"
            }
          ],
          "nonrefundable": null,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "taxes": [
            {
              "currency": "EUR", 
              "amount": "6.00", 
              "type": "VAT", 
              "detail": "", 
              "inclusive": true
            }, 
            {
              "currency": "EUR", 
              "amount": "5.00", 
              "type": "City Tax", 
              "detail": "Example data", 
              "inclusive": true
            }
          ],
          "fees": [
            {
              "currency": "EUR",
              "amount": "6.00",
              "type": "Resort Fee",
              "detail": "",
              "inclusive": true
            },
          ],
          "view": false
        }
      ]
    }
  ]
}

Example(2):  GET /api/v2/search/?pax=1&checkout=2017-01-25&checkin=2017-01-20&hotel_code=103752&client_nationality=us&currency=EUR&max_product=1

Response:

{
  "count": 1,
  "code": "20170120_5_1_1_232_462875c1706e462da59554d407e4774d_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "103752",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206ec",
      "products": [
        {
          "code": "103752_58502674047670_2_2_2_2_0_1_238342530_0_0-0-0.20170120_5_1_1_232_462875c1706e462da59554d407e4774d_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "559.34",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-20": "111.87",
                "2017-01-21": "111.87",
                "2017-01-22": "111.87",
                "2017-01-23": "111.87",
                "2017-01-24": "111.87"
              },
              "room_type": "SB"
            }
          ],
          "nonrefundable": false,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "taxes": [
            {
              "currency": "EUR", 
              "amount": "6.00", 
              "type": "VAT", 
              "detail": "", 
              "inclusive": true
            }, 
            {
              "currency": "EUR", 
              "amount": "5.00", 
              "type": "City Tax", 
              "detail": "Example data", 
              "inclusive": true
            }
          ],
          "fees": [
            {
              "currency": "EUR",
              "amount": "6.00",
              "type": "Resort Fee",
              "detail": "",
              "inclusive": true
            },
          ],
          "view": false
        }
      ]
    }
  ]
}

Example(3):

POST /api/v2/search/?pax=3&checkout=2017-01-25&checkin=2017-01-20&client_nationality=tr&currency=EUR

POST BODY: hotel_code=10e6cc, ...

Note : You can pass 500 hotel code in body

Response:

{
  "count": 197 ,
  "code": "20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "10e6cc",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206e4",
      "products": [
        {
          "code": "10e6cc_56305817968661_0_3_2_2_0_1_2406044196_0_3-0-0.20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "357.21",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 3
              },
              "room_category": "Standard",
              "room_description": "Triple Room",
              "nightly_prices": {
                "2017-01-20": "71.44",
                "2017-01-21": "71.44",
                "2017-01-22": "71.44",
                "2017-01-23": "71.44",
                "2017-01-24": "71.44"
              },
              "room_type": "TB"
            }
          ],
          "nonrefundable": null,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "taxes": [
            {
              "currency": "EUR", 
              "amount": "6.00", 
              "type": "VAT", 
              "detail": "", 
              "inclusive": true
            }, 
            {
              "currency": "EUR", 
              "amount": "5.00", 
              "type": "City Tax", 
              "detail": "Example data", 
              "inclusive": true
            }
          ],
          "fees": [
            {
              "currency": "EUR",
              "amount": "6.00",
              "type": "Resort Fee",
              "detail": "",
              "inclusive": true
            },
          ],
          "view": false
        }
      ]
    }

  ...

  ]
}

Request Base Parameters

Name	Value	Required	Description
format	string	no	Type of the data to be received as a response. JSON is currently supported. Default setting is human readable structured plain html. The default is determined by Accept header of the HTTP Request.
pax	custom-list	yes	Indicates amount of persons.  A few input examples are as follows : pax = 4 (4 adults) pax = 2,12,11 (2 adults, 2 children with ages of 12 and 11) First integer is the number of adults,  and the rest after the first comma will be taken as list of children ages.  Can be used multiple times in one search separated with &.
checkout	dateobject	yes	Indicates check-out date. Can not be greater than check-in. The range between check-in and checkout is limited to maximum 30 days. Must be in the formatted as YYYY-MM-DD
checkin	dateobject	yes	Indicates check-in date. Can not be greater than checkout. The range between checkin and checkout is limited to maximum 30 days. Must be in the formatted as YYYY-MM-DD
currency	string	sometimes	Indicates requested currency of the product prices. Must be one of the Consumer's account currencies. This field is required if multiple currencies are enabled on the Consumer's account.
client_nationality	string	yes	Indicates two letter country code of the client nationality. The nationality must refer to a valid country_code within countries table.
max_product	integer	optional	Indicates maximum amount of products per hotel returned from the API. If not set, no limit set to product count. default is no limit.

Restrictions:

Number of children per room cannot be more than 4
Number of adults per room must be minimum 1 maximum 6
Number of passengers per room cannot be more than 6
Maximum number of rooms : 5
Maximum child age : 17
Maximum number of hotels in search response cannot be more than 5000
Timeout between search and booking process can occur after 30 minutes
The cancellation policies can be in search response if our partners settled them

Primary Search Methods

There is a primary method available to limit the selection of hotels returned in the request, presented below in no particular order.  The method allows an explicit set of products to be returned via a specific hotel_code. Only this method can be used at a time.

Using Multiple hotel_code(s)

A hotel code or list of hotel codes with comma separation (see: example below) can be used with this method. Hotel codes from different destinations can be used. It is possible to send multiple hotel code search request at the same time.

Name	Value	Required	Description	Restrictions
hotel_code	string	Yes*	The unique code(s) for a hotel.	Maximum 5000 hotel in one request allowed.

(*) : Required only for this search method

Multiple Hotel Codes Search Examples

Below search beginning with 14097 hotel code (Didi Hotel/Turkey) returns rooms from Didi Hotel :

GET /api/v2/search/?hotel_code=14097e

Below search beginning with 14097 hotel code (Didi Hotel/Turkey) and 15325f hotel code (Olive Grove Resort / Greece) returns rooms from Didi Hotel and Olive Grove Resort even they are hotel codes from different destinations.

GET /api/v2/search/?hotel_code=14097e,15325f

Using destination_code

This method can be used to get hotel list on a specific destination such as London.

Name	Value	Required	Description
destination_code	string	Yes*	The unique code for the destination.

(*) : Required only for this search method

Destination search example

Below search beginning with 11260 destination code (London/England) returns hotel list at London :

GET /api/v2/search/?destination_code=11260

Using Geo-Location

Geo-Code is geographic coordinating system which points the location on the map by latitude and longitude. This method can be used to get hotel list on a specific circle area.

Geo Search

Latitude, longitude and radius information can be used with this method.

Note that, one geo search query will return 200 hotels at maximum even if there are more hotels available at that radius.

Name	Value	Required	Description	Restrictions
lat	string	Yes*	latitude(φ) geographic coordinate that specifies the north-south position of a point on the Earth's surface.	This value must be between -90 and 90
lon	string	Yes*	Longitude, geographic coordinate that specifies the east-west position of a point on the Earth's surface.	This value must be between -180 and 180.
radius	string	Yes*	Distance from given point. (in meter)	This value is maximum 20000(20km).

(*) : Required only for this search method

Geo Codes Search Example

Search hotels around 1km radius from Eifel Tower:

Eifel Tower

GET /api/v2/search/?pax=1&checkout=2017-01-25&checkin=2017-01-20&lat=48.858543&lon=2.294502&radius=1000&client_nationality=gb&currency=GBP

Example response for the above geo-search request is below :

Example Response

{
  "count": 19,
  "code": "20170120_5_1_3_76_f9ef5a5a78734d44a835e07eb99d4650_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "106f18",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "20a11",
      "products": [
        {
          "code": "106f18_55217158285494_1_2_2_2_0_3_238342530_0_0-0-0.20170120_5_1_3_76_f9ef5a5a78734d44a835e07eb99d4650_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "281.94",
          "currency": "GBP",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-20": "56.39",
                "2017-01-21": "56.39",
                "2017-01-22": "56.39",
                "2017-01-23": "56.39",
                "2017-01-24": "56.39"
              },
              "room_type": "SB"
            }
          ],
          "nonrefundable": true,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "taxes": [
            {
              "currency": "EUR", 
              "amount": "6.00", 
              "type": "VAT", 
              "detail": "", 
              "inclusive": true
            }, 
            {
              "currency": "EUR", 
              "amount": "5.00", 
              "type": "City Tax", 
              "detail": "Example data", 
              "inclusive": true
            }
          ],
          "fees": [
            {
              "currency": "EUR",
              "amount": "6.00",
              "type": "Resort Fee",
              "detail": "",
              "inclusive": true
            },
          ],
          "view": false
        }
      ]
    },
    ...
  ]
}

Response Object Parameters

Name	Value	Description
checkin	string	Check-in date. Format : YYYY-MM-DD
checkout	string	Check-out date. Format : YYYY-MM-DD
destination_code	string	The code resembles that is the equivalent of the searched hotel destination. The unique code refers to destination_code within destinations table.
hotel_code	string	The unique code for the hotel.
products	list	List of products and details
code	string	Product code of returned product
currency	string	Currency code of returned product
meal_type	string	Meal type code of returned product
nonrefundable	boolean	Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products.
pay_at_hotel	boolean	Information of the payment either the customer can pay at the time of arrival to the hotel itself or not. If this parameter is false than hotel_currency and hotel_price will be returned as null
hotel_currency	string	Currency of the hotel_price. Only returned in case if pay_at_hotel variable is true.
hotel_price	decimal	The price in hotel currency that the customer will pay at the time of arrival to the hotel itself. Only returned in case if pay_at_hotel variable is true.
price	decimal	Product price value in currency determined in search query.
minimum_selling_price	decimal	It is the minimum selling price to the end consumer. In other words, a price that can't in any circumstances be undersold.
rooms	list	List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
taxes	list	List of taxes. It contains tax details if it is available.
type	string	Tax Type. Available types: VAT, City Tax, Others
amount	decimal	Tax Amount in related currency(Use tax currency in response)
inclusive	boolean	It shows whether tax amount is included in price or not
detail	string	Tax details, if it is available
fees	list	List of fees. It contains fee details if it is available.
type	string	Fee Type. Available types: Resort Fee, Others
amount	decimal	Fee Amount in related currency(Use fee currency in response)
inclusive	boolean	It shows whether fee amount is included in price or not
detail	string	Fee details, if it is available
view	boolean	Information about if the room has a view.
supports_cancellation	boolean	Indicates the product whether can cancel or not over api
policies	list	List of cancellation policies. For detailed information and example about policies list of the product, please see section "Contents of Policies List"
next_page_code	string	This parameter is DEPRECATED, so returns null.
max_wait	string	Your maximum wait configuration(SLA Time).
response_time	string	Response time

Contents of Policies List

Name	Value	Description
days_remaining	decimal	Number(s) of remaining days to check-in date. days_remaining = today - checkin (GMT+3)
ratio	decimal	Ratio of cancellation charge. The multiplier that will be applied to price to calculate cancellation charge.

Example Policies Response

"policies": [
        {
            "days_remaining": 1,
            "ratio" : "0.45"
        },
        {
            "days_remaining": 7,
            "ratio": "0.01"
        }
     ],

Contents of Room List

Name	Value	Description
pax	dict	A dict consists of adult quantity, children ages keys.
adult_quantity	int	Total number of adults
children_ages	list	A list consisting of integers which represent children guest ages
room_category	string	Represents the category of the room referring to room categories table.
room_descriptions	string	Description of the room
nightly_prices	dict	List of prices to pay for each night of the room. Dictionary contains night date and price pairs day by day. Date format is "yyyy-mm-dd"
room_type	string	Represents the type of the room

Important Notice

search/availability/hotel-availability/provision/book endpoints return the rooms data in the same template above.

Example Room List Response

Below example shows a multi pax search request & response for 1 adult and 2 adults 2017-01-21 to 2017-01-23.

GET /api/v2/search/?pax=1&pax=2&checkout=2017-01-23&checkin=2017-01-21&destination_code=19064&client_nationality=GB&currency=EUR

{
  "count": 52,
  "code": "20170121_2_1~2_1_76_b583b11744d54725b438fdecc3f8c066_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "100ff3",
      "checkout": "2017-01-23",
      "checkin": "2017-01-21",
      "destination_code": "19064",
      "products": [
        {
          "code": "100ff3_242336389998_2_2_2_2_0_1_1483860825_0_0-0-0~1-0-0.20170121_2_1~2_1_76_b583b11744d54725b438fdecc3f8c066_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "84.07",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-21": "18.68",
                "2017-01-22": "18.68"
              },
              "room_type": "SB"
            },
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 2
              },
              "room_category": "Standard",
              "room_description": "DOUBLE STANDARD",
              "nightly_prices": {
                "2017-01-21": "23.35",
                "2017-01-22": "23.35"
              },
              "room_type": "DB"
            }
          ],
          "nonrefundable": false,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "taxes": [
            {
              "currency": "EUR", 
              "amount": "6.00", 
              "type": "VAT", 
              "detail": "", 
              "inclusive": true
            }, 
            {
              "currency": "EUR", 
              "amount": "5.00", 
              "type": "City Tax", 
              "detail": "Example data", 
              "inclusive": true
            }
          ],
          "fees": [
            {
              "currency": "EUR",
              "amount": "6.00",
              "type": "Resort Fee",
              "detail": "",
              "inclusive": true
            },
          ],
          "view": false
        }
      ]
    },
    ...
  ]
}

Hotel Availability (Optional)

This method is used for getting information of a hotel availability via GET from /hotel-availability endpoint. Check Hotel Availability can be used multiple times to check the availability of the hotel in time range. It is advised to post the request in every display of hotel - detail or hotel - list functionalities in order to avoid availability or price changes and keeping pricing information up-to-date.

This endpoint returns a list of availability endpoint response. /availability endpoint returns up-to-date availability information for a single room; /hotel-availability endpoint returns up-to-date availability information for all rooms of a single hotel.

! If you want to get all up-to-date availability information for a single hotel's rooms then you should use this endpoint instead of /availability request for each room.

Note that: Hotel availability response is valid for 45 minutes. When you get an hotel availability response you have 45 minutes to go to book step. If you have missed this time and you have to get hotel-availability response again for that hotel.

Timeout duration: Hotel availability request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name	Value	Required	Description
search_code	string	yes	This is the code from the response of the search request. (code)
hotel_code	string	yes	This is the code from the response of the search request. (hotel_code)
max_product	integer	optional	Indicates maximum amount of products per hotel returned from the API. If not set, no limit set to product count. default is no limit.

Example(1): GET /api/v2/hotel-availability/?<search_code>&<hotel_code>

Example Response

GET /api/v2/hotel-availability/?search_code=20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_&hotel_code=135f3a

{
  "code": "20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_",
  "count": 25,
  "results": [
    {
      "code": "135f3a_55186709030717_1_2_2_2_0_1_438178821_23_0-1-0.20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_",
      "destination_code": "206ec",
      "hotel_code": "135f3a",
      "additional_info": "",
      "checkin": "2017-01-20",
      "checkout": "2017-01-25",
      "price": "212.38",
      "currency": "EUR",
      "pay_at_hotel": false,
      "hotel_price": null,
      "hotel_currency": null,
      "meal_type": "RO",
      "nonrefundable": true,
      "view": false,
      "rooms": [
        {
          "pax": {
            "children_ages": [],
            "adult_quantity": 1
          },
          "room_category": "Shared Facility",
          "room_description": "TWIN WITH SHARED BATHROOM",
          "nightly_prices": {
            "2017-01-20": "42.47",
            "2017-01-21": "42.47",
            "2017-01-22": "42.47",
            "2017-01-23": "42.47",
            "2017-01-24": "42.47"
          },
          "room_type": "SB"
        }
      ],
      "supports_cancellation": true,
      "minimum_selling_price": null,
      "offer": false,
      "policies": [
        {
          "ratio": "1.00",
          "days_remaining": 44
        }
      ]
    },
    ...
  ]
}

Example(2): GET /api/v2/hotel-availability/?<search_code>&<hotel_code>/max_product=1

{
  "code": "20180617_1_1_0_109_5c177913af964c92b591dab74d580209_",
  "count": 1,
  "results": [
      {
        "code": "112dfb_604661331_0_0_2_2_0_0_604661347_0_0-0-0.20180617_1_1_0_109_5c177913af964c92b591dab74d580209_",
      "destination_code": "206ec",
      "hotel_code": "135f3a",
      "additional_info": "",
      "checkin": "2017-01-20",
      "checkout": "2017-01-25",
      "price": "212.38",
      "currency": "EUR",
      "pay_at_hotel": false,
      "hotel_price": null,
      "hotel_currency": null,
      "meal_type": "RO",
      "nonrefundable": true,
      "view": false,
      "rooms": [
        {
          "pax": {
            "children_ages": [],
            "adult_quantity": 1
          },
          "room_category": "Shared Facility",
          "room_description": "TWIN WITH SHARED BATHROOM",
          "nightly_prices": {
            "2017-01-20": "42.47",
            "2017-01-21": "42.47",
            "2017-01-22": "42.47",
            "2017-01-23": "42.47",
            "2017-01-24": "42.47"
          },
          "room_type": "SB"
        }
      ],
      "supports_cancellation": true,
      "minimum_selling_price": null,
      "offer": false,
      "policies": [
        {
          "ratio": "1.00",
          "days_remaining": 44
        }
      ]
    }
  ]
}

Response Object Parameters

Name	Value	Description
product_code	string	Product code of returned product.
destination_code	string	The unique code for the destination.
hotel_code	string	The unique code for the hotel.
additional_info	string	Additional information about the room including specific information about product restrictions, rules, warnings etc.
checkin	string	Check-in date. Format : YYYY-MM-DD
checkout	string	Check-out date. Format : YYYY-MM-DD
price	decimal	The amount that will be charged for this booking (*)
currency	string	Indicates currency of the price. It is optional to send a specific currency option to receive the response price in specific currency. (EUR , USD , GBP etc.). The currency must refer to a valid currency_code within currencies table.
pay_at_hotel	boolean	Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
hotel_price	decimal	The local price value.
hotel_currency	string	Indicates the currency of hotel_price. It’s similar type of currency variable.
meal_type	string	Meal type code of returned product.
supports_cancellation	boolean	Indicates the product whether can cancel or not over api.
nonrefundable	boolean	Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products.
view	boolean	Information about if the room has a view.
rooms	list	List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
pax	dict	A dict consists of adult quantity, children ages keys.
adult_quantity	int	Total number of adults
children_ages	list	A list consisting of integers which represent children guest ages
room_category	string	Represents the category of the room referring to room categories table.
room_description	string	Description of the room
room_type	string	Represents the type of the room
supports_cancellation	boolean	Indicates the product whether can cancel or not over api.
minimum_selling_price	decimal	It is the minimum selling price to the end
offer	boolean
policies	list	List of cancellation policies. For detailed information and example about policies list of the product, please see section “Contents of Policies List”
days_remaining	int	Number(s) of remaining days to check-in date. days_remaining = today – checkin_date(GMT+3)
ratio	decimal	The multiplier that will be applied to price to calculate cancellation charge.
list_price	decimal

And also you will see product and room details just like in search response.

Availability (Optional)

If customer uses "Search-Hotel Availability-Provision-Book", on Hotel Availability step, some rooms may not have cancellation policy. For these rooms, you can call /availability endpoint to get cancellation policy however you have to verify the policy, price, room type etc. always in provision endpoint as it may change.

NB: Availability endpoint is to ask for room availability but not for hotel availability.

Provision

This method is used to get the last second information of the product that either it is available or not by POST method. If the product is available, this method returns with provision code. Provision method should be used just before booking to make sure the price and room is still available after the last executed search request. Carrying the code came from 'products' list in response of the search request is mandatory to execute provision command. It is not possible to make booking without posting provision code. So, this method is mandatory to make booking. Provision response and code are valid for 600 seconds.

NOTE: We only guarantee the price, room type, room description, meal type and cancellation policy offered in provision step and booking step. You must check these parameters in provision before booking and show to your customer. In case of no-show, the policy ( charge amount ) is up to hoteliers / partners. Refund can not be guaranteed.

Timeout duration: Provision request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name	Value	Required	Description
code	string	yes*	This is the code from the response of the search request. (product code)

Example Response

POST /api/v2/provision/<code>

Example Response

POST /api/v2/provision/135f3a_55186709030717_1_2_2_2_0_1_438178821_23_0-1-0.20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_

{
  "code": "PL77K57A2CLA",
  "destination_code": "206ec",
  "offer": false,
  "price": "212.38",
  "currency": "EUR",
  "rooms": [
    {
      "pax": {
        "children_ages": [],
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "nonrefundable": false,
  "additional_info": "Check-in hour 15:00 – 02:00. No alcohol is served. Deposit on arrival   . Early departure. Twin beds are bunk beds. Children under 0-17 years old are not permitted to stay in a bed room type.",
  "supports_cancellation": true,
  "hotel_code": "135f3a",
  "hotel_currency": null,
  "hotel_price": null,
  "checkin": "2017-01-20",
  "meal_type": "RO",
  "policies": [
    {
      "ratio": "1.00",
      "days_remaining": 44
    }
  ],
  "taxes": [
    {
      "currency": "EUR", 
      "amount": "6.00", 
      "type": "VAT", 
      "detail": "", 
      "inclusive": true
    }, 
    {
      "currency": "EUR", 
      "amount": "5.00", 
      "type": "City Tax", 
      "detail": "Example data", 
      "inclusive": true
    }
  ],
  "fees": [
    {
      "currency": "EUR",
      "amount": "6.00",
      "type": "Resort Fee",
      "detail": "",
      "inclusive": true
    },
  ],
  "view": false,
  "checkout": "2017-01-25",
  "minimum_selling_price": null,
  "pay_at_hotel": false
}

Response Object Parameters

Name	Value	Description
code	string	The provision code. This code is necessary to go to booking stage.
destination_code	string	The unique code for the destination
offer	boolean
price	list	The amount that will be charged for this booking.
currency	string	Indicates currency of the price. It is optional to send a specific currency option to receive the response price in specific currency. (EUR , USD , GBP etc.). The currency must refer to a valid currency code within currencies table.
rooms	list	List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
pax	dict	A dict consists of adult quantity, children ages keys.
adult_quantity	int	Total number of adults
children_ages	list	A list consisting of integers which represent children guest ages
room_category	string	Represents the category of the room referring to room categories table.
room_description	string	Description of the room
room_type	string	Represents the type of the room
nonrefundable	boolean	Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products.
list_price	decimal
supports_cancellation	boolean	Indicates the product whether can cancel or not over api.
additional_info	string	Additional information about the room including specific information about product restrictions, rules, warnings etc.
hotel_code	string	The unique code for the hotel.
hotel_currency	string	Indicates the currency of hotel_price. It’s similar type of currency variable.
hotel_price	decimal	The local price value.
checkin	string	Check-in date. Format : YYYY-MM-DD
meal_type	string	Meal type code of returned product.
policies	decimal	List of cancellation policies. For detailed information and example about policies list of the product, please see section “Contents of Policies List”
days_remaining	int	Number(s) of remaining days to check-in date. (GMT+3)
ratio	decimal	The multiplier that will be applied to price to calculate cancellation charge.
taxes	list	List of taxes. It contains tax details if it is available.
type	string	Tax Type. Available types: VAT, City Tax, Others
amount	decimal	Tax Amount in related currency(Use tax currency in response)
inclusive	boolean	It shows whether tax amount is included in price or not
detail	string	Tax details, if it is available
fees	list	List of fees. It contains fee details if it is available.
type	string	Fee Type. Available types: Resort Fee, Others
amount	decimal	Fee Amount in related currency(Use fee currency in response)
inclusive	boolean	It shows whether fee amount is included in price or not
detail	string	Fee details, if it is available
view	boolean	Information about if the room has a view.
checkout	string	Check-out date. Format : YYYY-MM-DD
minimum_selling_price	decimal	It is the minimum selling price to the end
pay_at_hotel	boolean	Information of the payment either the customer can pay at the time of arrival to the hotel itself or not

Booking

This method is the fourth and last step of hotel booking. The method is used to book a product that have made sure available with 'Provision' request. Carry the unique code which has got from Provision response. And also guest information and payment information is used to get. At the end of this method if provision code is not expired and property information is still valid, booking process will be completed.

NOTE: Please don’t forget to add your reference IDs for bookings you will make. You can use agency_ref_id parameter in your booking requests.

Timeout duration: Booking request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name	Value	Required	Description	Restrictions
card_cvc	string	Conditional*	Credit card cvc value	3 or 4 digits
card_expiration	string	Conditional*	Credit card expiration date	YYYY-MM format
card_holder_name	string	Conditional*	Credit card holder name
card_number	string	Conditional* Credit card number	Must be valid card number
card_type	string	Conditional*	Credit card type	Visa / MasterCard
code	string	yes	Product code that have been retrieved from provision response
email	string	Conditional*	Guest email address	Must be valid email address
format	string	no	Type of the data document that is going to be received as a response.	Only JSON is currently supported
name	string	yes	Must be `name=1,firstname,lastname,type` format (1 refers room number, type can be adult/child)	200 Characters, max.
phone_number	string	Conditional*	Guest phone number. Phone Numbers must be at least 5 digits long and have at least one different digit (ex:5555555555 is not valid)
special_request	string	no	A free text section where the personal making the hotel reservation can make special requests.	255 Characters, max.
agency_ref_id	string	no		255 Characters, max.
expected_price**	float	Optional	expected_price should be used in book data request. As long as price changes on book step is under your expected price, booking will be confirmed to you.

(**) Expected Price: Provision price is 100 EUR and you can cover the booking till 105 EUR. So, you can send expected_price=105 EUR. If in book step, price changes to 105 EUR, booking will be confirmed to you with 105 EUR.

If in book step, price is 110 EUR, booking will failed to you and not confirmed.

expected_price can not be under provision price.

(*) Conditional: Required for pay_at_hotel payment type.

Example Request Post

POST /api/v2/book/<code>

Request Body

pay_at_hotel type

name&card_cvc&card_expiration&card_holder_name&card_number&card_type&email&phone_number

prepaid

name

expected_price

expected_price

Example Request Body

name=1,John,Doe,adult&expected_price=220.0

Response Objects

Example response for the above booking request is below:

Example Response

POST /api/v2/book/PL77K57A2CLA

{
  "code": "B3CJBKKDU43F",
  "created_at": "2016-12-09 07:03:03.367699+00:00",
  "checkin": "2017-01-20",
  "checkout": "2017-01-25",
  "hotel_code": "135f3a",
  "destination_code": "206ec",
  "client_nationality": "gb",
  "pay_at_hotel": false,
  "currency": "EUR",
  "mealtype_code": "RO",
  "nonrefundable": false,
  "view": false,
  "policies": [
    {
      "days_remaining": 44,
      "ratio": "1.00"
    }
  ],
  "taxes": [
    {
      "currency": "EUR", 
      "amount": "6.00", 
      "type": "VAT", 
      "detail": "", 
      "inclusive": true
    }, 
    {
      "currency": "EUR", 
      "amount": "5.00", 
      "type": "City Tax", 
      "detail": "Example data", 
      "inclusive": true
    }
  ],
  "fees": [
  {
      "currency": "EUR",
      "amount": "6.00",
      "type": "Resort Fee",
      "detail": "",
      "inclusive": true
    },
  ],
  "price": "212.38",
  "rooms": [
    {
      "pax": {
        "children_ages": "",
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "status": "succeeded",
  "confirmation_numbers": [
    {
      "confirmation_number": "164-3015081",
      "names": [
        "John Doe"
      ],
      "rooms": [
        {
          "room_description": "TWIN WITH SHARED BATHROOM",
          "room_type": "TWN"
        }
      ]
    }
  ],
  "hotel_payment_info": [
    {
      "hotel_currency": null,
      "hotel_price": null
    }
  ],
  "minimum_selling_price": null,
  "special_request": null,
  "hotel_confirmation_number":"11223344",
  "hotel_confirmation_number_date":"2018-01-31 20:58:16.429164+00:00"
}

Response Object Parameters

Name	Value	Description
code	string	booking code
created_at	string	Time of the booking
checkin	dateobject	Indicates check-in date
checkout	dateobject	Indicates check-out date
pay_at_hotel	boolean	Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
price	decimal	Total price of the booking
currency	string	Currency code
client_nationality	string	Indicates two letter country code of the client nationality
destination_code	string	The unique code for the destination
hotel_code	string	The unique code for the hotel
mealtype_code	string	The unique code for the meal type
policies	list	Policies list including days_remaining and ratio (GMT+3)
taxes	list	List of taxes. It contains tax details if it is available.
type	string	Tax Type. Available types: VAT, City Tax, Others
amount	decimal	Tax Amount in related currency(Use tax currency in response)
inclusive	boolean	It shows whether tax amount is included in price or not
detail	string	Tax details, if it is available
nonrefundable	boolean	Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products.
fees	list	List of fees. It contains fee details if it is available.
type	string	Fee Type. Available types: Resort Fee, Others
amount	decimal	Fee Amount in related currency(Use fee currency in response)
inclusive	boolean	It shows whether fee amount is included in price or not
detail	string	Fee details, if it is available
view	boolean	Information about if the room has a view.
supports_cancellation	boolean	Indicates the product whether can cancel or not over api
status	string	Status of the booking Possible status list; 'Succeeded', 'Failed', 'Cancelled'
confirmation_numbers	list	A list dictionaires that has the number of the booking. The names that the booking has been done under and the partner of it.
minimum_selling_price	decimal	It is the minimum selling price to the end
special_request	string	Given free format text to inform hotel (remember that, it could be unsent)
hotel_confirmation_number	string	Hotel confirmation Number assigned to identify, record, and trace a confirmed booking with Hotelier.
hotel_confirmation_number_date	string	Time which taken hotel confirmation number

Unsaved Condition Recovery

When you send a book request and receive no response due to network problems (timeout issues, losing connection, etc.), you need to use the /api/v2/bookings/<code> endpoint to double-check the booking result and ensure if the book request is confirmed/completed or not.

Nightly Price Information

Nightly price is coming from our partners for only information. Some partners give supplements, fees, taxes, meal price, etc separately not included in the nightly prices and that is why they may not be equal to the total price.

Clients should show the total price as final price and nightly price should be only for information.

Cancellation

This method is used to cancel booking. Code value from the booking response must be included.

Booking code should be included which has been received from booking process.

Please note that cancellation charge will be applied at 00.00 (GMT+3) once booking is in cancellation deadline.

Request Base Parameters

Name	Value	Required	Description
code	string	yes	The code from response of the booking request. (code)

Example Response

POST /api/v2/cancel/<code>

{
  "currency": "EUR",
  "charge_amount": "212.38",
  "code": "B3CJBKKDU43F"
}

Response Object Parameters

Name	Value	Description
currency	string	currency type of the charge_amount
code	string	cancellation code
charge_amount	decimal	The amount of penalty payment for cancelling the booking. No charge is taken if returned null.

Bookings

This method is also known for 'booking list' and it is for retrieving past booking data.

It has three uses. If you are authorized with a specific consumer, it will get you all the booking data related to that consumer.

Second use is that you can do a request with a specific booking code (or provision code) to retrieve that specific booking data.

You can now search your own booking reference id by using our "/bookings" endpoint. When you make a booking, if you send your own reference in book data like "&agency_ref_id=test1234", you can check the booking details after booking is confirmed like like; https://api2.hprotravel.com/api/v2/bookings/?agency_ref_id=test1234

And finally, as it is stated in the "Unsaved Condition Recovery" section, this method should be used to ensure book request status in case of not having a proper booking response.

Request Base Parameters

GET /api/v2/bookings/<code>

Name	Value	Required	Type	Description
code	string	No	-	This is the code that taken from the response of the bookings request. (Or provision code can be used to make a booking request.)
from_date	string	No	Query string	This is the booking date for filtering the bookings from the from_date(YYYY-MM-DD).
to_date	string	No	Query string	This is the booking date for filtering the bookings until the to_date(YYYY-MM-DD).
format	string	No	Query string	Only JSON supported
agency_ref_id	string	no	This is the agency_ref_id that was sent in booking request

If code, from_date and to_date parameteres, agency_ref_id are not provided, the result will include the bookings of that day only.

Example Response

GET /api/v2/bookings/B3CJBKKDU43F or GET /api/v2/bookings/?agency_ref_id=test1234

{
  "code": "B3CJBKKDU43F",
  "created_at": "2016-12-09T07:03:03.367Z",
  "checkin": "2017-01-20",
  "checkout": "2017-01-25",
  "hotel_code": "135f3a",
  "destination_code": "206ec",
  "client_nationality": "gb",
  "pay_at_hotel": false,
  "currency": "EUR",
  "mealtype_code": "RO",
  "nonrefundable": false,
  "view": false,
  "policies": [
    {
      "days_remaining": 44,
      "ratio": "1.00"
    }
  ],
  "taxes": [
    {
      "currency": "EUR", 
      "amount": "6.00", 
      "type": "VAT", 
      "detail": "", 
      "inclusive": true
    }, 
    {
      "currency": "EUR", 
      "amount": "5.00", 
      "type": "City Tax", 
      "detail": "Example data", 
      "inclusive": true
    }
  ],
  "price": "212.38",
  "rooms": [
    {
      "pax": {
        "children_ages": "",
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "status": "cancelled",
  "confirmation_numbers": [
    {
      "confirmation_number": "164-3015081",
      "agency_ref_id": [
        "test1234"
      ],
      "names": [
        "John Doe"
      ],
      "rooms": [
        {
          "room_description": "TWIN WITH SHARED BATHROOM",
          "room_type": "TWN"
        }
      ]
    }
  ],
  "hotel_payment_info": [
    {
      "hotel_currency": null,
      "hotel_price": null
    }
  ],
  "minimum_selling_price": null,
  "special_request": null,
  "hotel_confirmation_number": "11223344", 
  "hotel_confirmation_number_date": "2018-01-31 20:58:16.429164+00:00",
  "cancellation_price": "0.00"
}

Name	Value	Description
code	string	booking code
created_at	string	Time of the booking
checkin	dateobject	Indicates check-in date
checkout	dateobject	Indicates check-out date
pay_at_hotel	boolean	Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
price	decimal	Total price of the booking
currency	string	Currency code
client_nationality	string	Indicates two letter country code of the client nationality
destination_code	string	The unique code for the destination
hotel_code	string	The unique code for the hotel
mealtype_code	string	The unique code for the meal type
policies	list	Policies list including days_remaining and ratio (GMT+3)
taxes	list	List of taxes. It contains tax details if it is available.
type	string	Tax Type. Available types: VAT, City Tax, Others
amount	decimal	Tax Amount in related currency(Use tax currency in response)
inclusive	boolean	It shows whether tax amount is included in price or not
detail	string	Tax details, if it is available
nonrefundable	boolean	Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products.
view	boolean	Information about if the room has a view.
supports_cancellation	boolean	Indicates the product whether can cancel or not over api
status	string	Status of the booking Possible status list; 'Succeeded', 'Failed', 'Cancelled'
confirmation_numbers	list	A list dictionaires that has the number of the booking. The names that the booking has been done under and the partner of it.
minimum_selling_price	decimal	It is the minimum selling price to the end
special_request	string	Given free format text to inform hotel (remember that, it could be unsent)
hotel_confirmation_number	string	Hotel confirmation Number assigned to identify, record, and trace a confirmed booking with Hotelier.
hotel_confirmation_number_date	string	Time which taken hotel confirmation number
cancellation_price	decimal	If the book is cancelled, we return the cancellation cost. Otherwise its NULL.

Errors, Error Codes

Errors and error codes are generated specific messages corresponds to the information. When an error occurs, API sends a response which contains error_code and detail information. detail field can be string or javascript object.

{
 "error_code": 4405,
 "detail": "Method not allowed"
}
{
 "error_code": 4400,
 "detail": {
 "card_type": ["'diners' is not a valid card type. Supported cards: visa"],
 "card_number": ["Card number is not valid"]
 }
}

Error Code List

http_status	error_code	error_type	detail	detail parameter
400	4400
		common error
			Invalid client IP	client_IP
			Invalid channel	channel
		booking error
			Passenger names are required	name
			Search pax info and book pax info does not match	detail
			This card type is not valid, please check. Available cards:...	card_type
			Card number is not valid	card_number
			At least one name parameter is required	name
			Credit card info is required for direct payment hotels	detail
		cancellation error	Booking cannot be cancelled after checkin date	detail
		search error
			Invalid currency	detail
			Invalid destination code	destination_code
			Checkin date is invalid	checkin
			Checkin date is in the past	checkin
			Checkout date is invalid	checkout
			Checkout date appears to be earlier than the checkin date	non_field_errors
			Number of room cannot be more than 5	pax
			Number of adults per room must be between 1-6	pax
			Number of children per room cannot be more than 4	pax
			Number of passengers per room cannot be more than 6	pax
			Number of night for a stay cannot be more than 30 days	non_field_errors
			Destination code is required	non_field_errors
			Invalid destination code	destination_code
401	4401	common error
			Authentication credentials were not provided.
			Invalid username/password
			Channel is disabled
404	4404	booking error
			Please go to provision step first!	detail
			Search result with given code could not be found	detail
		cancellation error	Booking not found	detail
		availability/provision error	Product is expired	detail
405	4405	common error	Method not allowed	detail
409	4409	booking error
			This product is already purchased	detail
			We could not process the booking due to an unknown error
		cancellation error	Booking already cancelled	detail
410	4410	booking error	The room is no longer available	detail
500	5500	common error	There was an error. Please try again later