ExtraGuestCharges

除了房价的原始房客数量之外,您可以修改通过 <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 消息具有以下元素和属性:

Element / @Attribute 出现次数 类型 说明
ExtraGuestCharges 1 Complex element 此消息的根元素。
ExtraGuestCharges / @partner 1 string 此消息的合作伙伴账号。此字符串值是 Hotel Center 的 “帐号设置”页面上列出的 Partner key 值。

注意:如果您的后端为多个帐号提供 Feed,则此值需要与同一帐号的 <OTA_HotelRateAmountNotifRQ><OTA_HotelAvailNotifRQ> 消息的 <RequestorID> 元素中指定的 ID 属性值匹配。

ExtraGuestCharges / @id 1 string 此请求消息的唯一标识符。此值会在响应消息中返回。允许使用的字符包括 a-zA-Z0-9_(下划线)和 -(短划线)。
ExtraGuestCharges / @timestamp 1 DateTime 此消息的创建日期和时间。
ExtraGuestCharges / HotelExtraGuestCharges 0..n HotelExtraGuestCharges 用于存储针对单个媒体资源的费用的容器。
ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id 1 string 房源的唯一标识符。此值必须与酒店列表 Feed 的 <listing> 元素中使用 <id> 指定的酒店 ID 一致。酒店 ID 也会显示在 Hotel Center 中。
ExtraGuestCharges / HotelExtraGuestCharges / @action 0..1 enum 指定如何应用更新。仅支持 overlay,默认值为叠加层。在更新之前,系统会清除此媒体资源之前的所有费用。
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge 0..99 ExtraGuestCharge

针对媒体资源的一组费用。这可能包含有关扣款方式以及按年龄或房客类别计算费用的方式的限制。

HotelExtraGuestCharges 中的每个 ExtraGuestCharge 都必须适用于一组唯一的日期和产品。如果两个 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 针对特定年龄段的儿童收取的费用。应按照从最低 max_age 到最高 max_age 的顺序进行排序。可以使用 amountpercentagediscount_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 之间的十进制值,用于指定应为此类别中额外一名儿童支付的成人价格的百分比。此费用使用的币种与为每晚房价指定的币种相同。

如需详细了解成人价格的计算方式,请参阅 counts_as_base_occupant 中的讨论。

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @discount_amount 0..1 float

一个正数十进制值,用于指明针对这个年龄段中多名儿童在成人价格基础上享受的固定折扣金额。 此费用使用的币种与为每晚房价指定的币种相同。

一般来说,此年龄段中孩子的费用是通过从“单价”中扣减固定金额来计算的。counts_as_base_occupant 属性部分下详细说明了单价。

ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @counts_as_base_occupant 0..1 string

如果指定了 percentagediscount_amount 属性,还必须指定 counts_as_base_occupant。此值确定在您选择 <BaseByGuestAmount> 费率来应用百分比费用和折扣时,是否应将子级包含在 NumberOfGuest 中。

这样做的目标是获得可以计算实际费用的“单位价格”。

unit price = rate / occupancy

此属性的值必须是 neverpreferredalways 中的一个。

  • 如果指定了 never,则房价的入住人数中绝不应包含子项。

    如果您想计算 2 名成人和 2 名儿童 (2+2) 的房价,则应使用 2 名成人的房价,因为不应该将儿童包含在内。

  • 如果指定了 preferred,则最好将儿童包含在房价中的入住人数内。

    如果您想计算 2 名成人和 1 名儿童 (2+1) 的房价,则最好使用 3 名成人的房价,但如果找不到,则应使用 2 名成人的房价。

  • 如果指定了 always,则房价的入住人数应始终包含子级。

    如果您想计算 2 名成人和 2 名儿童 (2+2) 的房价,则应使用 4 名成人的房价,因为必须将儿童包含在内。

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 属性中的值。 允许的最大字符数为 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”指定允许在日期范围内使用工作日。

有效字符包括:

  • 周一价格为 M
  • 周二价格为 T
  • 周三W
  • 周四:H
  • 周五F
  • S(周六)
  • U(周日)

任何字符组合都有效。

示例

成人费用

额外成人的费用只能以固定金额表示。以下示例展示了一条指定成人费用的 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 上搜索 4 名成人时,总匹配率为 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 日期间,如果商品包含客房类型为“queen”或“king”,费率方案为“free-wifi”或“hot-breakfast”的任何商品,都应该向成人收费。

重叠收费

本部分介绍了一个无效消息示例,该消息为相同的日期和产品组合指定不同的费用。


<?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 日的“queen”和“free-wifi”应该额外收取 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 消息具有以下元素和属性:

Element / @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 消息已成功处理,且未出现警告、错误或失败。

每条消息中存在 <Success><Issues>

ExtraGuestChargesResponse / Issues 0..1 Issues 用于存储处理 ExtraGuestCharges 消息时遇到的一个或多个问题的容器。

每条消息中存在 <Success><Issues>

ExtraGuestChargesResponse / Issues / Issue 1..n Issue 对处理 ExtraGuestCharges 消息时遇到的警告、错误或失败的说明。如需详细了解这些问题,请参阅 Feed 状态错误消息
ExtraGuestChargesResponse / Issues / Issue / @code 1 integer 问题的标识符。
ExtraGuestChargesResponse / Issues / Issue / @status 1 enum

遇到的问题类型。

有效值为 warningerrorfailure

示例

成功

以下是对成功处理的 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>