Distributor Knowledge Base

TABLE OF CONTENTS

Introduction
Ping
- Response Example
Hotel Setup
Shopping

Introduction

ShoppingEngine is a high-performance shopping API that enables distributors to query multiple hotels from the ARI cache. It supports inbound messages from the distributor's system and provides high accuracy and TPS.

APIs marked with "☆" are mandatory for Distributors to implement, while those marked with "◎" are optional but recommended.

◎ Ping(/ping) - GO Distributors utilize the API to check whether the endpoint is functional or not.
☆ Hotel Setup(/hotels/{supplierId}/setup) - GO Distributors call the API to activate/deactivate hotels in DerbySoft.
☆ Shopping(/shopping/multihotels) - GO Distributors are using the Shopping API to shop ARI from DerbySoft Cache.

Note: The URL domain for the ShoppingEngine Endpoint is distinct from that of the BookingUSB Endpoint.

Important Notes:
GO provides separate endpoints  for Pull Model Distributors.
① BookingUSB Endpoint - It uses for booking flow. For PCI DSS Compliance purposes, Reservation services deploy in a security isolation environment. Therefore the URL is specific and will be different from the ShoppingEngine Endpoint. 
URL Example: https://xxx.derbysoftca.com/api/go/bookingusb/v4
②ShoppingEngine Endpoint - It uses for ARI flow. ARI Services deploy in Non-reservation Environment. Therefore the domain of the URL is another one.
URL Example: https://xxx.derbysoftsec.com/api/go/shoppingengine/v4

Ping

This is an API for Go distributors to call Go’s system to determine if the API is working or not.

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

Response Example

Success Response (HTTP Status 200)

"ok"

Error Response (HTTP Status 401)

{
    "error": "Key not authorised"
}

Error Response (HTTP Status 500)

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

Hotel Setup

GO Distributors call the API to activate/deactivate hotels in DerbySoft GO.

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

Request Example

{
  "header": {
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotels": [
    {
      "supplierId": "HILTON",
      "hotelId": "GATHI",
      "status": "Actived"
    }
  ]
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@distributorId	string	Yes	Max Length: 32 The ID of distributor in DerbySoft's system	GTA
@version	string	Yes	Max Length: 20 Version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be a UUID identity.	18393849028490234
hotels	array	Yes	Hotel list to set up	/
@supplierId	string	Yes	The ID of the hotel supplier in DerbySoft's system	HILTON
@hotelId	string	Yes	Hotel ID in supplier's system	GATHI
@status	enum	Yes	Enum:[Actived,Deactived] Hotel status in distributors' system	Actived

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelCount": 100
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	GTA
@version	string	Yes	Max Length: 20 version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
hotelCount	integer	No	Available inventory count according to request criteria.	100

Shopping

Shop availability, rate, and inventory - query available room rates of multiple hotels.

This request hits the DerbySoft ARI Cache.
Up to 20 hotels and a max of 61 days of data can be queried by GO Distributors in a single request.

POST /shopping/multihotels HTTP/1.1
URL: {{endpoint}}/shopping/multihotels
Authorization:Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
    "header": {
        "distributorId": "GTA",
        "version": "v4",
        "token": "18393849028490234"
    },
    "hotels": [
        {
            "supplierId": "HILTON",
            "hotelId": "GATHI",
            "status": "Actived",
            "isAfterPromotion": false,
            "promoteCode": "string"
        }
    ],
    "stayRange": {
        "checkin": "2018-01-01",
        "checkout": "2018-01-04"
    },
    "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
            4,
            8
        ]
    },
    "iata": "string",
    "extensions": {
        "key1": "key1",
        "key2": "key2"
    }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@distributorId	string	Yes	Max Length: 32 Distributor ID in DerbySoft's system	GTA
@version	string	Yes	Max Length: 20 Version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be a UUID identity.	18393849028490234
hotels	array	Yes	/	/
@supplierId	string	Yes	Supplier ID in DerbySoft's system	HILTON
@hotelId	string	Yes	Hotel Supplier's Hotel ID	GATHI
@status	enum	No	Enum: [Actived, Deactived] Hotel status in distributor's system	Actived
@isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. true means to check the availability under the promotion rules provided by the supplier. false means no need to check the availability under any promotions, basic live-check only.	false
@promoteCode	string	No	Promote code defined by the hotel, is an optional field when you want to request the promotion rates. (isAfterPromotion = true). If the promotion code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2018-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2018-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Number of adults staying per room	1
@childCount	integer	No	Number of children staying per room	2
@childAges	integer	No	Ensure the size of the child age array matches the number of children.	[4, 8]
IATA	string	No	IATA of distributor	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field.	{ "key1": "value1", "key2": "value2" }

Response Example

Success Response (HTTP Status 200)

{
  "header": {
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "iata": "string",
  "availHotels": [
    {
      "supplierId": "HILTON",
      "hotelId": "GATHI",
      "status": "Actived",
      "stayRange": {
        "checkin": "2018-01-01",
        "checkout": "2018-01-04"
      },
      "iata": "string",
      "availRoomRates": [
        {
          "roomId": "K1D",
          "rateId": "ODAD01",
          "currency": "USD",
          "amountBeforeTax": [
            100,
            100,
            120
          ],
          "amountAfterTax": [
            110,
            110,
            130
          ],
          "mealPlan": "RO",
          "paymentType": "PayNow",
          "guarantee": {
            "guaranteeType": "CCG"
          },
          "fees": [
            {
              "dateRange": {
                "startDate": "2018-01-01",
                "endDate": "2018-01-04"
              },
              "fee": {
                "name": "Service Charge",
                "type": "Exclusive",
                "amount": 10,
                "amountType": "Percent",
                "chargeType": "PerRoomPerNight",
                "effectivePerson": 2
              }
            }
          ],
          "cancelPolicy": {
            "code": "12AM2D1N_1N",
            "description": "48 hrs prior to arrival ",
            "cancelPenalties": [
                {
                    "noShow": false,
                    "cancellable": true,
                    "cancelDeadline": {
                        "offsetTimeDropType": "BeforeArrival",
                        "offsetTimeUnit": "D",
                        "offsetTimeValue": 2,
                        "deadline": "12AM"
                    },
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                },
                {
                    "noShow": true,
                    "penaltyCharge": {
                        "chargeBase": "NightBase",
                        "nights": 1
                    }
                }
            ]
        },
          "roomCriteria": {
            "roomCount": 2,
            "adultCount": 1,
            "childCount": 2,
            "childAges": [
              4,
              8
            ]
          },
          "inventory": 2,
          "isAfterPromotion": false,
          "promoteCode": "string"
        }
      ]
    }
  ]
}

Error Response (HTTP Status 401)

{
    "error": "Key not authorised"
}

Error Response (HTTP Status 500)

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

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@distributorId	string	Yes	Max Length: 32 ID of distributor in DerbySoft's system	GTA
@version	string	Yes	Max Length: 20 Version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be a UUID identity.	18393849028490234
IATA	string	No	IATA of distributor	/
availHotels	array	Yes	/	/
@supplierId	string	Yes	ID of hotel supplier in DerbySoft's system	HILTON
@hotelId	string	Yes	Hotel ID in supplier's system	GATHI
@status	enum	No	Enum:[Actived,Deactived] Hotel status in distributor's system	Actived
availHotels/stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2018-01-01
@checkout	string	Yes	Checkout, format with yyyy-MM-dd	2018-01-04
availHotels/IATA	string	No	IATA of distributor	/
availHotels/availRoomRates	array	Yes	Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in API.
@roomId	string	Yes	Room ID in supplier's system	10000101
@rateId	string	Yes	Rate ID in supplier's system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount of rate without tax and fee	[100,100,120]
@amountAfterTax	array[number]	No	The daily amount of rate with tax and fee	[110,110,130]
@mealPlan	string	No	For meal plan code, refer to the meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum:[PayLater,PayNow].	PayNow
availRoomRates/guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	The type of guarantee method, refers to the guarantee type list.	CCG
availRoomRates / fees	array[object]	No	Fee or tax by date range.	/
fees/dateRange	object	Yes	/	/
@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	Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	Indicates whether or not the fee or tax is included in the amount before tax. Enum: [Inclusive, Exclusive].	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example. Enum: [ Fix, Percent ].	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@effectivePerson	integer	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
availRoomRates/cancelPolicy	object	No	The cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to a No-Show or a time range before a No-Show.	/
@code	string	Yes	Max Length: 128 Code of cancellation policy	AD100P_100P
@description	string	No	Max Length: 1024 Description of the cancel policy.	Non Refundable
cancelPolicy/cancelPenalties	array	Yes	Details about the cancellation penalty	/
@noShow	boolean	Yes	If true means the penalty charge was applied for a No-Show, the cancelable and cancelDeadline nodes will be omitted.	/
@cancellable	boolean	No	Specifies whether cancellation is allowed. If false, cancellation is not allowed. If true, the cancelDeadline node will be present.	/
cancelPenalties/cancelDeadline	object	No	/	/
@offsetTimeDropType	enum	No	An enumerated type indicates when the deadline drop time goes into effect. Enum: [BeforeArrival].	/
@offsetTimeUnit	enum	No	Enum:[D,H]	/
@offsetTimeValue	string	No	The number of offset times with the time unit	/
@deadline	string	No	Deadline times for cancellation are typically based on the hotel's local time, usually at either 4 PM or 6 PM.	/
cancelPenalties/penaltyCharge	object	Yes	/	/
@chargeBase	enum	No	If FullStay, it will be a percentage or amount, if NightBase, the nights are required Enum:[FullStay, NightBase].	/
@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%	/
availRoomRates/roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Number of adults staying per room	1
@childCount	integer	No	Number of children staying per room	2
@childAges	integer	No	Ensure the size of the child age array matches the number of children.	[4,8]
availRoomRates/inventory	integer	Yes	Available inventory count according to request criteria.	2
availRoomRates/isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. true means to check the availability that is under the promotion rules provided by the Supplier. false means no need to check the availability under any promotions, basic live-check only.	false
availRoomRates/promoteCode	string	No	Promote code defined by the hotel, it's an optional field when you want to request the promotion rates (isAfterPromotion = true). If the promotion code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/

ShoppingEngine(Pull Model)

Introduction

Ping

Response Example

Hotel Setup

Request Example

Request Specification

Response Example

Response Specification

Shopping

Request Example

Request Specification

Response Example

Response Specification