本頁面由 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 訊息包含下列元素和屬性：

元素 / @屬性	發生次數	類型	說明
ExtraGuestCharges	1	Complex element	這個訊息的根元素。
ExtraGuestCharges / @partner	1	string	這則訊息的合作夥伴帳戶。這個字串值是 Hotel Center 帳戶設定頁面中列出的 `Partner key` 值。注意：如果您的後端為多個帳戶提供動態饋給，這個值必須符合同一帳戶中 `<OTA_HotelRateAmountNotifRQ>` 的 `<RequestorID>` 元素所指定的 `ID` 屬性值，以及 `<OTA_HotelAvailNotifRQ>` 訊息。
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 相符。飯店 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>`，則最低存在時間是零。否則，它會大於前一個括號的最大存在時間。
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	商品目錄 (客房類型) 的專屬 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」的產品，且房價方案為「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 訊息包含下列元素和屬性：

元素 / @屬性	發生次數	類型	說明
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>