Distributor Knowledge Base

TABLE OF CONTENTS

Introduction
Hotel List
Hotel Products

Introduction

Hotel APIs are mandatory to implement and are used by GO Distributors to retrieve hotel suppliers' hotels and products.

Hotel List (/hotels/{supplierId}): GO Distributors use this API to obtain hotels and their availability status. If the hotel status returned is 'Deactived', it indicates that the hotel has been offline or unavailable.
Hotel Product (/hotel/{supplierId}/{hotelId}): GO Distributors use this API to obtain hotel products and the availability status of each product. 'Deactived' indicates that it is not available for sale.

Hotel List

Distributors use the API to retrieve the list of hotels and then turn hotels on or off in their system according to the hotel status (Active/Deactived). Hotel lists should be synced on a regular schedule (daily is preferred).

GET /hotels/{supplierId}?distributorId={distributorId} HTTP/1.1
URL: {endpoint}/hotels/{supplierId}?distributorId={distributorId}
Authorization:Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Parameters

Name	Description	Required	Type	Example
supplierId	Supplier ID in DerbySoft’s system	Yes	string	HILTON
distributorId	Distributor ID in DerbySoft's system	Yes	string	TUI

Response Example

Success Response (HTTP Status 200)

[
  {
    "hotelId": "GATHI",
    "hotelName": "This is a test hotel",
    "supplierId": "HILTON",
    "status": "Actived"
  }
]

Error Response(HTTP Status 401)

{
    "error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}

Response Specification

Attribute	Type	Required	Description	Example
hotelId	string	Yes	Hotel ID provided by hotel suppliers	GATHI
hotelName	string	No	Hotel Name provided by hotel suppliers	Hilton xxx Resort & Spa
supplierId	string	Yes	Supplier ID in DerbySoft's system	HILTON
status	enum	Yes	Enum: [Actived, Deactived] Hotel Status provided by hotel suppliers	Actived

Hotel Products

Distributors use the API to retrieve hotel products for a particular hotel, then activate/deactivate these on their system according to the status (Active/Deactived). Hotel products should be synced on a regular schedule(daily is preferred).

GET /hotel/{supplierId}/{hotelId}?distributorId={distributorId} HTTP/1.1
URL: {endpoint}/hotel/{supplierId}/{hotelId}?distributorId={distributorId}
Authorization:Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Parameters

Name	Description	Required	Type	Example
supplierId	The ID of the supplier in DerbySoft's system	Yes	string	HILTON
hotelId	Hotel ID provided by hotel suppliers	Yes	string	GATHI
distributorId	The ID of distributor in DerbySoft's system	Yes	string	TUI

Response Example

Success Response (HTTP Status 200)

{
  "hotelId": "GATHI",
  "hotelName": "This is a test hotel",
  "supplierId": "HILTON",
  "status": "Actived",
  "chainCode": "Hilton",
  "brandCode": "Hampton",
  "longitude": "41.40338",
  "latitude": "2.17403",
  "city": "string",
  "country": "string",
  "state": "string",
  "address": [
    "AddressLine1",
    "AddressLine2",
    "AddressLine3",
    "AddressLine4",
    "AddressLine5"
  ],
  "phone": {
    "countryAccessCode": "string",
    "areaCityCode": "string",
    "phoneNumber": "string"
  },
  "settings": {
    "key1": "value1",
    "key2": "value2"
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
   },
  "ariType": "Daily",
  "timezone": "America/Los_Angeles",
  "rateType": "AmountBeforeTax",
  "maxChildAge": 17,
  "childRateType": "ByAge",
  "products": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "stayType": "OverNightRoom",
      "status": "Actived",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateName": "Bar Rate",
      "rateDescription": "Begin your day with a hearty meal.",
      "occupancy": {
        "maxAdult": 3,
        "maxChild": 2,
        "maxOccupancy": 3
      },
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "cancelPolicies": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "cancelPolicy": {
            "code": "1D1N_1N",
            "description": "Cancellations or changes to bookings for this room will be charged the first night of the booking in 1 day before arrival date, if no show, will be charged the first night of the booking.",
            "cancelPenalties": [
                {
                    "noShow": false,
                    "cancellable": true,
                    "cancelDeadline": {
                        "offsetTimeDropType": "BeforeArrival",
                        "offsetTimeUnit": "D",
                        "offsetTimeValue": 1
                    },
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                },
                {
                    "noShow": true,
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                }
            ]
          }
        }
      ],
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "bookingChannels": [
        "channel",
        "channel"
      ],
      "sourceMarkets": [
        "region",
        "region"
      ],
      "productAddons": [
        {
          "type": "DisneyTicket",
          "required": true,
          "candidateCodes": [
            "code",
            "code"
          ]
        }
      ]
    }
  ]
}

Successful Response from Exchange Connection and RETAIL Rate Model(HTTP Status 200)

{
  "hotelId": "GATHI",
  "hotelName": "This is a test hotel",
  "supplierId": "HILTON",
  "status": "Actived",
  "chainCode": "Hilton",
  "brandCode": "Hampton",
  "longitude": "41.40338",
  "latitude": "2.17403",
  "city": "string",
  "country": "string",
  "state": "string",
  "address": [
    "AddressLine1",
    "AddressLine2",
    "AddressLine3",
    "AddressLine4",
    "AddressLine5"
  ],
  "phone": {
    "countryAccessCode": "string",
    "areaCityCode": "string",
    "phoneNumber": "string"
  },
  "settings": {
    "key1": "value1",
    "key2": "value2"
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
   },
  "ariType": "Daily",
  "timezone": "America/Los_Angeles",
  "rateType": "AmountBeforeTax",
  "maxChildAge": 17,
  "childRateType": "ByAge",
  "products": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "rateModel": "RETAIL",
      "connectionType": "Exchange",
      "stayType": "OverNightRoom",
      "status": "Actived",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateName": "Bar Rate",
      "rateDescription": "Begin your day with a hearty meal.",
      "occupancy": {
        "maxAdult": 3,
        "maxChild": 2,
        "maxOccupancy": 3
      },
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "cancelPolicies": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "cancelPolicy": {
            "code": "1D1N_1N",
            "description": "Cancellations or changes to bookings for this room will be charged the first night of the booking in 1 day before arrival date, if no show, will be charged the first night of the booking.",
            "cancelPenalties": [
                {
                    "noShow": false,
                    "cancellable": true,
                    "cancelDeadline": {
                        "offsetTimeDropType": "BeforeArrival",
                        "offsetTimeUnit": "D",
                        "offsetTimeValue": 1
                    },
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                },
                {
                    "noShow": true,
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                }
            ]
          }
        }
      ],
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "bookingChannels": [
        "channel",
        "channel"
      ],
      "sourceMarkets": [
        "region",
        "region"
      ],
      "productAddons": [
        {
          "type": "DisneyTicket",
          "required": true,
          "candidateCodes": [
            "code",
            "code"
          ]
        }
      ],
      "commissions": [
        {
          "startDate": "2018-01-01",
          "endDate": "2018-01-04",
          "value": 10,
          "type": "percentage"
        }
      ]
    }
  ]
}

Successful Response from Exchange Connection and NET Rate Model(HTTP Status 200)

{
  "hotelId": "GATHI",
  "hotelName": "This is a test hotel",
  "supplierId": "HILTON",
  "status": "Actived",
  "chainCode": "Hilton",
  "brandCode": "Hampton",
  "longitude": "41.40338",
  "latitude": "2.17403",
  "city": "string",
  "country": "string",
  "state": "string",
  "address": [
    "AddressLine1",
    "AddressLine2",
    "AddressLine3",
    "AddressLine4",
    "AddressLine5"
  ],
  "phone": {
    "countryAccessCode": "string",
    "areaCityCode": "string",
    "phoneNumber": "string"
  },
  "settings": {
    "key1": "value1",
    "key2": "value2"
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
   },
  "ariType": "Daily",
  "timezone": "America/Los_Angeles",
  "rateType": "AmountBeforeTax",
  "maxChildAge": 17,
  "childRateType": "ByAge",
  "products": [
    {
      "roomId": "10000101",
      "rateId": "123456",
      "rateModel": "NET",
      "connectionType": "Exchange",
      "stayType": "OverNightRoom",
      "status": "Actived",
      "roomName": "Double Room",
      "roomDescription": "Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.",
      "rateName": "Bar Rate",
      "rateDescription": "Begin your day with a hearty meal.",
      "occupancy": {
        "maxAdult": 3,
        "maxChild": 2,
        "maxOccupancy": 3
      },
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "cancelPolicies": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "cancelPolicy": {
            "code": "1D1N_1N",
            "description": "Cancellations or changes to bookings for this room will be charged the first night of the booking in 1 day before arrival date, if no show, will be charged the first night of the booking.",
            "cancelPenalties": [
                {
                    "noShow": false,
                    "cancellable": true,
                    "cancelDeadline": {
                        "offsetTimeDropType": "BeforeArrival",
                        "offsetTimeUnit": "D",
                        "offsetTimeValue": 1
                    },
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                },
                {
                    "noShow": true,
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                }
            ]
          }
        }
      ],
      "fees": [
        {
          "dateRange": {
            "startDate": "2018-01-01",
            "endDate": "2018-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "bookingChannels": [
        "channel",
        "channel"
      ],
      "sourceMarkets": [
        "region",
        "region"
      ],
      "productAddons": [
        {
          "type": "DisneyTicket",
          "required": true,
          "candidateCodes": [
            "code",
            "code"
          ]
        }
      ]
    }
  ]
}

Error Response (HTTP Status 401)

{
    "error": "Key not authorized"
}

Error Response (HTTP Status 500)

{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}

Response Specification

Attribute	Type	Required	Description	Example
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
hotelName	string	No	Hotel name in supplier's system	This is a test hotel
supplierId	string	Yes	Supplier ID in DerbySoft's system	HILTON
status	enum	Yes	Enum: [ Actived, Deactived ] Status in supplier's system	Actived
chainCode	string	No	The chain code may identify a hotel chain or management group, e.g. Hyatt, Hilton. The hotel chain code is decided between suppliers and is optional if the hotel is an independent property that can be identified by the hotelId field alone.	Marriott
brandCode	string	No	The brand code may identify the brand within a chain, e.g. Courtyard, Hampton Inn. This field is optional if the hotel is an independent property that can be identified by the hotelId field alone.	Waldorf
longitude	string	No	The information for hotel location.	41.40338
latitude	string	No	The information for hotel location.	2.17403
city	string	No	/	/
country	string	No	/	/
state	string	No	/	/
address	array	No	Support up to five enumeration values	[ "AddressLine1", "AddressLine2", "AddressLine3", "AddressLine4", "AddressLine5" ]
phone	object	No	/	/
@countryAccessCode	string	Yes	/	/
@areaCityCode	string	No	/	/
@phoneNumber	string	Yes	/	/
settings	object	No	An additional field is used for transmitting extra settings, accounts, etc that are required by Distributors	{ "key": "value" }
extensions	object	No	It is used to provide the rate cluster information for Marriott properties. This additional field will consist of a cluster code and its corresponding rate plan IDs. It is optional but available to all distributors connecting to Marriott who wish to receive rate cluster indicators.	{ "key1": "value1", "key2": "value2" }
ariType	enum	Yes	Emun:[ Daily, LOS ] Indicates which ARI model be used for ARI API	Daily
timezone	string	Yes	Timezone of property	America/Los_Angeles
rateType	enum	Yes	Emun:[ AmountBeforeTax, AmountAfterTax, Both ] Indicates which rate will be used in ARI and Reservation. AmountBeforeTax: only AmountBeforeTax is pushed out to distributors, and only AmountBeforeTax is sent back to the supplier. AmountAfterTax: only AmountAfterTax is pushed out to distributors, and only AmountAfterTax is sent back to the supplier. Both: AmountBeforeTax & AmountAfterTax will be pushed to Distributors.	AmountBeforeTax
maxChildAge	integer	No	maxChildAge will be provided If childRateType is ByAge.	/
childRateType	enum	No	Enum: [ Normal, ByAge, Free, AsAdult ] Indicates which child rate type will be used in ARI OccupancyRate. Normal: This is the default option, hotels provide rates for a combination of adults and children. ByAge: Hotels provide extra child pricing based on age bands, maxChildAge field will be provided as well as extraChildRates nodes will be provided in ARI. Free: Hotels indicate children as free of charge to stay, maxChildAge may be provided. AsAdult: Hotels indicate children will be charged the same rate as adults for their stay.	ByAge
products	array	Yes	/	/
@roomId	string	Yes	Room ID in supplier's system	King
@rateId	string	Yes	Rate ID in supplier's system	BAR
@rateModel	enum	No	Enum: [RETAIL, NET] Rate model of the product	RETAIL
@connectionType	enum	No	Enum: [Exchange, Standard] Indicates the connection type of product. Notes: If the connection type is not specified or labeled as "Standard", neither the "rateModel" nor the "commissions" field/node will appear.	Standard
@stayType	enum	No	Enum: [ OverNightRoom, DayUseRoom ] This tag indicates if the product is specifically for day-use or regular overnight use. The default is OverNightRoom.	OverNightRoom
@status	enum	Yes	Enum: [ Actived, Deactived ]	Actived
@roomName	string	No	Room type name Max length: 256	King Room
@roomDescription	string	No	/	Soak in city views in our Deluxe room, which features a well-appointed ensuite bathroom and up-to-date entertainment offerings.
@rateName	string	No	Rate plan name Max length: 256	Best Available Rate
@rateDescription	string	No	/	Begin your day with a hearty meal
products/occupancy	/	Yes	/	/
@maxAdult	integer	Yes	Max adult count	3
@maxChild	integer	Yes	Max child count	2
@maxOccupancy	integer	Yes	Max occupancy	3
@paymentType	enum	No	Enum: [ PayLater, PayNow ] Indicates the product is prepaid to the hotel(PayNow) or pay at the hotel(PayLater).	PayNow
products/guarantee	/	No	/	/
@guaranteeType	string	Yes	Guarantee information for this room rate. The type of guarantee method, refers to the standard guarantee type list.	CCG
products/cancelPolicies	/	No	/	/
cancelPolicies/dateRange	object	No	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2018-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2018-01-04
cancelPolicies/cancelPolicy	object	No	/	/
@code	string	Yes	Code of cancel policy Max Length: 128	AD100P_100P
@description	string	No	The description of the cancellation policy Max Length: 1024	Non Refundable
cancelPolicy/cancelPenalties	/	Yes	Detail about the cancellation Penalty	/
@noShow	boolean	Yes	If true, it means the penalty charge is applied for No-Show, and the cancellable and cancelDeadline nodes won't appear.	/
@cancellable	boolean	No	Indicates if cancellation is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline node will appear.	/
cancelPenalties/cancelDeadline	/	/	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit.	/
@deadline	string	No	Local deadline times allowed for cancellation, like 4 PM, 6 PM	/
cancelPenalties/penaltyCharge	/	Yes	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBased, the nights are required.	/
@nights	number	No	Exists if the penalty charge is based on the night, like the first night	/
@amount	number	No	Exists if the penalty charge is a flat charge, like USD 30.00	/
@percent	number	No	Exists if the penalty charge is percent, like 15.5 means 15.5%	/
products/fees	/	No	/	/
fees/dateRange	/	No	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2018-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2018-01-04
fees/fee	object	No	/	/
@name	string	Yes	The name of the fee or tax	Service Charge
@type	enum	Yes	Enum: [ Inclusive, Exclusive ] Indicates fees or tax is included in the amount before tax or not.	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	enum	Yes	Enum: [ Fix, Percent ] Indicates how to charge the tax, 10% per room per night in this example.	Percent
@chargeType	enum	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Enum: [ PayLater, PayNow ] Indicates if the fee is prepaid to hotels(PayNow) or paid at the hotel(PayLater).	PayNow
@effectivePerson	number	No	It indicates the fee will be charged starting from which occupancy, such as the "Extra Person Charge" fee. The EffectivePerson is 3, meaning an extra fee will be applied from the third person onward.	3
products/bookingChannels	array[string]	No	/	["channel1", "channel2"]
products/sourceMarkets	array[string]	No	Sold to specific markets	["region1", "region2"]
products/productAddons	array[object]	No	/
@type	string	Yes	product addon type	DisneyTicket
@required	boolean	Yes	Indicate whether the addon must be chosen with the room	true
productAddons/candidateCodes	array[string]	Yes	/	["code1", "code2"]
products/commissions	array[object]	No	/	/
@startDate	string	No	Start date of commission, format with yyyy-MM-dd	2018-01-01
@endDate	string	No	End date of commission, format with yyyy-MM-dd	2018-01-04
@value	number	Yes	Commission value	10
@type	enum	Yes	Commission type Enum: [ percentage, amount ]	percentage

BookingUSB-Hotel APIs

Introduction

Hotel List

Request Parameters

Response Example

Response Specification

Hotel Products

Request Parameters

Response Example

Response Specification