本頁面由 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` 值。注意：如果您的後端會為多個帳戶提供動態饋給，則這個值必須與同一個帳戶的 `<OTA_HotelRateAmountNotifRQ>` 和 `<OTA_HotelAvailNotifRQ>` 訊息中指定的 `ID` 屬性值相符。`<RequestorID>`
ExtraGuestCharges / @id	1	string	此要求訊息的專屬 ID。這個值會在回應訊息中傳回。允許的字元包括 `a-z`、`A-Z`、`0-9`、`_` (底線) 和 `-` (破折號)。
ExtraGuestCharges / @timestamp	1	DateTime	建立這則訊息的日期和時間。
ExtraGuestCharges / HotelExtraGuestCharges	0..n	HotelExtraGuestCharges	單一資源費用的容器。
ExtraGuestCharges / HotelExtraGuestCharges / @hotel_id	1	string	房源的專屬 ID。這個值必須與飯店清單動態饋給中 `<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	特定年齡層兒童適用的費用。這些值應從最低 `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	廣告空間的專屬 ID (房間類型)。這個值會對應至交易 (資源資料) 訊息中的 `<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	費率方案的專屬 ID。這個值對應至交易 (資源資料) 訊息中 `<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 上搜尋四位成人，總費率會是 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」，應向成人收取費用。

重疊費用

本區段是無效訊息示例，指出同一日期與產品組合不同的收費方式。


<?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` 訊息的專屬 ID。
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` 訊息時發生的警告、錯誤或失敗說明。如要進一步瞭解這些問題，請參閱動態饋給狀態錯誤訊息一文。
ExtraGuestChargesResponse / Issues / Issue / @code	1	integer	問題的 ID。
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>