此页面由 Cloud Translation API 翻译。

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 中 `<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` 的顺序排列。您可以使用 `amount`、`percentage` 或 `discount_amount` 指定要收取的金额。必须为每个 `<ChildAgeBracket>` 指定其中一个属性。
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @max_age	1	integer	`<ChildAgeBracket>` 中指定的费用可能适用的最长年龄。如果在此 `<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>` 值进行引用。（其 `<RoomID>` 值也被 OTA_HotelRateAmountNotifRQ 消息中的 `InvTypeCode` 属性引用。）
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 日期间，房型为“双人床”或“大床”，且房价方案为“免费 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 日的“queen”和“free-wifi”应对每位额外成人收取 50 美元。第二个 <ExtraGuestCharge> 指定，如果客人选择“queen”或“king”客房，并选择“free-wifi”或“hot-breakfast”，则 9 月 1 日至 5 日期间每位额外成人需支付 20 美元。9 月 1 日至 5 日期间，“queen”和“free-wifi”的费用重叠，并且对于额外一名成人，收费标准存在 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>

ExtraGuestCharges 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

容量要求

请求

语法

元素和属性

示例

成人费用

子级费用

扣款限制

重叠扣款

响应

语法

元素和属性

示例

成功

问题

ExtraGuestCharges