此页面由 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 一致。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	针对特定年龄段儿童收取的费用。这些 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 之间的十进制值，用于指定要针对这个价格括号中的多名儿童收取的费用占成人价格的百分比。此费用使用的货币与为每晚费率指定的货币相同。如需详细了解成人价格的计算方式，请参阅 `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` 属性中的 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”指定日期范围允许工作日。有效字符包括： `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 上搜索四位成人时，总费率为 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` 消息已成功处理，没有出现警告、错误或失败。每条消息中是否存在 `<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>