Business Travel Suite Knowledge Base

As part of our design update, the screenshots are currently being revised.

TABLE OF CONTENTS

Hotels API
Hotel API

Change Log:

V.1.2.1

Add 'rateFlag' to the hotel product API, which indicates the product type.
- PUB: Public rates.
- CWD: Chain-wide discount. The products are dynamically changed and offer a certain percentage off the best available rates.
- RFP: Static negotiated rates. The rates are negotiated by corporations with suppliers and can be accessed via special corpCode.

Remove all the supplierCodein URL
Remove the promotionassociation attributes
Remove addOnassociation attributes

Hotels API

The Hotels API is used by distributors to retrieve the list of hotels and then turn hotels on or off in their own system according to the hotel status (Actived/Deactivated). This API should be retrieved on a regular schedule (daily is preferred).

Important：
If the distributor specifies a corpCode, BTS will filter the supplier hotels specific to the corpCode.
If the distributor does not specify any corpCode, BTS will return all the supplier hotels.

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

Request Parameters

Attribute	Type	Required	Description	Example
supplierId	String	Yes	Supplier ID in DerbySoft’s system	HILTON
distributorId	String	Yes	Distributor ID in DerbySoft's system	TUI
corpCode	String	No	Corp ID in distributor’s system	DIS

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 in supplier's system	GATHI
hotelName	string	No	Hotel name	Hilton hotel resorts
supplierId	string	Yes	Supplier ID in DerbySoft's system	HILTON
status	enum	Yes	Enum: [ Actived, Deactived ] Status in distributor's system	Actived

Hotel API

Hotel API used by distributors to retrieve hotel products for a particular hotel, then turn on or off hotel products on their own system according to the hotel product status (Actived/Deactived). This API should be retrieved on a regular schedule (daily is preferred).

GET /hotel/{supplierId}/{hotelId}?distributorId={distributorId}&supplierId={supplierId} HTTP/1.1
URL: {endpoint}/hotel/{supplierId}/{hotelId}?distributorId={distributorId}&supplierId={supplierId}
Authorization:Bearer {apiKey}
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	The ID of the hotel in the Supplier's system	Yes	string	GATHI
distributorId	The ID of distributor in DerbySoft's system	Yes	string	TUI
corpCode	Corp ID in distributors' system	No	string	DIS

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": {
      "M96": "FBJL,MWSU,YRNB,RMOT",
      "13.RPT": "LLRJ,XXRN,UAON,HDYB"
   },
  "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": "2024-01-01",
            "endDate": "2024-01-04"
          },
          "cancelPolicy": {
            "code": "AD100P_100P",
            "description": "Non Refundable",
            "cancelPenalties": [
              {
                "noShow": true,
                "cancellable": true,
                "cancelDeadline": {
                  "offsetTimeDropType": "BeforeArrival",
                  "offsetTimeUnit": "D",
                  "offsetTimeValue": 999,
                  "deadline": "string"
                },
                "penaltyCharge": {
                  "chargeBase": "FullStay",
                  "nights": 0,
                  "amount": 0,
                  "percent": 0
                }
              }
            ]
          }
        }
      ],
      "fees": [
        {
          "dateRange": {
            "startDate": "2024-01-01",
            "endDate": "2024-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.	Hilton
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.	Hamption
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	Yes	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: both AmountBeforeTax & AmountAfterTax is pushed out to distributor, and both AmountBeforeTax & AmountAfterTax is sent back to supplier.	AmountBeforeTax
maxChildAge	integer	No	If childRateType is set as ByAge, max child age must be provided and greater than zero.	/
childRateType	enum	No	Enum: [ Normal, ByAge, Free, AsAdult ] Indicates which child rate type will be used in ARI OccupancyRate. Normal: by default, the occupancy rate is combined with adult rate and child rate without age settings. ByAge: the child will be charged by age, maxChildAge must be provided, and extraChildRates should be provided in ARI. Free: the child is free, maxChildAge may be provided. AsAdult: the child will be charged as an adult.	ByAge
products	array	Yes	/	/
@roomId	string	Yes	Room ID in supplier's system	King
@rateId	string	Yes	Rate ID in supplier's system	BAR
@rateFlag	enum	No	Product type. [PUB, CWD, RFP] PUB: Public rates CWD: Chain-wide discount rates RFP: Static negotiated rates	CWD
@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. guarantee type list.	CCG
products/cancelPolicies	/	No	/	/
cancelPolicies/dateRange	object	No	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-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 cancel 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	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees/fee	object	No	/	/
@name	string	Yes	The name of the fee or tax	Service Charge
@type	enum	Yes	Enum: [ Inclusive, Exclusive ] The fee 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	This means that this fee will be charged based on how many persons, like an extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
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	/	true
productAddons/candidateCodes	array[string]	Yes	/	["code1", "code2"]