作为我们设计更新的一部分，应用截图目前正在修订中。

TABLE OF CONTENTS


介绍

 Reservation 提供了订单流程相关接口，包括实时询价(单一酒店)、实时询价（单一产品）、预订、修改、取消，查询订单详情等接口。

  • 实时询价（/availability/{supplierId}）- 用于实时获取某一酒店的最新 ARI 数据。将向酒店集团发送请求以获取实时结果。
  • 实时询价（/livecheck/{supplierId}）- 用于实时获取某一产品的最新 ARI 数据。将向酒店集团发送请求以获取实时结果。



实施询价

此 API 用于实时获取某一酒店最新的 ARI 数据。将向酒店集团发送请求获取实时结果。

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

请求示例

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
},
"corpCode": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2024-01-01",
      "checkout": "2024-01-04"
    },
    "roomCriteria": {
      "roomCount": 2,
      "adultCount": 1,
      "childCount": 2,
      "childAges": [
        4,
        8
      ]
    },
    "productCandidate": {
      "roomId": "K1D",
      "rateId": "ODAD01"
    },
    "iata": "string",
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "isAfterPromotion": false,
    "promoteCode": "string",
    "bookingChannel": "string",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  }

请求规范

属性类型必要字段描述示例

header

object

Yes

 /

 /

@supplierId

string

Yes

最大长度：32

酒店集团ID

HILTON

@distributorId

string

Yes

最大长度：32

渠道ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

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

18393849028490234

corpCode

String

No

渠道企业协议代码

IBM

hotelId

string

Yes

酒店 ID

GATHI

stayRange

object

Yes

 /

 /

@checkin

string

Yes

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

2024-01-01

@checkout

string

Yes

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

2024-01-04

roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

array

No

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

[ 4, 8 ]

iata

string

No

渠道 IATA

 /

loyaltyAccount

object

No

 /

 /

@programCode

string

Yes

会员体系代码

BW

@accountId

string

Yes

会员号

1234567890123457

corpAccount

object

No

供应商企业协议代码

 /

@corpProgramCode

string

Yes

公司代码

CR

@corpId

string

Yes

协议价代码

A-1232

isAfterPromotion

boolean

No

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

  • true : 表示根据供应商提供的促销规则检查可用性。
  • false : 表示您无需检查任何促销活动的可用性，只需进行基本的实时检查。

false

promoteCode

string

 No

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

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

 /

bookingChannel

string

No

渠道 ID/子渠道 ID

/

extensions

object

No

可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft 将提供指定的格式)。请不要通过这个字段传送敏感信息。

 /


响应示例

  • 成功响应 (HTTP Status 200)
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "rateId": "ODAD01",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "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
          }
        }
      ],
      "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
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

  • 错误响应（HTTP Status 403）
{
    "error": "Key not authorized"
}

  • 错误响应（HTTP Status 500）
{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}


响应规范

属性类型必要字段描述示例

header

object

Yes

 /

 /

@supplierId

string

Yes

最大长度：32

酒店集团 ID

HILTON

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API版本

v4

@token

string

Yes

最大长度：64

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

18393849028490234

hotelId

string

Yes

酒店代码

GATHI

stayRange

object

Yes

 /

 /

@checkin

string

Yes

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

2024-01-01

@checkout

string

Yes

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

2024-01-04

roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

array

No

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

[ 4, 8 ]

iata

string

No

渠道 IATA

 /

roomRates

 

Yes

膳食计划、费用和取消政策是可选字段，因为一些分销商在 API 中不支持这些字段。

 /

@inventory

integer

Yes

房量/库存

1

@isAfterPromotion

boolean

No

该标志表示是否根据促销规则计算可用房价。如果为空，则默认值为 false

  • true: 表示检查渠道提供的促销规则是否可用。
  • false: 表示不检查促销规则是否可用，只做常规实时询价。

false

@promoteCode

string

No

促销代码，当isAfterPromotion=true时，它是必传字段

discount001

@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

餐食计划代码

RO

@paymentType

enum

No

预付（PayNow）、前台现付（PayLater）

枚举：[PayLater，PayNow]

PayNow

roomRates / guarantee

object

No

订单支付担任信息

 /

@guaranteeType

string

Yes

担保类型列表

CCG

roomRates / fees

array[object]

No

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

 /

fees / dateRange

object

Yes

日期范围

 /

@startDate

string

Yes

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

2024-01-01

@endDate

string

Yes

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

2024-01-04

fees / fee

 

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

@paymentType

enum

No

预付（PayNow）、前台现付（PayLater）

枚举：[PayLater，PayNow]

PayNow

@effectivePerson

number

No

从第几名成人开始收取额外费用，通常从第 3 名成人开始收取。值为 3 表示从第3名成年人起将收取额外费用 

 /

roomRates / cancelPolicy

object

No

取消政策定义了当客人在特定提前时间范围内取消预订时将收取的罚款

 /

@code

string

 Yes

最大长度：128

取消政策代码

AD100P_100P

@description

string

 No

最大长度：1024

取消政策的描述

Non Refundable

cancelPolicy / cancelPenalties

 

Yes

取消政策详情

 /

@noShow

boolean

Yes

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

 /

@cancellable

boolean

No

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

 /

cancelPenalties / cancelDeadline

 

 No

 /

 /

@offsetTimeDropType

enum

No

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

枚举：[BeforeArrival]

 /

@offsetTimeUnit

enum

No

枚举：[D，H]

 /

@offsetTimeValue

number

No

时间数

 /

@deadline

string

No

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

 /

cancelPenalties / penaltyCharge

 /

 /

 /

 /

@chargeBase

enum

No

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

枚举：[FullStay，NightBase]

 /

@nights

number

No 

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

 /

@amount

number

No 

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

 /

@percent

number

No 

15.5 为 15.5%

 /

extensions

object

No

可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft 将提供指定的格式)。请不要通过这个字段传送敏感信息。

 /



实时询价

此 API 用于实时获取某一酒店最新的 ARI 数据。将向酒店集团发送请求获取实时结果。

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


请求示例

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
},
"corpCode": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2024-01-01",
      "checkout": "2024-01-04"
    },
    "roomCriteria": {
      "roomCount": 2,
      "adultCount": 1,
      "childCount": 2,
      "childAges": [
        4,
        8
      ]
    },
    "productCandidate": {
      "roomId": "K1D",
      "rateId": "ODAD01"
    },
    "iata": "string",
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "isAfterPromotion": false,
    "promoteCode": "string",
    "bookingChannel": "string",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  }


请求规范

属性类型必要字段描述示例

header

object

Yes

 /

 /

@supplierId

string

Yes

最大长度：32

酒店集团 ID

HILTON

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API 版本

v4

@token

string

Yes

最大长度：64

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

18393849028490234

corpCode

String

No

渠道企业协议代码

IBM

hotelId

string

Yes

酒店 ID

GATHI

stayRange

object

Yes

 /

 /

@checkin

string

Yes

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

2024-01-01

@checkout

string

Yes

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

2024-01-04

roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

array

No

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

[ 4, 8 ]

productCandidate

object

No

 /

 /

@roomId

string

No

房型代码

K1D

@rateId

string

No

价格计划代码

ODAD01

iata

string

No

渠道 IATA

 /

loyaltyAccount

object

No

 /

 /

@programCode

string

Yes

会员体系代码

BW

@accountId

string

Yes

会员号

1234567890123457

corpAccount

object

No

供应商协议代码

 /

@corpProgramCode

string

Yes

公司代码

CR

@corpId

string

Yes

协议价代码

A-1232

isAfterPromotion

boolean

No

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

  • true : 表示根据供应商提供的促销规则检查可用性。
  • false : 表示您无需检查任何促销活动的可用性，只需进行基本的实时检查。

false

promoteCode

string

 No

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

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

 /

bookingChannel

string

No

渠道 ID/子渠道 ID

/

extensions

object

No

可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft 将提供指定的格式)。请不要通过这个字段传送敏感信息。 

 /


响应示例

  • 成功响应（HTTP 状态 200）
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2024-01-01",
    "checkout": "2024-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "rateId": "ODAD01",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "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
          }
        }
      ],
      "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
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}


  • 错误响应（HTTP 状态 403）
{
    "error": "Key not authorized"
}


  • 错误响应（HTTP 状态 500）
{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}


响应规范

属性

类型

必要字段

描述

示例

header

object

Yes

 /

 /

@supplierId

string

Yes

最大长度：32

酒店集团 ID

HILTON

@distributorId

string

Yes

最大长度：32

渠道 ID

GTA

@version

string

Yes

最大长度：20

API 版本

v4

@token

string

Yes

最大长度：64

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

18393849028490234

hotelId

string

Yes

酒店代码

GATHI

stayRange

object

Yes

 /

 /

@checkin

string

Yes

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

2024-01-01

@checkout

string

Yes

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

2024-01-04

roomCriteria

object

Yes

 /

 /

@roomCount

integer

Yes

每个请求的总房间数

2

@adultCount

integer

Yes

每个房间的成人人数

1

@childCount

integer

No

每个房间的儿童人数

2

@childAges

array

No

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

[ 4, 8 ]

productCandidate

object

No

 /

 /

@roomId

string

No

房型代码

K1D

@rateId

string

No

价格计划代码

ODAD01

iata

string

No

渠道 IATA

 /

roomRates

 

Yes

膳食计划、费用和取消政策是可选字段，因为一些分销商在 API 中不支持这些字段。

 /

@inventory

integer

Yes

房量/库存

1

@isAfterPromotion

boolean

No

该标志表示是否根据促销规则计算可用房价。如果为空，则默认值为 false

  • true: 表示检查渠道提供的促销规则是否可用。
  • false: 表示不检查促销规则是否可用，只做常规实时询价。

false

@promoteCode

string

No

促销代码，当 isAfterPromotion=true 时，它是必传字段

discount001

@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

餐食计划代码

RO

@paymentType

enum

No

预付（PayNow）、前台现付（PayLater）

枚举：[PayLater，PayNow]

PayNow

roomRates / guarantee

object

No

订单支付担任信息

 /

@guaranteeType

string

Yes

担保类型列表

CCG

roomRates / fees

array[object]

No

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

 /

fees / dateRange

object

Yes

日期范围

 /

@startDate

string

Yes

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

2024-01-01

@endDate

string

Yes

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

2024-01-04

fees / fee

 

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

@paymentType

enum

No

预付（PayNow）、前台现付（PayLater）

枚举：[PayLater，PayNow]

PayNow

@effectivePerson

number

No

从第几名成人开始收取额外费用，通常从第3名成人开始收取。值为 3 表示从第3名成年人起将收取额外费用

 /

roomRates / cancelPolicy

object

No

取消政策定义了当客人在特定提前时间范围内取消预订时将收取的罚款

 /

@code

string

 Yes

最大长度：128

取消政策代码

AD100P_100P

@description

string

 No

最大长度：1024

取消政策的描述

Non Refundable

cancelPolicy / cancelPenalties

 

Yes

取消政策详情

 /

@noShow

boolean

Yes

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

 /

@cancellable

boolean

No

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

 /

cancelPenalties / cancelDeadline

 

 No

 /

 /

@offsetTimeDropType

enum

No

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

枚举：[BeforeArrival]

 /

@offsetTimeUnit

enum

No

枚举：[D，H]

 /

@offsetTimeValue

number

No

时间数

 /

@deadline

string

No

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

 /

cancelPenalties / penaltyCharge

 /

 /

 /

 /

@chargeBase

enum

No

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

枚举：[FullStay，NightBase]

 /

@nights

number

No 

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

 /

@amount

number

No 

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

 /

@percent

number

No 

15.5 为 15.5%

 /

extensions

object

No

可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft 将提供指定的格式)。请不要通过这个字段传送敏感信息。

 /