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 消息具有以下元素和属性：

元素 / @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-z、A-Z、0-9、_（下划线）和 -（短划线）。
ExtraGuestCharges / @timestamp 1 DateTime 相应消息的创建日期和时间。
ExtraGuestCharges / HotelExtraGuestCharges 0..n HotelExtraGuestCharges 单个媒体资源的费用的容器。
ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id 1 string 房源的唯一标识符。此值必须与酒店列表 Feed 中使用 <id> 在 <listing> 元素中指定的酒店 ID 相匹配。您还可以在 Hotel Center 中找到酒店 ID。
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 的顺序排列。可以使用 amount、percentage 或 discount_amount 指定要收取的金额。必须为每个 <ChildAgeBracket> 指定这些属性中的一个。
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age 1 integer <ChildAgeBracket> 中指定的费用可能适用的最大年龄。如果没有在此之前指定其他 <ChildAgeBracket>，则最小年龄为零。否则，该年龄段的最小年龄比前一个年龄段的最大年龄大 1。
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @exclude_from_capacity 1 boolean 一个布尔值，用于指示此年龄段的儿童是否应计入房间的总容量和儿童容量。这些容量可以通过 Transaction(Property Data) 进行设置。例如，未满一定年龄的婴儿可能无需计入儿童人数上限。
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

如果指定了 percentage 或 discount_amount 属性，则还必须指定 counts_as_base_occupant。此值用于确定在选择 <BaseByGuestAmount> 费率以应用百分比费用和折扣时，是否应将儿童纳入 NumberOfGuest 中。

此处的目的是获取“单价”，以便计算实际费用。

unit price = rate / occupancy

此属性的值必须为 never、preferred 或 always 之一。

  • 如果指定了 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 来自 NumberOfGuests="3" 的 <BaseByGuestAmt> 比率，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 消息具有以下元素和属性：

元素 / @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

遇到的问题类型。

有效值为 warning、error 和 failure。

示例

成功

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