概览
借助此 API,您可以定义方式,以便在满足条件时对房价动态应用操作,例如调整价格或启用可退款性。与 Promotions API(只能应用折扣力度最高的符合条件的促销活动)不同,此 API 会在满足特定条件时应用所有操作,包括可能最终提高最终价格的价格调整。
请求
语法
RateModifications
消息使用以下语法:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="partner_key"
id="message_ID"
timestamp="timestamp">
<HotelRateModifications hotel_id="HotelID" action="[overlay]">
<ItineraryRateModification id="ModificationID" action="[delete]">
<BookingDates>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week=""MTWHFSU_or_subset""/>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week=""MTWHFSU_or_subset""/>
</BookingDates>
<BookingWindow min="integer" max="integer"/>
<CheckinDates>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week=""MTWHFSU_or_subset""/>
</CheckinDates>
<CheckoutDates>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week=""MTWHFSU_or_subset""/>
</CheckoutDates>
<Devices>
<Device type="[desktop|tablet|mobile]"/>
</Devices>
<LengthOfStay min="integer" max="integer"/>
<MinimumAmount before_discount="integer"/>
<RatePlans>
<RatePlan id="PackageID_1"/>
<RatePlan id="PackageID_2"/>
</RatePlans>
<RoomTypes>
<RoomType id="RoomID_1"/>
<RoomType id="RoomID_2"/>
</RoomTypes>
<StayDates application="[all|any]">
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week=""MTWHFSU_or_subset""/>
</StayDates>
<UserCountries type="[include|exclude]">
<Country code="country_code"/>
</UserCountries>
<ModificationActions>
<PriceAdjustment multiplier="float"/>
<RateRule id="RateRuleID"/>
<Refundable available="[false|true]"
refundable_until_days="number_of_days"
refundable_until_time="time"/>
<Availability status="[unavailable]"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
元素和属性
RateModifications
消息包含以下元素和属性:
元素 / @Attribute | 出现次数 | 类型 | 说明 |
---|---|---|---|
RateModifications | 1 | Complex element | 费率修改消息的根元素。 |
RateModifications / @partner | 1 | string | 此消息所属的合作伙伴账号。此字符串值是 Hotel Center
帐号设置页面上列出的“合作伙伴密钥”值。
注意:如果您的后端为多个帐号提供 Feed,则此值需要与同一帐号的 |
RateModifications / @id | 1 | string | 此请求消息的唯一标识符。该值在响应消息中返回。允许使用的字符包括 a-z、A-Z、0-9、_(下划线)和 -(短划线)。 |
RateModifications / @timestamp | 1 | DateTime | 此消息的创建日期和时间。 |
RateModifications / HotelRateModifications | 0..n | HotelRateModifications | 房源的房价调整。每个费率修改均适用于单个房源。 注意:如果对同一费率应用多项费率修改,则系统将应用所有修改。无法保证特定顺序。 |
RateModifications / HotelRateModifications / @hotel_id | 1 | string | 房源的唯一标识符。此值必须与酒店列表 Feed 的 <listing> 元素中的
<id> 指定的酒店 ID 一致。Hotel Center 中也会列出酒店 ID。 |
RateModifications / HotelRateModifications / @action | 0..1 | enum | 如果未指定 |
RateModifications / HotelRateModifications / ItineraryRateModification | 0..200 | ItineraryRateModification | 对房源的单次费率修改。 注意:费率修改难以调试,因此建议您谨慎使用。对于需要修改超过 200 次费率的用例,请与您的技术支持客户经理 (TAM) 联系。 |
RateModifications / HotelRateModifications / ItineraryRateModification / @id | 1 | string | 房价修改的唯一标识符。允许的最大字符数为 40。允许使用的字符包括 a-z、A-Z、0-9、_(下划线)、-(短划线)和 . (英文句点)。 |
RateModifications / HotelRateModifications / ItineraryRateModification / @action | 0..1 | enum | 如果未指定,并且未存储具有相同 如果指定,则值必须为 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingDates | 0..1 | BookingDates | 一个或多个日期范围的容器,用于定义预订时间,才能应用房价修改。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingDates / DateRange | 1..99 | DateRange | 一个日期范围,用于指定要应用房价修改必须何时进行预订。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingDates / DateRange / @start | 0..1 | Date | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingDates / DateRange / @end | 0..1 | Date | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingWindow | 0..1 | BookingWindow | 指定相对于入住日期(以酒店所在的时区)为准的预订时间段。例如,预订期限可设置为入住前至少 7 天,但不超过 180 天。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingWindow / @min | 0..1 | integer | 入住前至少需要提前多少天预订,才能应用房价修改。如果未指定,则没有最小值。 |
RateModifications / HotelRateModifications / ItineraryRateModification / BookingWindow / @max | 0..1 | integer | 若要应用房价修改,必须在入住前入住的最晚天数。如果未指定,则表示没有最大值。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckinDates | 0..1 | CheckinDates | 一个或多个日期范围的容器,用于定义入住时间必须在什么时间入住才能应用房价修改。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckinDates / DateRange | 1..99 | DateRange | 一个日期范围,用于指定必须在何时入住才能应用房价修改。如果您要删除一个或多个费率修改,则不需要此元素。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckinDates / DateRange / @start | 0..1 | Date | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckinDates / DateRange / @end | 0..1 | Date | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckinDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckoutDates | 0..1 | CheckoutDates | 一个或多个日期范围的容器,用于定义要应用费率修改的退房时间。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckoutDates / DateRange | 1..99 | DateRange | 一个日期范围,用于指定要应用房价修改的退房时间。如果您要删除一个或多个费率修改,则不需要此元素。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckoutDates / DateRange / @start | 0..1 | Date | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckoutDates / DateRange / @end | 0..1 | Date | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / CheckoutDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
RateModifications / HotelRateModifications / ItineraryRateModification / Devices | 0..1 | Devices | 用于列出符合费率修改条件的用户设备的容器。如果已指定,则仅当用户匹配列出的其中一个设备时,系统才会应用费率修改。如果未指定,则不会限制费率修改的应用。 |
RateModifications / HotelRateModifications / ItineraryRateModification / Devices / Device | 1..3 | Device | 定义一种符合费率修改条件的用户设备。 |
RateModifications / HotelRateModifications / ItineraryRateModification / Devices / Device / @type | 1 | enum | 一种设备的类型。该值必须是 desktop 、tablet 或 mobile 。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions | 1 | ModificationActions | 满足所有指定条件时应用于费率的操作。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / PriceAdjustment | 0..1 | PriceAdjustment | 将 AmountBeforeTax 和 AmountAfterTax 都乘以指定系数来调整比率 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / PriceAdjustment / @multiplier | 1 | float | AmountBeforeTax 和 AmountAfterTax 都会与此值相乘。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / RateRule | 0..1 | RateRule | 通过应用指定的费率规则 ID 来修改费率。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / RateRule / @id | 1 | string | 此 ID 使费率与费率规则定义文件中的定义相匹配。
注意:
|
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / Refundable | 0..1 | Refundable | 将房价的可退款性覆盖为指定值。
设置属性时,请注意以下事项:
|
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / Refundable / @available | 1 | boolean | (必需)设置为 1 或 true 以指明费率是否允许全额退款;否则设置为 0 或 false 。 |
Transaction / PropertyDataSet / PackageData / Refundable / @refundable_until_days | 0..1 | integer | (如果 available 为 true ,则为必需)指定在入住前多少天可以申请全额退款。refundable_until_days 的值必须是 0 到 330(含)之间的整数。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / Refundable / @refundable_until_time | 0..1 | Time | (建议当 available 为 true 时)指定接受全额退款请求的最晚时间(酒店的当地时间)。例如,可与 refundable_until_days 结合使用以指定“退款在入住前两天下午 4 点之前均可退款”。如果未设置 refundable_until_time ,则该值默认为午夜。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / Availability | 0..1 | Availability | 将费率的可用性替换为指定值。
我们仅支持将房价设置为 unavailable 。 |
RateModifications / HotelRateModifications / ItineraryRateModification / ModificationActions / Availability / @status | 1 | enum | 如果为 status="unavailable" ,则无论费率是否存在有效价格,费率都被视为不可用。 |
RateModifications / HotelRateModifications / ItineraryRateModification / LengthOfStay | 0..1 | LengthOfStay | 定义可以应用此房价修改的住宿晚数限制。如果住宿晚数超出最低和最高限制,系统不会应用费率修改。 |
RateModifications / HotelRateModifications / ItineraryRateModification / LengthOfStay / @min | 0..1 | integer | 住宿晚数可用于应用费率修改的最短住宿晚数。如果未指定,则没有最小值。 |
RateModifications / HotelRateModifications / ItineraryRateModification / LengthOfStay / @max | 0..1 | integer | 住宿晚数可用于修改房价。如果未指定,则表示没有最大值。 |
RateModifications / HotelRateModifications / ItineraryRateModification / MinimumAmount | 0..1 | MinimumAmount | 指定应用房价修改所必须达到的每日房价总和下限(使用 AmountBeforeTax 或 AmountAfterTax 中的较大者)。 |
RateModifications / HotelRateModifications / ItineraryRateModification / MinimumAmount / @before_discount | 1 | integer | 要应用费率修改,必须超过该值。 |
RateModifications / HotelRateModifications / ItineraryRateModification / RatePlans | 0..1 | RatePlans | 包含费率修改所适用的费率方案列表的容器。如果未指定 <RatePlans> ,则费率修改会应用于所有费率方案。 |
RateModifications / HotelRateModifications / ItineraryRateModification / RatePlans / RatePlan | 1..n | RatePlan | 指定费率方案。房价方案由套餐、房价和空房情况的组合定义,如“交易”(房源数据)、OTA_HotelRateAmountNotifRQ 和 OTA_HotelAvailNotifRQ 消息中所定义,并由 PackageID 标识。 |
RateModifications / HotelRateModifications / ItineraryRateModification / RatePlans / RatePlan / @id | 1 | string | 费率方案的唯一标识符。此值映射到交易(房源数据)消息的 <PackageData> 中的 PackageID 值,以及 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 消息的 <StatusApplicationControl> 的 RatePlanCode 属性中的 PackageID 值。
允许的最大字符数为 50。 |
RateModifications / HotelRateModifications / ItineraryRateModification / RoomTypes | 0..1 | RoomTypes | 包含房价修改所适用的客房类型的列表的容器。
费率修改会应用于指定的每个 <RoomType> 。如果未指定 <RoomTypes> ,房价修改将应用于所有客房。 |
RateModifications / HotelRateModifications / ItineraryRateModification / RoomTypes / RoomType | 1..n | RoomType | 指定房间类型。客房类型在“交易(房源数据)”消息的 <RoomData> 元素中定义,并使用其 <RoomID> 值引用。(OTA_HotelRateAmountNotifRQ 消息中的 InvTypeCode 属性也会引用其 <RoomID> 值。) |
RateModifications / HotelRateModifications / ItineraryRateModification / RoomTypes / RoomType / @id | 1 | string | 房源的唯一标识符(房间类型)。此值映射到交易(房源数据)消息中的 <RoomID> 。
允许的最大字符数为 50。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates | 0..1 | StayDates | 一个或多个日期范围的容器,用于确定如何应用费率调整,例如适应季节性价格。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates / @application | 1 | enum | 说明应如何应用费率调整。 有效值包括:
必须始终指定此属性。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates / DateRange | 1..99 | DateRange | 一个日期范围,用于指定要应用汇率调整的日期。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates / DateRange / @start | 0..1 | Date | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates / DateRange / @end | 0..1 | Date | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
RateModifications / HotelRateModifications / ItineraryRateModification / StayDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
RateModifications / HotelRateModifications / ItineraryRateModification / UserCountries | 0..1 | UserCountries | 如果已指定,则仅当用户位于其中一个指定国家/地区时,才会应用费率调整。如果未指定,则无论用户身在何处,系统都会应用费率修改。 |
RateModifications / HotelRateModifications / ItineraryRateModification / UserCountries / @type | 0..1 | enum | UserCountry 规范的类型。
有效值为 如果 UserCountry 如果 User countries 如果未设置 User countries |
RateModifications / HotelRateModifications / ItineraryRateModification / UserCountries / Country | 1..300 | Country | 指定允许修改费率的用户所在国家/地区。 |
RateModifications / HotelRateModifications / ItineraryRateModification / UserCountries / Country / @code | 1 | string | CLDR 国家/地区代码,例如 DE 或 FR 。请注意,对于某些国家/地区,CLDR 国家/地区代码与由 2 个字母组成的 ISO 国家/地区代码不同。此外,CLDR 地区代码也不受支持。 |
示例
基本消息
以下示例展示了基本的 RateModifications
` 消息:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1">
<ItineraryRateModification id="1">
<BookingDates>
<DateRange start="2023-07-01" end="2023-07-31" days_of_week="MTWHF"/>
<DateRange start="2023-09-01" end="2023-09-30"/>
</BookingDates>
<BookingWindow min="7" max="330"/>
<CheckinDates>
<DateRange start="2023-10-01" end="2023-10-31" days_of_week="FSU"/>
</CheckinDates>
<CheckoutDates>
<DateRange start="2023-10-08" end="2023-11-07" days_of_week="FSU"/>
</CheckoutDates>
<Devices>
<Device type="mobile"/>
<Device type="tablet"/>
</Devices>
<LengthOfStay min="2" max="14"/>
<RatePlans>
<RatePlan id="234"/>
<RatePlan id="567"/>
</RatePlans>
<RoomTypes>
<RoomType id="123"/>
<RoomType id="456"/>
</RoomTypes>
<UserCountries>
<Country code="US"/>
<Country code="GB"/>
</UserCountries>
<ModificationActions>
<PriceAdjustment multiplier="1.2"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
删除一项价格修改
以下示例展示了如何删除媒体资源的一次费率修改:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1">
<ItineraryRateModification id="1" action="delete"/>
</HotelRateModifications>
</RateModifications>
删除所有费率修改
以下示例展示了如何删除媒体资源的所有费率修改:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1" action="overlay"/>
</RateModifications>
叠加所有费率修改
以下示例展示了如何使用一项或多项新的费率修改为房源叠加 <HotelRateModifications>
。如果设置为 action="overlay"
,则在存储当前消息中指定的费率修改之前,系统会删除所有已存储的费率修改:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1" action="overlay"/>
<ItineraryRateModification id="1">
<BookingDates>
<DateRange start="2023-09-01" end="2023-09-30"/>
</BookingDates>
<ModificationActions>
<PriceAdjustment multiplier="1.2"/>
</ModificationActions>
<RoomTypes>
<RoomType id="123"/>
<RoomType id="456"/>
</RoomTypes>
<RatePlans>
<RatePlan id="234"/>
<RatePlan id="567"/>
</RatePlans>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
多项修改操作
以下示例展示了如何一次执行多项修改操作:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1">
<ItineraryRateModification id="1">
<BookingDates>
<DateRange start="2023-01-01" end="2023-02-28"/>
</BookingDates>
<ModificationActions>
<PriceAdjustment multiplier=".95"/>
<Refundable available="true"
refundable_until_days="1"
refundable_until_time="12:00:00"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
为用户所在国家/地区停用价格方案
以下示例展示了如何将费率方案限制为仅面向日语 (JP
) 用户:
<?xml version="1.0" encoding="UTF-8"?>
<RateModifications partner="account_xyz"
id="123_abc"
timestamp="2023-05-22T16:20:00-04:00">
<HotelRateModifications hotel_id="Property_1">
<ItineraryRateModification id="1">
<RatePlans>
<RatePlan id="jp_only"/>
</RatePlans>
<UserCountries type="exclude">
<Country code="JP"/>
</UserCountries>
<ModificationActions>
<Availability status="unavailable"/>
</ModificationActions>
</ItineraryRateModification>
</HotelRateModifications>
</RateModifications>
响应
语法
RateModificationsResponse
消息使用以下语法:
<?xml version="1.0" encoding="UTF-8"?>
<RateModificationsResponse timestamp="timestamp"
id="message_ID"
partner="partner_key">
<!-- Either Success or Issues will be populated. -->
<Success/>
<Issues>
<Issue code="issue_code" status="issue_type"><var>issue_description</var></Issue>
</Issues>
</RateModificationsResponse>
元素和属性
RateModificationsResponse
消息包含以下元素和属性:
元素 / @Attribute | 出现次数 | 类型 | 说明 |
---|---|---|---|
RateModifications | 1 | Complex element | 指示收到的 RateModifications 请求消息是否成功的根元素。 |
RateModificationsResponse / @timestamp | 1 | DateTime | 此消息的创建日期和时间。 |
RateModificationsResponse / @id | 1 | string | 来自相关 RateModifications 消息的唯一标识符。 |
RateModificationsResponse / @partner | 1 | string | 此消息所属的合作伙伴账号。 |
RateModificationsResponse / Success | 0..1 | Success | 表示 RateModifications 消息已成功处理,没有出现警告、错误或失败。
每条消息中是否存在 |
RateModificationsResponse / Issues | 0..1 | Issues | 处理 RateModifications 消息时遇到的一个或多个问题的容器。
每条消息中是否存在 |
RateModificationsResponse / Issues / Issue | 1..n | Issue | 对处理 RateModifications 消息时遇到的警告、错误或失败的说明。如需详细了解这些问题,请参阅 Feed 状态错误消息。 |
RateModificationsResponse / Issues / Issue / @code | 1 | integer | 问题的标识符。 |
RateModificationsResponse / Issues / Issue / @status | 1 | enum | 遇到的问题类型。 有效值为 |
示例
成功
以下是对已成功处理的 RateModifications 消息的响应。
<?xml version="1.0" encoding="UTF-8"?>
<RateModificationsResponse timestamp="2023-05-22T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</RateModificationsResponse>
问题
以下是对因出错而未处理的 RateModifications 消息的响应。
<?xml version="1.0" encoding="UTF-8"?>
<RateModificationsResponse timestamp="2023-05-22T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Issues>
<Issue code="1001" status="error">Example</Issue>
</Issues>
</RateModificationsResponse>