旧版文档将于2025年11月30日下线，您可以查看新版或了解更新日志。

TABLE OF CONTENTS

介绍

ShoppingEngine 用于渠道在 DerbySoft GO 系统中激活酒店以及获取可预订 ARI 缓存数据。它能提供高性能、高精度和高TPS 的 ARI Shopping 服务。


ShoppingEngine 提供以下接口供渠道调用：

  • Ping（/ping）- 渠道调用 GO 接口，来检测其系统是否正常。
  • 酒店设置（/hotels/{supplierId}/setup）- 渠道调用此接口在 GO 系统中激活或停用酒店。
  • Shopping (/shopping/multihotels) - 渠道调用此接口从 GO 系统中获取可预订 ARI 缓存数据。



Ping

渠道可调用此接口来检查DerbySoft GO的系统是否正常工作。 

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


响应示例

  • 成功响应（HTTP状态200）

"ok"
  • 错误响应（HTTP状态401）
{
    "error": "Key not authorised"
}
  • 错误响应（HTTP状态500）
{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}



酒店设置

渠道调用此接口在 GO系统中激活或停用酒店。请先激活酒店，再从 GO 系统中获取 ARI 缓存数据。反之如果停用酒店，则无法获取 ARI 缓存数据。

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


请求示例

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


请求规范

属性

类型

必传字段

描述

示例
headerobjectYes//

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

用于标识请求和响应的唯一ID，通常应为UUID

18393849028490234

hotels

array

Yes

要激活/停用的酒店列表

 /

@supplierId

string

Yes

酒店集团 ID

HILTON

@hotelId

string

Yes

酒店代码

GATHI

 @status

 enum

Yes

枚举：[Actived，Deactived]

酒店状态

 Active



响应示例

  • 成功响应（HTTP状态200）

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



响应规范

属性

类型

必传字段？

描述

示例

header

object

Yes

 /

 /

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

用于标识请求和响应的唯一ID，通常应为UUID

18393849028490234

hotelCount

integer

No

设置成功的酒店数量

20



Shopping

渠道调用此接口从 GO 系统中获取可预订 ARI 数据。此请求是访问GO的 ARI 缓存，一个请求最多支持查询20家酒店。

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


请求示例

{
    "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"
    }
}


请求规范

属性

类型

必传字段？

描述

示例

header

object

Yes

 /

 /

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

用于标识请求和响应的唯一ID，通常应为UUID

18393849028490234

hotels

array

Yes

 /

 /

@supplierId

string

Yes

酒店集团 ID

HILTON

@hotelId

string

Yes

酒店代码

GATHI

 @status

enum

No

枚举：[Actived，Deactived]

激活或停用酒店

 Actived

@isAfterPromotion

boolean

No

该标志表示是否根据促销规则计算可用房价。

true表示根据酒店集团提供的促销规则检查可用性。

false意味着不需要检查任何促销活动的可用性，只需进行基本的实时检查。

false

@promoteCode

string

No

由酒店定义的促销代码是您请求促销费率时的可选字段。（isAfterPromotion=true）。

如果促销代码为空，并且一个产品同时有多个促销，则将根据多促销策略选择促销规则。

 /

stayRange

object

Yes

 /

 /

@checkin

string

Yes

入住日期，格式为yyyy-MM-dd

2018-01-01

@checkout

string

Yes

离店日期，格式为yyyy-MM-dd

2018-01-04

roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

integer

No

与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄。

[ 4, 8 ]

IATA

string

No

渠道 IATA

 /

extensionsobjectNo

{

    "key1": "value1",

    "key2": "value2"

}



响应示例

  • 成功响应（HTTP状态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": "AD100P_100P",
            "description": "Non Refundable",
            "cancelPenalties": [
              {
                "noShow": true,
                "cancellable": true,
                "cancelDeadline": {
                  "offsetTimeDropType": "BeforeArrival",
                  "offsetTimeUnit": "D",
                  "offsetTimeValue": 0,
                  "deadline": "6PM"
                },
                "penaltyCharge": {
                  "chargeBase": "FullStay",
                  "nights": 0,
                  "amount": 0,
                  "percent": 0
                }
              }
            ]
          },
          "roomCriteria": {
            "roomCount": 2,
            "adultCount": 1,
            "childCount": 2,
            "childAges": [
              4,
              8
            ]
          },
          "inventory": 2,
          "isAfterPromotion": false,
          "promoteCode": "string"
        }
      ]
    }
  ]
}
  • 错误响应（HTTP状态401）
{
    "error": "Key not authorised"
}
  • 错误响应（HTTP状态500）
{
  "errorCode": "InvalidField",
  "errorMessage": "Invalid Message"
}


响应规范

属性

类型

必传字段

描述

示例

header

object

Yes

 /

 /

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

用于标识请求和响应的唯一ID，通常应为UUID

18393849028490234

IATA

string

No

渠道 IATA

 /

availHotels

array

Yes

 /

 /

@supplierId

string

Yes

酒店集团 ID

HILTON

@hotelId

string

Yes

酒店代码

GATHI

@status

enum

No

枚举：[Actived，Deactived]

酒店状态

 Actived

availHotels / stayRange

object

Yes

 /

 /

@checkin

string

Yes

入住日期，格式为yyyy-MM-dd

2018-01-01

@checkout

string

Yes

离店日期，格式为yyyy-MM-dd

2018-01-04

availHotels / IATA

string

No

渠道 IATA

 /

availHotels / availRoomRates

array

Yes

餐食计划、税费和取消政策是可选字段，因为一些渠道在API中不支持这些字段。

 

@roomId

string

Yes

房型代码

10000101

@rateId

string

Yes

价格计划代码

123456

@currency

string

Yes

币种代码 [ISO-4217]

USD

@amountBeforeTax

array[number]

No

税前价

[ 100, 100, 120 ]

@amountAfterTax

array[number]

No

税后价

[ 110, 110, 130 ]

@mealPlan

string

No

餐食计划代码，参考标准 meal plan code list.

RO

@paymentType

enum

No

表示产品已预付至酒店（PayNow）或入住时在酒店前台付款（PayLater）

枚举：[PayLater，PayNow]。

PayNow

availRoomRates / guarantee

object

No

房费的担保信息

 /

@guaranteeType

string

Yes

担保方法类型，参考标准 guarantee type list.

CCG

availRoomRates / fees

array[object]

No

按日期范围列出的费用或税款

 /

fees / dateRange

object

Yes

时间范围

 /

@startDate

string

Yes

开始日期，格式为yyyy-MM-dd

2018-01-01

@endDate

string

Yes

结束日期，格式为yyyy-MM-dd

2018-01-04

fees/fee

 object

Yes

 /

 /

@name

string

Yes

Pattern: \w[\w\d]+

Service Charge

@type

enum

Yes

税费是否包含在税前价中。


枚举：[Inclusive，Exclusive]

Exclusive

@amount

number

Yes

税费金额

10

@amountType

string

Yes

税费收取规则，是固定金额收取，还是按房费比例收取


枚举：[Fix，Percent]

Percent

@chargeType

string

Yes

枚举：[PerRoomPerNight，PerPersonPerNight、PerRoomPerStay、PerPersonPerStay]

PerRoomPerNight

@effectivePerson

integer

No

表示这个fee要从第几个人开始收取

2

availRoomRates / cancelPolicy

object

No

取消政策定义了当客人在特定提前时间范围内取消预订时将收取的罚金。罚金与未入住或入住前的时间范围有关

 /

@code

string

Yes 

最大长度：128

取消政策代码

AD100P_100P

@description

string

No 

最大长度：1024

取消政策描述

Non Refundable

cancelPolicy / cancelPenalties

array

Yes

取消政策详情

 /

@noShow

boolean

Yes

如果为true，则意味着罚金适用于“未入住”，cancellable 和 cancelDeadline 两个节点将不会出现。

 /

@cancellable

boolean

No

标示是否允许取消。如果为false，则不可取消。如果为true，cancelDeadline 节点将出现。

 /

cancelPenalties / cancelDeadline

object

No

 /

 /

@offsetTimeDropType

enum

No

枚举类型标示取消政策以入住日期或预订日期为依据。目前只支持入住日期类型

枚举：[BeforeArrival]。

 /

@offsetTimeUnit

enum

No

 

枚举: [ D, H ]

 /

@offsetTimeValue

string

No

时间数

 /

@deadline

string

No

取消截止时间，一般为酒店所在地时间，如下午4点前和下午6点前。

 /

cancelPenalties / penaltyCharge

object

Yes

 /

 /

@chargeBase

enum

No

如果是FullStay，则为百分比或金额；如果是NightBase，则需要通过 nights 节点提供间夜数。

枚举：[FullStay，NightBase]。

 /

@nights

number

No

罚款是基于入住晚数，如一晚。

 /

@amount

number

No

罚款是固定费用，如30.00美元。

 /

@percent

number

No

罚款是基于百分比，如15.5 为 15.5%.

 /

availRoomRates / roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

integer

No

儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄。

[ 4, 8 ]

availRoomRates / inventory

integer

Yes

根据请求条件的返回可用库存数量

2

availRoomRates / isAfterPromotion

boolean

No

该标志表示是否根据促销规则计算可用房价。

true是指根据酒店集团提供的促销规则检查可用性。

false意味着不需要检查任何促销活动的可用性，只需进行基本的实时检查。

false

availRoomRates / promoteCode

string

No

由酒店定义的促销代码，当您想要请求促销价时，它是一个可选字段（isAfterPromotion=true）。

如果促销代码为空，并且一个产品同时有多个促销代码时，则将根据多促销策略选择促销规则。

 /