分销商知识库

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

TABLE OF CONTENTS

介绍
实时询价
预订前验价
预订
修改订单
取消订单
查询订单列表
查询订单详情

介绍

BookingUSB 提供了订单流程相关接口，包括实时询价、预订前验价、预订、修改、取消，查询订单详情等接口。

实时询价（/availability）- 用于实时获取最新 ARI 数据。将向酒店集团发送请求以获取实时结果。
预订前验价（/reservation/prebook）- 用于在预订前进行最终验价。
预订（/reservation/book）- 用于实时预订，酒店集团实时返回预订结果。
修改订单（/reservation/modify）- 用于修改订单，如果酒店集团不支持修改订单，将采用“取消->重新预订”策略进行处理。
取消订单（/reservation/cancel）- 用于取消订单，酒店集团实时返回取消结果。
查询订单列表（/reservations）- 用于查询订单列表。
查询订单详情（/reservation/detail）- 用于查询订单详情，还可用于检查某些超时预订请求的预订状态。

实时询价

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

POST /availability HTTP/1.1
URL: {endpoint}/availability
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"
    },
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-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
hotelId	string	Yes	酒店ID	GATHI
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	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": "2018-01-01",
    "checkout": "2018-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": "2018-01-01",
            "endDate": "2018-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": 0,
              "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	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	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	meal plan code list	RO
@paymentType	enum	No	预付（PayNow）、前台现付（PayLater）枚举：[PayLater，PayNow]	PayNow
roomRates / guarantee	object	No	订单支付担任信息	/
@guaranteeType	string	Yes	guarantee type list.	CCG
roomRates / 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		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将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

预订前验价

预订前最后检查目标房间的可用性和价格

POST /reservation/prebook HTTP/1.1
URL: {endpoint}/reservation/prebook
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"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0"
    },
    "iata": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "contactPerson": {
      "firstName": "James",
      "lastName": "Bond",
      "email": "007@james.com",
      "phone": "string",
      "address": "string"
    },
    "roomCriteria": {
      "roomCount": 2,
      "adultCount": 1,
      "childCount": 2,
      "childAges": [
        4,
        8
      ]
    },
    "total": {
      "amountBeforeTax": 640,
      "amountAfterTax": 700
    },
    "payment": {
      "cardCode": "VI",
      "cardNumber": "4111111111111111",
      "cardHolderName": "Sherlock Holmes",
      "expireDate": "0119",
      "securityCode": "123"
    },
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "promoteCode": "string",
    "guests": [
      {
        "firstName": "James",
        "lastName": "Bond",
        "email": "007@james.com",
        "phone": "string",
        "address": "string",
        "age": 32,
        "gender": "Male",
        "birthday": "1990-01-01",
        "type": "Adult",
        "index": 1,
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      }
    ],
    "comments": [
      "no smoking",
      "high floor"
    ],
    "roomRates": [
      {
        "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",
              "paymentType": "PayNow",
              "effectivePerson": 0
            }
          }
        ],
        "cancelPolicy": {
          "code": "AD100P_100P",
          "description": "Non Refundable",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        }
      }
    ],
    "bookingChannel": "string",
    "productAddons": [
      {
        "type": "DisneyTicket",
        "code": "code",
        "date": "2018-01-01",
        "quantity": 1,
        "officeId": "string",
        "rate": {
          "ageQualifyingType": {
            "type": "Adult",
            "minAge": 18,
            "maxAge": 99
          },
          "currency": "USD",
          "amountBeforeTax": 123.23,
          "amountAfterTax": 134.34
        }
      }
    ],
    "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
reservationIds	/	Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
iata	string	No	IATA	/
hotelId	string	Yes	酒店代码	100001
stayRange	object	Yes	/	/
@checkin	string	Yes	入住日期，格式为yyyy-MM-dd	2018-01-01
@checkout	string	Yes	离店日期，格式为yyyy-MM-dd	2018-01-04
contactPerson	object	Yes	/	/
@firstName	string	Yes	联系人名字	James
@lastName	string	Yes	联系人姓氏	Bond
@email	string	No	Email	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	每个请求的总房间数	/
@adultCount	integer	Yes	每个房间的成人人数	/
@childCount	integer	No	每个房间的儿童人数	/
@childAges	array	No	与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄。	/
total	object	Yes	/	/
@amountBeforeTax	number	No	税前价，简称ABT 税前价与税后价不能同时为空	640
@amountAfterTax	number	No	税后价，简称AAT 税前价与税后价不能同时为空	700
payment		No	/	/
@cardCode	string	Yes	VI、 MC、AX等。信用卡片代码	VI
@cardNumber	string	Yes	信用卡卡号	4111111111111111
@cardHolderName	string	Yes	持卡人姓名	Sherlock Holmes
@expireDate	string	Yes	格式为“MMYY” 如 0119 代表2019年1月	0119
@securityCode	string	No	安全码	123
loyaltyAccount	object	No	/	/
@programCode	string	Yes	会员体系代码	BW
@accountId	string	Yes	会员号	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	公司代码	CR
@corpId	string	Yes	协议价代码	A-1232
promoteCode	string	No	促销规则代码	/
guests	/	/	/	/
@firstName	string	Yes	客人名字	James
@lastName	string	Yes	客人姓氏	Bond
@email	string	No	邮箱	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
@age	integer	No	客人年龄	/
@gender	enum	No	客人性别枚举：[Male, Female]	Male
@birthday	string	No	客人生日格式为yyyy-MM-dd	1970-12-20
@type	string	No	客人类型枚举：[Adult, Child, Infant]	/
@index	integer	No	客人入住第几间房	1
@extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。	/
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	/	/
@roomId	string	Yes	房型代码	10000101
@rateId	string	Yes	价格计划代码	123456
@currency	string	Yes	币种代码 [ISO-4217]	USD
@amountBeforeTax	array[number]	No	税前价，简称ABT 税前价与税后价不能同时为空	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	税后价，简称AAT 税前价与税后价不能同时为空	[ 110, 110, 130 ]
@mealPlan	string	No	meal plan code list	RO
@paymentType	enum	No	预付（PayNow）、前台现付（PayLater）枚举：[PayLater，PayNow]	PayNow
roomRates/guarantee	object	No	订单支付担任信息	/
@guaranteeType	string	Yes	guarantee type list.	CCG
roomRates/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		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	/	/	/	/
@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%	/
bookingChannel	string	No	渠道账号/子账号	/
productAddons	array[object]	No	/	/
@type	string	Yes	产品 Addon 类型	/
@code	string	Yes	产品 Addon 代码	/
@date	string	Yes	格式：yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	/	/
productAddons/rate	object	No	/	/
rate/ageQualifyingType	object	No	/	/
@type	enum	Yes	枚举：[Adult，Child]	Adult
@minAge	integer	Yes	/	18
@maxAge	integer	Yes	/	18
rate/currency	string	Yes	/	USD
rate/amountBeforeTax	number	No	/	123.23
rate/amountAfterTax	number	No	/	134.34
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

响应示例

成功响应（HTTP状态200）

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  }

Error Response (HTTP Status 403)

{
    "error": "Key not authorised"
}

Error Response (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
bookingToken	string	Yes	用于下单的预订令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey JzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwi aWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJ f36POk6yJV_adQssw5c
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

预订

渠道使用此API预订房间，将向酒店集团实时发送预订请求并实时获取订单确认号。

POST /reservation/book HTTP/1.1
URL: {{endpoint}}/reservation/book
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"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0"
    },
    "iata": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "contactPerson": {
      "firstName": "Thomas",
      "lastName": "Hintz",
      "email": "Thomas.Hintz@yahoo.com",
      "phone": "260-975-4091",
      "address": "3946 Freddy Locks"
    },
    "roomCriteria": {
      "roomCount": 1,
      "adultCount": 2,
      "childCount": 1,
      "childAges": [
        5
      ]
    },
    "total": {
      "amountBeforeTax": 640,
      "amountAfterTax": 700
    },
    "payment": {
      "cardCode": "VI",
      "cardNumber": "4111111111111111",
      "cardHolderName": "Sherlock Holmes",
      "expireDate": "0119",
      "securityCode": "123"
    },
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "promoteCode": "string",
    "guests": [
      {
        "firstName": "Thomas",
        "lastName": "Hintz",
        "email": "Thomas.Hintz@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 32,
        "gender": "Male",
        "birthday": "1990-01-01",
        "type": "Adult",
        "index": 1,
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "firstName": "Hillary",
        "lastName": "Ullrich",
        "email": "Xavier.Lind49@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 28,
        "gender": "Female",
        "birthday": "1994-01-01",
        "type": "Adult",
        "index": 1
      },
      {
        "firstName": "Alex",
        "lastName": "Hintz",
        "age": 5,
        "type": "Child",
        "index": 1
      }
    ],
    "comments": [
      "no smoking",
      "high floor"
    ],
    "roomRates": [
      {
        "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",
              "paymentType": "PayNow",
              "effectivePerson": 0
            }
          }
        ],
        "cancelPolicy": {
          "code": "AD100P_100P",
          "description": "Non Refundable",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        }
      }
    ],
    "bookingChannel": "string",
    "productAddons": [
      {
        "type": "DisneyTicket",
        "code": "code",
        "date": "2018-01-01",
        "quantity": 1,
        "officeId": "string",
        "rate": {
          "ageQualifyingType": {
            "type": "Adult",
            "minAge": 18,
            "maxAge": 99
          },
          "currency": "USD",
          "amountBeforeTax": 123.23,
          "amountAfterTax": 134.34
        }
      }
    ],
    "threeDomainSecurity": {
      "cavv": "string",
      "eci": "string",
      "xid": "string",
      "threeDomainSecurityVersion": "string",
      "transactionId": "string",
      "merchantName": "string",
      "channelCode": "EC",
      "exemptionType": "SC",
      "extensions": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "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
reservationIds	/	Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
iata	string	No	渠道 IATA	/
hotelId	string	Yes	酒店代码	100001
stayRange	object	Yes	/	/
@checkin	string	Yes	入住日期，格式为yyyy-MM-dd	2018-01-01
@checkout	string	Yes	离店日期，格式为yyyy-MM-dd	2018-01-04
contactPerson	object	Yes	/	/
@firstName	string	Yes	联系人名字	James
@lastName	string	Yes	联系人姓氏	Bond
@email	string	No	Email	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	每个请求的总房间数	/
@adultCount	integer	Yes	每个房间的成人人数	/
@childCount	integer	No	每个房间的儿童人数	/
@childAges	array	No	与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄	/
total	object	Yes	/	/
@amountBeforeTax	number	No	税前价，简称ABT 税前价与税后价不能同时为空	640
@amountAfterTax	number	No	税后价，简称AAT 税前价与税后价不能同时为空	700
payment		No	/	/
@cardCode	string	Yes	VI、 MC、AX等。信用卡代码	VI
@cardNumber	string	Yes	信用卡卡号	4111111111111111
@cardHolderName	string	Yes	持卡人姓名	Sherlock Holmes
@expireDate	string	Yes	格式为“MMYY” 如 0119 代表 2019年1月	0119
@securityCode	string	No	安全码	123
loyaltyAccount	object	No	/	/
@programCode	string	Yes	会员体系代码	BW
@accountId	string	Yes	会员号	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	公司代码	CR
@corpId	string	Yes	协议价代码	A-1232
promoteCode	string	No	由酒店定义的促销代码是您想要请求促销价时的可选字段（isAfterPromotion=true）。如果促销代码为空，并且一个产品同时有多个促销，则将根据多促销策略选择促销规则。	/
guests	/	/	/
@firstName	string	Yes	客人名字	James
@lastName	string	Yes	客人姓氏	Bond
@email	string	No	邮箱	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
@age	integer	No	客人年龄	/
@gender	enum	No	客人性别枚举：[Male，Female]	Male
@birthday	string	No	客人生日格式：yyyy-MM-dd	1970-12-20
@type	string	No	客人类型枚举：[Adult, Child, Infant]	/
@index	integer	No	客人入住第几间房	1
@extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。	/
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	/	/
@roomId	string	Yes	房型代码	10000101
@rateId	string	Yes	价格计划代码	123456
@currency	string	Yes	币种代码 [ISO-4217]	USD
@amountBeforeTax	array[number]	No	税前价，简称ABT 税前价与税后价不能同时为空	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	税后价，简称AAT 税前价与税后价不能同时为空	[ 110, 110, 130 ]
@mealPlan	string	No	餐食计划代码	RO
@paymentType	enum	No	预付（PayNow）、前台现付（PayLater）枚举：[PayLater，PayNow]	PayNow
roomRates/guarantee	object	No	订单支付担任信息	/
@guaranteeType	string	Yes	guarantee type list	CCG
roomRates/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		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	/	/	/	/
@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%	/
bookingChannel	string	No	渠道账号/子账号	/
productAddons	array[object]	No	/	/
@type	string	Yes	产品 Addon 类型	/
@code	string	Yes		/
@date	string	Yes	格式：yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	/	/
productAddons/rate	object	No	/	/
rate/ageQualifyingType	object	No	/	/
@type	enum	Yes	枚举：[Adult，Child]	Adult
@minAge	integer	Yes	/	18
@maxAge	integer	Yes	/	18
rate/currency	string	Yes	/	USD
rate/amountBeforeTax	number	No	/	123.23
rate/amountAfterTax	number	No	/	134.34
threeDomainSecurity	object	No	/	/
@cavv	string	No	认证成功后，从3DS提供商检索持卡人信息	/
@eci	string	No	电子商务标识	/
@xid	string	No	3DS版本1提供程序的事务标识符，由Directory Server分配以标识单个事务	/
@threeDomainSecurityVersion	string	No	仅适用于3D Secure 2	/
@transactionId	string	No	3DS版本2提供程序的事务标识符，由Directory Server分配以标识单个事务	/
@merchantName	string	No	完成3DS交易的商家的标识符	/
@channelCode	enum	No	指定支付卡的收款渠道 Enum: [TO, EC, MO, FA]	EC
@exemptionType	enum	No	确定支付服务提供商(PSP)使用了哪项豁免 Enum: [SC, DA, TA, TB, LV]	SC
bookingToken	string	Yes	用于下单的预订令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6Ik pXVCJ9.eyJzdWIiOiIxMjM0NTY3 ODkwIiwibmFtZSI6IkpvaG4gRG9lIi wiaWF0IjoxNTE2MjM5MDIyfQ .SflKxwRJSMeKKF2QT4fwpMeJf36PO k6yJV_adQssw5c
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。

响应示例

成功响应（HTTP状态200）

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    },
    "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
reservationIds		Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	No	德比订单号	D15F893D34DF
@supplierResId	string	No	酒店订单号	89389494
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

修改订单

渠道使用此API修改现有预订。将向酒店集团发送请求获得实时确认。对于没有修改接口的酒店集团，将采用“取消->重新预订”策略。

POST /reservation/modify HTTP/1.1
URL: {endpoint}/reservation/modify
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"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    },
    "iata": "string",
    "hotelId": "GATHI",
    "stayRange": {
      "checkin": "2018-01-01",
      "checkout": "2018-01-04"
    },
    "contactPerson": {
      "firstName": "Thomas",
      "lastName": "Hintz",
      "email": "Thomas.Hintz@yahoo.com",
      "phone": "260-975-4091",
      "address": "3946 Freddy Locks"
    },
    "roomCriteria": {
      "roomCount": 1,
      "adultCount": 2,
      "childCount": 1,
      "childAges": [
        5
      ]
    },
    "total": {
      "amountBeforeTax": 640,
      "amountAfterTax": 700
    },
    "payment": {
      "cardCode": "VI",
      "cardNumber": "4111111111111111",
      "cardHolderName": "Sherlock Holmes",
      "expireDate": "0119",
      "securityCode": "123"
    },
    "loyaltyAccount": {
      "programCode": "BW",
      "accountId": "1234567890123457"
    },
    "corpAccount": {
      "corpProgramCode": "CR",
      "corpId": "A-1232"
    },
    "promoteCode": "string",
    "guests": [
      {
        "firstName": "Thomas",
        "lastName": "Hintz",
        "email": "Thomas.Hintz@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 32,
        "gender": "Male",
        "birthday": "1990-01-01",
        "type": "Adult",
        "index": 1
      },
      {
        "firstName": "Hillary",
        "lastName": "Ullrich",
        "email": "Xavier.Lind49@yahoo.com",
        "phone": "260-975-4091",
        "address": "3946 Freddy Locks",
        "age": 28,
        "gender": "Female",
        "birthday": "1994-01-01",
        "type": "Adult",
        "index": 1,
        "extensions": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      {
        "firstName": "Alex",
        "lastName": "Hintz",
        "age": 5,
        "type": "Child",
        "index": 1
      }
    ],
    "comments": [
      "no smoking",
      "high floor"
    ],
    "roomRates": [
      {
        "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",
              "paymentType": "PayNow",
              "effectivePerson": 0
            }
          }
        ],
        "cancelPolicy": {
          "code": "AD100P_100P",
          "description": "Non Refundable",
          "cancelPenalties": [
            {
              "noShow": true,
              "cancellable": true,
              "cancelDeadline": {
                "offsetTimeDropType": "BeforeArrival",
                "offsetTimeUnit": "D",
                "offsetTimeValue": 0,
                "deadline": "string"
              },
              "penaltyCharge": {
                "chargeBase": "FullStay",
                "nights": 0,
                "amount": 0,
                "percent": 0
              }
            }
          ]
        }
      }
    ],
    "bookingChannel": "string",
    "productAddons": [
      {
        "type": "DisneyTicket",
        "code": "code",
        "date": "2018-01-01",
        "quantity": 1,
        "officeId": "string",
        "rate": {
          "ageQualifyingType": {
            "type": "Adult",
            "minAge": 18,
            "maxAge": 99
          },
          "currency": "USD",
          "amountBeforeTax": 123.23,
          "amountAfterTax": 134.34
        }
      }
    ],
    "threeDomainSecurity": {
      "cavv": "string",
      "eci": "string",
      "xid": "string",
      "threeDomainSecurityVersion": "string",
      "transactionId": "string",
      "merchantName": "string",
      "channelCode": "EC",
      "exemptionType": "SC",
      "extensions": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "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
reservationIds	/	Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
iata	string	No	IATA	/
hotelId	string	Yes	酒店代码	100001
stayRange	object	Yes	/	/
@checkin	string	Yes	入住日期，格式为yyyy-MM-dd	2018-01-01
@checkout	string	Yes	离店日期，格式为yyyy-MM-dd	2018-01-04
contactPerson	object	Yes	/	/
@firstName	string	Yes	联系人名字	James
@lastName	string	Yes	联系人姓氏	Bond
@email	string	No	Email	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	每个请求的总房间数	/
@adultCount	integer	Yes	每个房间的成人人数	/
@childCount	integer	No	每个房间的儿童人数	/
@childAges	array	No	与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄	/
total	object	Yes	/	/
@amountBeforeTax	number	No	税前价，简称ABT 税前价与税后价不能同时为空	640
@amountAfterTax	number	No	税后价，简称AAT 税前价与税后价不能同时为空	700
payment		No	/	/
@cardCode	string	Yes	VI、 MC、AX等。信用卡代码	VI
@cardNumber	string	Yes	信用卡卡号	4111111111111111
@cardHolderName	string	Yes	持卡人姓名	Sherlock Holmes
@expireDate	string	Yes	格式为“MMYY” 如 0119 代表2019年1月	0119
@securityCode	string	No	安全码	123
loyaltyAccount	object	No	/	/
@programCode	string	Yes	会员体系代码	BW
@accountId	string	Yes	会员号	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	公司代码	CR
@corpId	string	Yes	协议价代码	A-1232
promoteCode	string	No	促销规则代码	/
guests	/	/	/
@firstName	string	Yes	客人名字	James
@lastName	string	Yes	客人姓氏	Bond
@email	string	No	邮箱	007@james.com
@phone	string	No	/	/
@address	string	No	/	/
@age	integer	No	客人年龄	/
@gender	enum	No	客人性别枚举：[Male, Female]	Male
@birthday	string	No	客人生日格式为yyyy-MM-dd	1970-12-20
@type	string	No	客人类型枚举：[Adult, Child, Infant]	/
@index	integer	No	客人入住第几间房	1
@extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。	/
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	/	/
@roomId	string	Yes	房型代码	10000101
@rateId	string	Yes	价格计划代码	123456
@currency	string	Yes	币种代码[ISO-4217]	USD
@amountBeforeTax	array[number]	No	税前价，简称ABT 税前价与税后价不能同时为空	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	税后价，简称AAT 税前价与税后价不能同时为空	[ 110, 110, 130 ]
@mealPlan	string	No	meal plan code list.	RO
@paymentType	enum	No	预付（PayNow）、前台现付（PayLater）枚举：[PayLater，PayNow]	PayNow
roomRates/guarantee	object	No	订单支付担任信息	/
@guaranteeType	string	Yes	guarantee type list.	CCG
roomRates/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		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	/	/	/	/
@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%.	/
bookingChannel	string	No	渠道账号/子账号	/
productAddons	array[object]	No	/	/
@type	string	Yes	产品 Addon 类型	/
@code	string	Yes	产品 Addon 代码	/
@date	string	Yes	格式： yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	/	/
productAddons/rate	object	No	/	/
rate/ageQualifyingType	object	No	/	/
@type	enum	Yes	枚举：[Adult，Child]	Adult
@minAge	integer	Yes	/	18
@maxAge	integer	Yes	/	18
rate/currency	string	Yes	/	USD
rate/amountBeforeTax	number	No	/	123.23
rate/amountAfterTax	number	No	/	134.34
threeDomainSecurity	object	No	/	/
@cavv	string	No	认证成功后，从3DS提供商检索持卡人认证验证值信息。	/
@eci	string	No	电子商务标识	/
@xid	string	No	3DS v1提供程序的事务标识符，由Directory Server分配以标识单个事务。	/
@threeDomainSecurityVersion	string	No	仅适用于3D Secure 2。	/
@transactionId	string	No	3DS v2提供程序的事务标识符，由Directory Server分配以标识单个事务。	/
@merchantName	string	No	完成3DS交易的商家的标识符	/
@channelCode	enum	No	指定支付卡的收款渠道 Enum: [TO, EC, MO, FA]	EC
@exemptionType	enum	No	确定支付服务提供商(PSP)使用了哪项豁免 Enum: [SC, DA, TA, TB, LV]	SC
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。

响应示例

成功响应（HTTP状态200）

{
    "header": {
      "supplierId": "HHBIJSOPLS",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    },
    "extensions": {
      "key": "value"
    }
  }

错误响应（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
reservationIds	object	Yes	/	100001
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	Yes	德比订单号	D15F893D34DF
@supplierResId	string	Yes	酒店订单号	89389494
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

取消订单

调用酒店集团订单取消接口，实时取消订单。对于拆分订单，建议渠道通过德比订单号或者酒店订单号取消订单。

POST /reservation/cancel HTTP/1.1
URL: {endpoint}/reservation/cancel
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"
    },
    "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
    },
    "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
reservationIds		Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	No	德比订单号	D15F893D34DF
@supplierResId	string	No	酒店订单号	89389494
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	{"key": "value"}

响应示例

成功响应（HTTP状态200）

{
    "header": {
        "supplierId": "HILTON",
        "distributorId": "GTA",
        "version": "v4",
        "token": "18393849028490234"
    },
    "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
    },
    "cancellationId": "C89389494",
    "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
reservationIds	object	Yes	/	100001
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	Yes	德比订单号	D15F893D34DF
@supplierResId	string	Yes	酒店订单号	89389494
cancellationId	string	Yes	酒店取消确认号	C89389494
extensions	object	No	可选字段:酒店集团和渠道之间商定的附加属性(DerbySoft将提供指定的格式)。请不要通过这个字段传送敏感信息。	/

查询订单列表接口

根据订单最后修改日期范围查询订单列表

POST /reservations HTTP/1.1
URL: {endpoint}/reservations
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"
    },
    "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-01-04"
    },
    "hotelId": "GATHI"
}

请求规范

属性	类型	必传字段？	描述	示例
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
dateRange	/	/	订单最后更新日期的日期范围	/
@startDate	string	Yes	开始日期格式：yyyy-MM-dd	2018-01-01
@endDate	string	Yes	订结束日期格式：yyyy-MM-dd	2018-01-04
hotelId	string	No	酒店代码	GATHI

响应示例

成功响应（HTTP状态200）

{
    "header": {
        "supplierId": "HILTON",
        "distributorId": "GTA",
        "version": "v4",
        "token": "18393849028490234"
    },
    "reservations": [
        {
            "reservationIds": {
                "distributorResId": "C2084DFL0",
                "derbyResId": "D15F893D34DF",
                "supplierResId": "89389494"
            },
            "iata": "string",
            "hotelId": "GATHI",
            "stayRange": {
                "checkin": "2018-01-01",
                "checkout": "2018-01-04"
            },
            "roomCriteria": {
                "roomCount": 2,
                "adultCount": 1,
                "childCount": 2,
                "childAges": [
                    4,
                    8
                ]
            },
            "total": {
                "amountBeforeTax": 640,
                "amountAfterTax": 700
            },
            "status": "Confirmed",
            "cancellationId": "C89389494",
            "result": "Successful",
            "failCause": {
                "errorCode": "string",
                "supplierErrorCode": "string",
                "errorMessage": "string"
            }
        }
    ]
}

错误响应（HTTP状态403）

{
    "error": "Key not authorized"
}

错误响应（HTTP状态500）

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

响应规范

属性	类型	必传字段？	描述	示例
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
reservations	/	/	/	/
reservations/reservationIds	/	/	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	Yes	德比订单号	D15F893D34DF
@supplierResId	string	Yes	酒店订单号	89389494
@iata	string	No	/	/
@hotelId	string	Yes	酒店代码	100001
reservations/stayRange	object	Yes	/	/
@checkin	string	Yes	入住日期，格式为yyyy-MM-dd	2018-01-01
@checkout	string	Yes	离店日期，格式为yyyy-MM-dd	2018-01-04
reservations/roomCriteria	object	Yes	/
@roomCount	integer	Yes	每个请求的总房间数
@adultCount	integer	Yes	每个房间的成人人数
@childCount	integer	No	每个房间的儿童人数
@childAges	array	No	与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄。	[ 4, 8 ]
reservations/total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
@status	enum	Yes	枚举：[Confirmed, Modified, Cancelled] 预订状态	/
cancellationId	string	No	酒店取消订单确认号	C89389494
@result	enum	Yes	枚举：[Successful, Failed, Processing] 订单预订状态	/
reservations / failCause		No	/	/
@errorCode	string	Yes	参阅 Error Code 附录	/
@supplierErrorCode	string	No	酒店集团返回的错误代码	/
@errorMessage	string	Yes	错误信息	/

查询订单详情

渠道使用此API查询订单详情。还可用于检查某些超时预订请求的预订状态

POST /reservation/detail HTTP/1.1
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"
    },
    "reservationIds": {
      "distributorResId": "C2084DFL0",
      "derbyResId": "D15F893D34DF",
      "supplierResId": "89389494"
    }
  }

请求规范

属性	类型	必传字段？	描述	示例
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
reservationIds		Yes	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	No	德比订单号	D15F893D34DF
@supplierResId	string	No	酒店订单号	89389494

响应示例

成功响应（HTTP状态200）

{
    "header": {
      "supplierId": "HILTON",
      "distributorId": "GTA",
      "version": "v4",
      "token": "18393849028490234"
    },
    "reservations": [
      {
        "reservationIds": {
          "distributorResId": "C2084DFL0",
          "derbyResId": "D15F893D34DF",
          "supplierResId": "89389494"
        },
        "iata": "string",
        "hotelId": "GATHI",
        "stayRange": {
          "checkin": "2018-01-01",
          "checkout": "2018-01-04"
        },
        "roomCriteria": {
          "roomCount": 2,
          "adultCount": 1,
          "childCount": 2,
          "childAges": [
            4,
            8
          ]
        },
        "total": {
          "amountBeforeTax": 640,
          "amountAfterTax": 700
        },
        "loyaltyAccount": {
          "programCode": "BW",
          "accountId": "1234567890123457"
        },
        "corpAccount": {
          "corpProgramCode": "CR",
          "corpId": "A-1232"
        },
        "promoteCode": "string",
        "comments": [
          "no smoking",
          "high floor"
        ],
        "roomRates": [
          {
            "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",
                  "paymentType": "PayNow",
                  "effectivePerson": 0
                }
              }
            ],
            "cancelPolicy": {
              "code": "AD100P_100P",
              "description": "Non Refundable",
              "cancelPenalties": [
                {
                  "noShow": true,
                  "cancellable": true,
                  "cancelDeadline": {
                    "offsetTimeDropType": "BeforeArrival",
                    "offsetTimeUnit": "D",
                    "offsetTimeValue": 0,
                    "deadline": "string"
                  },
                  "penaltyCharge": {
                    "chargeBase": "FullStay",
                    "nights": 0,
                    "amount": 0,
                    "percent": 0
                  }
                }
              ]
            }
          }
        ],
        "bookingChannel": "string",
        "productAddons": [
          {
            "type": "DisneyTicket",
            "code": "code",
            "date": "2018-01-01",
            "quantity": 1,
            "officeId": "string",
            "rate": {
              "ageQualifyingType": {
                "type": "Adult",
                "minAge": 18,
                "maxAge": 99
              },
              "currency": "USD",
              "amountBeforeTax": 123.23,
              "amountAfterTax": 134.34
            }
          }
        ],
        "status": "Confirmed",
        "cancellationId": "C89389494",
        "result": "Successful",
        "failCause": {
          "errorCode": "string",
          "supplierErrorCode": "string",
          "errorMessage": "string"
        }
      }
    ]
  }

错误响应（HTTP状态403）

{
    "error": "Key not authorized"
}

错误响应（HTTP状态500）

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

响应规范

属性	类型	必传字段？	描述	示例
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
reservations	/	No	/	/
/reservationIds	/	/	/	/
@distributorResId	string	Yes	渠道订单号	C2084DFL0
@derbyResId	string	Yes	德比订单号	D15F893D34DF
@supplierResId	string	Yes	酒店订单号	89389494
iata	string	No	/	/
hotelId	string	Yes	酒店代码	100001
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	每个请求的总房间数	/
@adultCount	integer	Yes	每个房间的成人人数	/
@childCount	integer	No	每个房间的儿童人数
@childAges	array	No	与儿童人数相同，比如两位儿童入住，则需要提供两位儿童的年龄	/
total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
loyaltyAccount	object	No	/	/
@programCode	string	Yes	会员体系代码	BW
@accountId	string	Yes	会员号	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	公司代码	CR
@corpId	string	Yes	协议价代码	A-1232
promoteCode	string	No	促销规则代码	/
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	/	/
@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	guarantee type list.	CCG
roomRates/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	/	Yes	/	/
@name	string	Yes	/	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		从第几名成人开始收取额外费用，通常从第3名成人开始收取。值为 3 表示从第3名成年人起将收取额外费用	/
roomRates/cancelPolicy	object	No	取消政策定义了当客人在特定提前时间范围内取消预订时将收取的罚款	/
@code	string		最大长度：128 取消政策代码	AD100P_100P
@description	string		最大长度：1024 取消政策描述	Non Refundable
cancelPolicy/cancelPenalties		Yes	取消政策详细信息	/
@noShow	boolean	Yes	如果为true，则意味着本条取消规则适用于“未入住”，cancellable 和 cancelDeadline 两个节点将不会出现	/
@cancellable	boolean	No	标示是否允许取消。如果为false，则不可取消。如果为true，cancelDeadline 节点将出现	/
cancelPenalties/cancelDeadline	/	/	/	/
@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%	/
bookingChannel	string	No	渠道账号/子账号	/
productAddons	array[object]	No	/	/
@type	string	Yes	/	DisneyTicket
@code	string	Yes	/	/
@date	string	Yes	格式为 yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	specific distributor office	/
productAddons/rate	object	No	/	/
rate/ageQualifyingType	object	No	/	/
@type	enum	Yes	枚举: [Adult, Child]	Adult
@minAge	integer	Yes	/	18
@maxAge	integer	Yes	/	18
rate/currency	string	Yes	/	USD
rate/amountBeforeTax	number	No	/	123.23
rate/amountAfterTax	number	No	/	134.34
status	enum	Yes	枚举：[Confirmed, Modified, Cancelled] 订单最新状态： Confirmed - 预订单 Modified - 修改单 Cancelled - 取消单请使用 status + result 字段组合来判断订单是否成功。例如： Confirmed + Successful 表示预订成功 Confirmed + Failed 表示预订失败 Modified + Successful 表示修改成功 Modified + Failed 表示修改失败 Cancelled + Successful 表示取消成功 Cancelled + Failed 表示取消失败	Confirmed
cancellationId	string	No	酒店取消订单确认号	C89389494
result	enum	Yes	枚举：[Successful, Failed, Processing] 订单请求结果： Successful - 成功 Failed - 失败 Processing - 处理中	Successful
reservations/failCause	/	No	/	/
@errorCode	string	Yes	Error Code Appendix	/
@supplierErrorCode	string	No	酒店集团返回的错误代码	/
@errorMessage	string	Yes	错误信息	/

Chinese

BookingUSB-订单接口

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

介绍

实时询价

请求示例

请求规范

响应示例

响应规范

预订前验价

请求示例

请求规范

响应示例

响应规范

预订

请求示例

请求规范

响应示例

响应规范

修改订单

请求示例

请求规范

响应示例

响应规范

取消订单

请求示例

请求规范

响应示例

响应规范

查询订单列表接口

请求示例

请求规范

响应示例

响应规范

查询订单详情

请求示例

请求规范

响应示例

响应规范