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

TABLE OF CONTENTS


介绍

DerbySoft使用促销API定期向渠道推送酒店集团的促销活动。

促销推送（/production/Push）：向渠道推送酒店集团提供的促销详情。



促销

向渠道推送酒店集团提供的促销详情

POST /promotion/push HTTP/1.1
URL: {{endpoint}}/promotion/push
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"
  },
  "hotelPromotion": {
    "hotelId": "100001",
    "supplierId": "Hilton",
    "multiPromotionsStrategy": "Sequence",
    "promotions": [
      {
        "promoteCode": "XXXX",
        "promoteName": "Mid-Annual Promotion",
        "description": "Stay 4 nights and get 1 night for free",
        "status": "Actived",
        "isCoupon": false,
        "sequence": 1,
        "productCandidates": [
          {
            "roomId": "K1D",
            "rateId": "ODAD01"
          }
        ],
        "bookWindow": {
          "startDate": "2018-01-01",
          "endDate": "2018-01-04",
          "eachDayStartTime": "00:00:00",
          "eachDayEndTime": "12:00:00",
          "excludedDate": [
            "2018-01-02",
            "2018-01-02"
          ]
        },
        "stayWindow": {
          "startDate": "2018-01-01",
          "endDate": "2018-01-04",
          "weekdays": "1111111",
          "excludedDate": [
            "2018-01-02",
            "2018-01-03"
          ]
        },
        "promoteType": "FreeNight",
        "basicDiscount": {
          "discountType": "Percent",
          "discountValue": 10,
          "rateApplied": false,
          "rateApplyOn": "AmountAfterTax",
          "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
          "restriction": {
            "minStayThrough": 1,
            "maxStayThrough": 4,
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 0
          }
        },
        "freeNight": {
          "stayNight": 4,
          "freeNight": 1,
          "recurring": true,
          "freeNightType": "LastNight",
          "rateApplied": false,
          "rateApplyOn": "AmountAfterTax",
          "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
          "restriction": {
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 0
          }
        },
        "lastMinute": {
          "discount": {
            "discountType": "Percent",
            "discountValue": 10
          },
          "rateApplied": false,
          "rateApplyOn": "AmountAfterTax",
          "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
          "restriction": {
            "minStayThrough": 1,
            "maxStayThrough": 4,
            "minAdvanceHour": 0,
            "maxAdvanceHour": 0,
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 0
          }
        },
        "earlyBooker": {
          "discount": {
            "discountType": "Percent",
            "discountValue": 10
          },
          "rateApplied": false,
          "rateApplyOn": "AmountAfterTax",
          "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
          "restriction": {
            "minStayThrough": 1,
            "maxStayThrough": 4,
            "minAdvanceDay": 0,
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 0
          }
        },
        "fixedPrice": {
          "type": "OccupancyRate",
          "occupancyRate": {
            "rate": [
              {
                "adultCount": 1,
                "childCount": 2,
                "amountBeforeTax": 502.19,
                "amountAfterTax": 623.23
              }
            ]
          },
          "commonRate": {
            "amountBeforeTax": 502.19,
            "amountAfterTax": 623.23
          },
          "rateApplied": false,
          "addOnDescription": "a welcome drink, hot spring, shuttle bus are included in this promotion, please ask to hotel reception while checking-in",
          "restriction": {
            "minStayThrough": 1,
            "maxStayThrough": 4,
            "minAdvanceDay": 0,
            "maxAdvanceDay": 0,
            "minAdvanceHour": 0,
            "maxAdvanceHour": 0,
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 0
          }
        },
        "giftPackage": {
          "description": "an extra dinner as gift is including in the price, please ask to hotel reception while checking-in",
          "restriction": {
            "minStayThrough": 1,
            "maxStayThrough": 4,
            "minRoomPerOrder": 0,
            "maxRoomPerOrder": 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
              }
            }
          ]
        },
        "mealPlan": "RO",
        "extensions": {
          "userName": "username",
          "password": "password"
        }
      }
    ]
  },
  "extension": {
    "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

hotelPromotion

 /

Yes

 /

 /

@hotelId

string

Yes

酒店代码

100001

@supplierId

string

Yes

酒店集团 ID

HILTON

multiPromotionsStrategy

enum

Yes

枚举：[Sequence，LowestPrice]

指示当有多个促销可用时用于选择促销的策略。如果是序列，则将在促销详细信息中为每个促销提供序列值。

Sequence

hotelPromotion/promotions

 /

Yes

 /

 /

@promoteCode

string

Yes

促销代码，可用于预订和实时检查中请求的@promoteCode。

 /

@promoteName

string

No

促销名称

Mid-Annual Promotion

@description

string

No

促销说明

Stay 4 nights and get 1 night for free

@status

enum

Yes

枚举：[Actived，Deactived]

促销状态

Actived

@isCoupon

boolean

Yes

  • true：只有当@promoteCode在预订和实时检查请求中有效时，才能提供此促销。
  • false：表示即使在预订和实时检查请求中@promoteCode为空，也可以提供此促销。

该标志指示是否是需要@promoteCode的优惠券促销。

对于拉模式的渠道，当从 GO 拉取 ARI 时，GO 将应用这些促销规则并计算到房价中。只有“isCoupon”=false的促销才会被视为进行多可用性检查时要应用的候选项。

false

@sequence

integer

No

从0开始。当@multiplePromotionsStrategy为Sequence时，它是必需的。如果有多个促销活动，则会选择序列号最大的促销活动。如果为空，则默认值为0。

1

promotions/productCandidates

 /

Yes

要应用于当前促销的产品列表。

 /

@roomId

string

Yes

房型代码

K1D

@rateId

string

Yes

价格计划代码

ODAD01

promotions/bookWindow

object

No

此促销可预订日期的日期范围。如果预订窗口没有限制，请将其留空。时间以酒店当地时间为准。

 /

@startDate

string

Yes

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

2018-01-01

@endDate

string

Yes

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

2018-01-01

@eachDayStartTime

string

No

每日促销开始时间

格式为“HH:MM:SS”

00:00:00

@eachDayEndTime

string

No

每日促销结束时间

格式为“HH:MM:SS”。如果在一天内的特定时间范围内预订窗口没有限制，请将eachDayStartTime和eachDayEndTime都留空。

这意味着当eachDayEndTime早于eachDayStartTime时，预订时间范围跨越一天。

12:00:00

@excludedDate

array[string]

No

不可预订的日期，格式为yyyy-MM-dd

[ "2018-01-02", "2018-01-02" ]

promotions/stayWindow

object

Yes

可入住的日期范围。时间以酒店当地时间为准。

 /

@startDate

string

Yes

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

2018-01-01

@endDate

string

Yes

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

2018-01-01

@weekdays

string

No

客户可以在一周中入住的特定日期进行此促销。每个自然周从周日开始SMTWTFS，1表示允许入住，0表示不可入住。例如，仅在周五和周六入住的促销将显示为0000011。如果为空，则默认值为1111111。

1111111

@excludedDate

array[string]

No

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

[ "2018-01-02", "2018-01-02" ]

promotions/promoteType

enum

Yes

Enum:[BasicDiscount，FreeNight，LastMinute，EarlyBooker，FixedPrice，GiftPackage]

促销类型。只能选择其中一个枚举。仅应用相应促销类型内的设置。

FreeNight

promotions/basicDiscount

object

No

 /

 /

@discountType

enum

Yes

枚举：[Percent, Fix]

低于原价的固定金额或百分比

 /

@discountValue

string

Yes

折扣值，可以是固定折扣或根据折扣类型的百分比折扣。

10

@rateApplied

boolean

Yes

标示房价是否已经应用此折扣

false

@rateApplyOn

enum

No

枚举：[AmountAfterTax，AmountBeforeTax]

如果@rateApplied为false，则此字段必填。

AmountAfterTax：基于税后价计算

AmountBeforeTax：基于税前价计算

AmountAfterTax

@addOnDescription

string

No

提供额外的礼物、服务等

A welcome drink, hot spring, and shuttle bus are included in this promotion, please ask for hotel reception while checking in.

basicDiscount/restriction

object

No

 /

 /

@minStayThrough

integer

No

客人最少入住几晚才能享受此折扣，零表示没有限制。

1

@maxStayThrough

integer

No

客人最多入住几晚才能享受此折扣，零表示无限制

4

@minRoomPerOrder

integer

No

客人最少需要预订的房间数

 /

@maxRoomPerOrder

integer

No

客人最多可预订的房间数

 /

promotions/freeNight

object

No

 /

 /

@stayNight

integer

Yes

 /

4

@freeNight

integer

Yes

 /

1

@recurring

boolean

Yes

标示此促销活动是否在整个入住期间是否重复适用。例如，如果是住四免一，如果连住八晚，true 值的话，则二晚免费，false 值则为一晚

true

@freeNightType

string

Yes

枚举：[FirstNight，LastNight]

以“住宿4晚，免费1晚”为例，允许此促销规则重复适用的话，LastNight  值，则表示第4晚和第8晚将免费。

LastNight

@rateApplied

boolean

Yes

标示房价是否已经应用此促销规则

false

@rateApplyOn

enum

No

枚举：[AmountAfterTax，AmountBeforeTax]

如果@rateApplied为false，则此字段必填。

AmountAfterTax：基于税后价计算

AmountBeforeTax：基于税前价计算

AmountAfterTax

@addOnDescription

string

No

提供额外的礼物、服务等

A welcome drink, hot spring, and shuttle bus are included in this promotion, please ask for hotel reception while checking in.

freeNight/restriction

object

No

 /

 /

@minRoomPerOrder

integer

No

最少预订几间房

 /

@maxRoomPerOrder

integer

No

最多预订几间房

 /

promotions/lastMinute

object

No

为最后一刻预订者提供的促销活动

 /

lastMinute/discount

object

Yes

 /

 /

@discountType

enum

Yes

枚举：[[Percent, Fix]]

Fix

@discountValue

number

Yes

折扣值，可以是固定折扣或根据折扣类型的百分比折扣。

10

lastMinute/rateApplied

boolean

Yes

标示房价是否已经应用此促销规则

false

lastMinute/rateApplyOn

enum

No

枚举：[AmountAfterTax，AmountBeforeTax]

如果@rateApplied为false，则此字段必填。

AmountAfterTax：基于税后价计算

AmountBeforeTax：基于税前价计算

AmountAfterTax

lastMinute/addOnDescription

string

No

这里可以提供额外的礼物、服务或附加组件。

A welcome drink, hot spring, shuttle bus are included in this promotion, please ask for hotel reception while checking-in.

lastMinute/restriction

ojbect

Yes

 /

 /

@minStayThrough

integer

No

客人最少入住几晚才能享受此折扣，零表示没有限制。

1

@maxStayThrough

integer

No

客人最多入住几晚才能享受此折扣，零表示没有限制。

4

@minAdvanceHour

integer

No

最少提前多少小时预订，时间数可以超过23小时

 /

@maxAdvanceHour

integer

Yes

最多允许提前多少小时预订，时间数可以超过23小时

 /

@minRoomPerOrder

integer

No

客人最少需要预订的房间数

 /

@maxRoomPerOrder

integer

No

客人最多允许预订的房间数

 /

promotions/earlyBooker

object

No

早鸟价

 /

earlyBooker/discount

ojbect

No

 /

 /

@discountType

enum

Yes

枚举：[[Percent, Fix]]

低于原价的固定金额或百分比

 

@discountValue

string

Yes

折扣值，可以是固定折扣或根据折扣类型的百分比折扣。

10

earlyBooker/rateApplied

boolean

Yes

标示房价是否已经应用此促销规则

false

earlyBooker/rateApplyOn

enum

No

枚举：[AmountAfterTax，AmountBeforeTax]

如果@rateApplied为false，则此字段必填。

AmountAfterTax：基于税后价计算

AmountBeforeTax：基于税前价计算

AmountAfterTax

earlyBooker/addOnDescription

string

No

提供额外的礼物、服务等

A welcome drink, hot spring, and shuttle bus are included in this promotion, please ask for hotel reception while check-in.

earlyBooker/restriction

object

No

 /

 /

@minStayThrough

integer

No

客人最少住几晚才能使用此促销，零表示没有限制。

1

@maxStayThrough

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

4

@minAdvanceDay

integer

Yes

客人最少提前几天预订才能享受此促销，零表示没有限制。

 /

@minRoomPerOrder

integer

No

客人最少预订几间房

 /

@maxRoomPerOrder

integer

No

客人最多预订几间房

 /

promotions/fixedPrice

object

No

使用固定价格替代原价

 /

@type

object

Yes

枚举：[OccupancyRate，CommonRate]

标示要使用的费率模型，OccupancyRate或CommonRate。

OccupancyRate

fixedPrice/occupancyRat

 /

 /

 /

 /

occupancyRate / rate

 /

 /

 /

 /

@adultCount

integer

Yes

 /

1

@childCount

integer

No

 /

2

@amountBeforeTax

number

No

 /

522

@amountAfterTax

number

No

 /

566

fixedPrice/commonRate

 /

 No

 /

 /

@amountBeforeTax

number

 No

 /

522

@amountAfterTax

number

No

 /

566

fixedPrice/rateApplied

boolean

Yes

标示房价是否已经应用此促销规则

false

fixedPrice/addOnDescription

string

No

提供额外的礼物、服务等

Welcome drink, hot spring, shuttle bus are included in this promotion, please ask for hotel reception while check-in.

fixedPrice/restriction

object

No

 /

 /

@minStayThrough

integer

No

客人最少住几晚才能使用此促销，零表示没有限制。

1

@maxStayThrough

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

4

@minAdvanceDay

integer

No

客人最少提前几天预订才能使用此促销，零表示没有限制。

 /

@maxAdvanceDay

integer

No

客人最多提前几天预订才能使用此促销，零表示没有限制。

 /

@minAdvanceHour

integer

No

客人最少提前多少小时才能使用此促销，零表示没有限制。

 /

@maxAdvanceHour

integer

No

客人最少提前多少小时才能使用此促销，零表示没有限制。

 /

@minRoomPerOrder

integer

No

客人最少预订几间房才能使用此促销，零表示没有限制。

 /

@maxRoomPerOrder

integer

No

客人最多预订几间房才能使用此促销，零表示没有限制。

 /

promotions/giftPackage

object

No

 /

 /

@description

string

No

价格中包含额外的晚餐作为礼物，入住时请在酒店前台询问。

 /

giftPackage/restriction

object

No

 /

 /

@minStayThrough

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

1

@maxStayThrough

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

4

@minRoomPerOrder

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

 /

@maxRoomPerOrder

integer

No

客人最多住几晚才能使用此促销，零表示没有限制。

 /

promotions/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

 /

No

 /

 /

@offsetTimeDropType

enum

No

一种枚举类型，指示最后期限删除时间何时生效。

枚举：[BeforeArrival]

 /

@offsetTimeUnit

enum

No

枚举：[D，H]

 /

@offsetTimeValue

number

No

时间数

 /

@deadline

string

No

允许取消的酒店本地截止时间，如下午4点、下午6点。

 /

cancelPenalties/penaltyCharge

 /

Yes

 /

 /

@chargeBase

enum

No

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


枚举：[FullStay，NightBase]

 /

@nights

number

No

如果罚款是基于当晚，如第一晚，则存在。

 /

@amount

number

No

如果罚款是固定费用，如30.00美元，则存在。

 /

@percent

number

No

如果罚款为%，则存在，如15.5表示15.5%。

 /

promotions/mealPlan

string

No

餐食代码，参考标准 meal plan code list. 它将覆盖原始的产品膳食计划。

RO

promotions/extensions

object

No

用于额外属性或参数等

{"key1": "value1"}

extension

object

No

用于额外属性或参数等

{"key1": "value1"}



响应示例

  • 成功响应（HTTP状态200）
{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "extension": {
    "userName": "username",
    "password": "password"
  }
}
  • 错误响应（HTTP状态500）
{
  "errorCode": "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

extension

object

No

用于额外属性或参数等

{"key": "value"}