除了原始房客人数外,通过 <OTA_HotelRateAmountNotifRQ>
发送的房价可修改为适合成人和儿童。ExtraGuestCharges
消息可让您指定如何为这些额外的房客计算房价,以及这些房客应针对哪些客房、价格方案和住宿日期收费。
容量要求
根据 ExtraGuestCharges
消息计算的价格仅在满足所有容量要求时才有效。如需了解详情,请参阅交易(房源数据)。
请求
语法
ExtraGuestCharges
消息使用以下语法:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges partner="partner_account_name"
id="message_ID"
timestamp="timestamp">
<HotelExtraGuestCharges hotel_id="HotelID" action="[overlay]">
<ExtraGuestCharge>
<RatePlans>
<RatePlan id="PackageID_1"/>
<RatePlan id="PackageID_2"/>
</RatePlans>
<RoomTypes>
<RoomType id="RoomID_1"/>
<RoomType id="RoomID_2"/>
</RoomTypes>
<StayDates>
<DateRange start="YYYY-MM-DD" end="YYYY-MM-DD"
days_of_week="MTWHFSU_or_subset"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="float"/>
<ChildAgeBrackets>
<!-- The following are different ways child charges can be specified.
Use the option that matches your system. -->
<ChildAgeBracket max_age="integer" amount="float"
exclude_from_capacity="[true|false]"/>
<ChildAgeBracket max_age="integer" percentage="float"
exclude_from_capacity="[true|false]"
counts_as_base_occupant="[never|preferred|always]"/>
<ChildAgeBracket max_age="integer" discount_amount="float"
exclude_from_capacity="[true|false]"
counts_as_base_occupant="[never|preferred|always]"/>
</ChildAgeBrackets>
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
元素和属性
ExtraGuestCharges
消息包含以下元素和属性:
元素 / @Attribute | 出现次数 | 类型 | 说明 |
---|---|---|---|
ExtraGuestCharges | 1 | Complex element | 此消息的根元素。 |
ExtraGuestCharges / @partner | 1 | string | 此消息所属的合作伙伴账号。此字符串值是 Hotel Center
帐号设置页面上列出的 Partner key 值。
注意:如果您的后端为多个帐号提供 Feed,则此值需要与同一帐号的 |
ExtraGuestCharges / @id | 1 | string | 此请求消息的唯一标识符。该值在响应消息中返回。允许使用的字符包括 a-z 、A-Z 、0-9 、_ (下划线)和 - (短划线)。 |
ExtraGuestCharges / @timestamp | 1 | DateTime | 此消息的创建日期和时间。 |
ExtraGuestCharges / HotelExtraGuestCharges | 0..n | HotelExtraGuestCharges | 用于存储单个媒体资源的费用的容器。 |
ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id | 1 | string | 房源的唯一标识符。此值必须与酒店列表 Feed 的 <listing> 元素中的
<id> 指定的酒店 ID 一致。Hotel Center 中也会列出酒店 ID。 |
ExtraGuestCharges / HotelExtraGuestCharges / @action | 0..1 | enum | 指定如何应用更新。仅支持 overlay ,默认为叠加层。在应用更新之前,此媒体资源之前的所有费用都会结清。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge | 0..99 | ExtraGuestCharge | 针对一个媒体资源的同一组费用。这可能包含关于收费方式以及按年龄或房客类别计算费用的方式的限制。
|
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets | 1 | AgeBrackets | 年龄段的容器,用于按年龄或房客类别计算费用。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge | 0..1 | AdultCharge | 用于支付额外的成人费用的容器。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / AdultCharge / @amount | 0..1 | float | 一个正小数值,用于指定要为额外的成人支付的固定金额。这笔费用使用的货币与为每晚房价指定的货币相同。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets | 0..1 | ChildAgeBrackets | 用于支付额外子级费用的容器。这些年龄段可能只涵盖 0-17 岁(含)的年龄段。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket | 1..99 | ChildAgeBracket | 针对特定年龄段儿童收取的费用。这些 ID 应按照从 max_age 从低到高 max_age 的顺序排列。您可以使用 amount 、percentage 或 discount_amount 指定收取的金额。必须为每个 <ChildAgeBracket> 指定其中一个属性。
|
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age | 1 | integer | <ChildAgeBracket> 中指定的费用适用的最长存在时间。如果在此时间之前未指定其他 <ChildAgeBracket> ,则最短存在时间为零。否则,该值将大于上一个括号的最大存在时间。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity | 1 | boolean | 一个布尔值,用于指示此年龄段中的儿童是否应计入会议室的总容纳人数和儿童可容纳人数。可以使用 交易(房源数据)设置这些容量。例如,未满特定年龄的婴儿可能不需要计入可容纳儿童的儿童数量。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount | 0..1 | float | 一个非负小数值,用于指定要为此括号中的额外子组收取的固定金额。此费用使用的货币与为每晚房价指定的货币相同。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @percentage | 0..1 | float | 一个介于 1 到 99 之间的十进制值,用于指定要针对这个价格括号中的多名儿童收取的费用占成人价格的百分比。此费用使用的货币与为每晚费率指定的货币相同。 如需详细了解成人价格的计算方式,请参阅 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount | 0..1 | float | 一个正小数值,用于指定此价格括号中另一个儿童的成人价格的固定折扣金额。 此费用使用的币种与每晚费率指定的币种相同。 一般而言,此年龄段内的儿童的费用是通过从“单价”中减去固定金额计算得出的。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant | 0..1 | string | 如果指定了 您的目标是获取“单价”,以便根据该单价计算实际费用。
此属性的值必须是
|
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes | 0..1 | RoomTypes | 收取相应费用的客房类型列表的容器。
这些费用适用于指定的每个 <RoomType> 。如果未指定 <RoomTypes> ,费用将应用于指定酒店内的所有客房。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType | 1..n | RoomType | 指定房间类型。客房类型在交易(房源数据)消息的 <RoomData> 元素中定义,并使用其 <RoomID> 值引用。(OTA_HotelRateAmountNotifRQ 消息中的 InvTypeCode 属性也会引用其 <RoomID> 值。) |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RoomTypes / RoomType / @id | 1 | string | 房源的唯一标识符(房间类型)。此值映射到交易(房源数据)消息中的 <RoomID> 。
允许的最大字符数为 50。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans | 0..1 | RatePlans | 包含收取相应费用的费率方案列表的容器。
如果未指定 <RatePlans> ,则该费用适用于所有费率方案。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan | 1..n | RatePlan | 指定费率方案。房价方案由套餐、房价和空房情况的组合定义,如“交易”(房源数据)、OTA_HotelRateAmountNotifRQ 和 OTA_HotelAvailNotifRQ 消息中所定义,并由 PackageID 标识。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / RatePlans / RatePlan / @id | 1 | string | 费率方案的唯一标识符。此值映射到交易(房源数据)消息的 <PackageData> 中的 PackageID 值,以及 <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 消息的 <StatusApplicationControl> 的 RatePlanCode 属性中的 PackageID 值。
允许的最大字符数为 50。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates | 0..1 | StayDates | 一个或多个日期范围的容器,用于确定费用的收取方式。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange | 1..99 | DateRange | 用于指定促销活动应用日期的日期范围。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @start | 0..1 | Date | 日期范围的开始日期(基于房源的时区)。此日期必须早于 end 日期或与其相同。如果未指定 start ,就开始日期而言,日期范围实际上没有限制。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @end | 0..1 | Date | 日期范围的结束日期(基于媒体资源的时区,含此日期)。此日期必须与 start 日期相同或更晚。如果未指定 end ,就结束日期而言,日期范围实际上没有限制。 |
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / StayDates / DateRange / @days_of_week | 0..1 | string | 允许出现在日期范围内的星期几。如果未指定,则日期范围允许所有日期。字符串中的每个字符都表示日期。例如,“MTWHF”指定日期范围允许工作日。 有效字符包括:
任意字符组合均有效。 |
示例
成人费用
针对额外成人的费用只能以固定金额表示。以下示例展示了一条指定成人费用的 ExtraGuestCharges
消息:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<StayDates />
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
对应的费率如下:
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="12345678"
TimeStamp="2020-05-19T20:50:37-05:00"
Version="3.0">
<RateAmountMessages HotelCode="ABC">
<RateAmountMessage>
<StatusApplicationControl Start="2020-05-18"
End="2020-05-23"
InvTypeCode="RoomID_1"
RatePlanCode="PackageID_1"/>
<Rates>
<Rate>
<BaseByGuestAmts>
<BaseByGuestAmt AmountAfterTax="100.00"
CurrencyCode="USD"
NumberOfGuests="1"/>
<BaseByGuestAmt AmountAfterTax="110.00"
CurrencyCode="USD"
NumberOfGuests="2"/>
<BaseByGuestAmt AmountAfterTax="120.00"
CurrencyCode="USD"
NumberOfGuests="3"/>
</BaseByGuestAmts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
当用户在 Google 上搜索四位成人时,总费率为 170 = 120 + 50。
120 来自 <BaseByGuestAmt>
速率,NumberOfGuests="3"
50 来自 AdultCharge amount="50"
。
儿童扣款
儿童费用以不超过 17 岁的年龄段表示,并可以用固定金额、百分比或折扣表示。
以下示例展示了一条指定子级费用的 ExtraGuestCharges
消息:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<AgeBrackets>
<ChildAgeBrackets>
<ChildAgeBracket max_age="3" percentage="10"
counts_as_base_occupant="never" />
<ChildAgeBracket max_age="10" percentage="30"
counts_as_base_occupant="preferred"/>
<ChildAgeBracket max_age="17" discount_amount="10"
counts_as_base_occupant="always" />
</ChildAgeBrackets>
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
对应的费率如下:
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelRateAmountNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="12345678"
TimeStamp="2020-05-19T20:50:37-05:00"
Version="3.0">
<RateAmountMessages HotelCode="ABC">
<RateAmountMessage>
<StatusApplicationControl Start="2020-05-18"
End="2020-05-23"
InvTypeCode="RoomID_1"
RatePlanCode="PackageID_1"/>
<Rates>
<Rate>
<BaseByGuestAmts>
<BaseByGuestAmt AmountAfterTax="100.00"
CurrencyCode="USD"
NumberOfGuests="1"/>
<BaseByGuestAmt AmountAfterTax="110.00"
CurrencyCode="USD"
NumberOfGuests="2"/>
</BaseByGuestAmts>
</Rate>
</Rates>
</RateAmountMessage>
</RateAmountMessages>
</OTA_HotelRateAmountNotifRQ>
```
1. Suppose you want the total price for 2 adults and 1 child of 2 years
of age.
Children aged 0-3 are never included in the rate's occupancy,
so here you should take the double occupancy rate and divide by 2 to
get the unit price. Then, multiply by the percentage rate and sum
with the rate to get the total price.
`unit price ` = 110 / 2 = 55
`total price` = 110 + 55 * 0.1 = 115.5
1. Suppose you want the total price for 1 adult and 2 children, both of 5
years of age.
Children aged 4-10 are preferably included in the rate's
occupancy. you should start by looking for a 3 adult rate since both
children are preferably included in the rate's occupancy. Since
that doesn't exist you should fall back to the 2 adult rate and then,
take this rate and divide by two to get the unit price. Finally,
multiply by the percentage rate and sum with the scaled rate to
get the total price.
`unit price` = 110 / 2 = 55
`total price` = 55 + 55 * 0.3 + 55 * 0.3 = 88
1. Suppose you want the total price for 1 adult and 1 child of 17
years of age.
Children aged 11-17 are always included in the rate's occupancy, so,
in this case, take the double occupancy rate and divide by 2 to get
the unit price. Then, deduct it by the discount amount and sum with
the scaled rate to get the total price.
`unit price` = 110 / 2 = 55
`total price` = 55 + (55 - 10) = 100
费用限制
所有类型的限制都是可选的,您可以使用它们的任意组合。
以下示例展示了一条指定限制的 ExtraGuestCharges
消息:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
<RoomType id="king" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
<RatePlan id="hot-breakfast" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-14"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
上述消息指定,对于 2020 年 9 月 1 日至 2020 年 9 月 14 日期间客房类型为“大号”或“特大”且价格方案为“免费 Wi-Fi”或“热早餐”的任何产品,成人均应支付相应的费用。
重叠费用
本部分显示了一个无效消息示例,该消息针对相同的日期和产品组合指定了不同的费用。
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestCharges timestamp="2001-02-03T04:05:06+00:00" id="1">
<HotelExtraGuestCharges hotel_id="ABC" action="overlay">
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-14"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="50" />
</AgeBrackets>
</ExtraGuestCharge>
<ExtraGuestCharge>
<RoomTypes>
<RoomType id="queen" />
<RoomType id="king" />
</RoomTypes>
<RatePlans>
<RatePlan id="free-wifi" />
<RatePlan id="hot-breakfast" />
</RatePlans>
<StayDates>
<DateRange start="2020-09-01" end="2020-09-05"/>
</StayDates>
<AgeBrackets>
<AdultCharge amount="20" />
</AgeBrackets>
</ExtraGuestCharge>
</HotelExtraGuestCharges>
</ExtraGuestCharges>
上述消息无效,因为第一个 <ExtraGuestCharge>
指定 9 月 1 日至 14 日期间的“大号床”和“免费 Wi-Fi”应额外加收 50 名成人的费用。第二个 <ExtraGuestCharge>
指定 9 月 1 日至 5 日期间,任一“女王”或“王”以及“免费 Wi-Fi”或“热早餐”中的任何一项,均应额外向成人收取 20 人的费用。从 9 月 1 日至 5 日,“女王”和“免费 Wi-Fi”的费用发生重叠,而额外的成人的费用是 20 美元还是 50 美元存在冲突。
响应
语法
ExtraGuestChargesResponse
消息使用以下语法:
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="timestamp"
id="message_ID"
partner="partner_key">
<!-- Either Success or Issues will be populated. -->
<Success/>
<Issues>
<Issue code="issue_code" status="issue_type">issue_description</Issue>
</Issues>
</ExtraGuestChargesResponse>
元素和属性
ExtraGuestChargesResponse
消息包含以下元素和属性:
元素 / @Attribute | 出现次数 | 类型 | 说明 |
---|---|---|---|
ExtraGuestChargesResponse | 1 | Complex element | 指示收到的 ExtraGuestCharges 请求消息是成功还是有问题的根元素。 |
ExtraGuestChargesResponse / @timestamp | 1 | DateTime | 此消息的创建日期和时间。 |
ExtraGuestChargesResponse / @id | 1 | string | 关联的 ExtraGuestCharges 消息中的唯一标识符。 |
ExtraGuestChargesResponse / @partner | 1 | string | 此消息所属的合作伙伴账号。 |
ExtraGuestChargesResponse / Success | 0..1 | Success | 表示 ExtraGuestCharges 消息已成功处理,没有出现警告、错误或失败。
每条消息中是否存在 |
ExtraGuestChargesResponse / Issues | 0..1 | Issues | 处理 ExtraGuestCharges 消息时遇到的一个或多个问题的容器。
每条消息中是否存在 |
ExtraGuestChargesResponse / Issues / Issue | 1..n | Issue | 对处理 ExtraGuestCharges 消息时遇到的警告、错误或失败的说明。如需详细了解这些问题,请参阅 Feed 状态错误消息。 |
ExtraGuestChargesResponse / Issues / Issue / @code | 1 | integer | 问题的标识符。 |
ExtraGuestChargesResponse / Issues / Issue / @status | 1 | enum | 遇到的问题类型。 有效值为 |
示例
成功
以下是对已成功处理的 ExtraGuestCharges
消息的响应。
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Success/>
</ExtraGuestChargesResponse>
问题
以下是对由于错误而未处理的 ExtraGuestCharges
消息的响应。
<?xml version="1.0" encoding="UTF-8"?>
<ExtraGuestChargesResponse timestamp="2020-05-18T16:20:00-04:00"
id="12345678"
partner="partner_key">
<Issues>
<Issue code="1001" status="error">Example</Issue>
</Issues>
</ExtraGuestChargesResponse>