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> 訊息中 <RequestorID> 元素的 ID 屬性值相符。
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> 指定，則最低年齡為零。否則，這個值會比前一個區間的最大年齡大 1。
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。這個值會決定是否應在選取NumberOfGuest時，將子項納入套用百分比費用和折扣的<BaseByGuestAmount>費率。

目標是取得「單價」，藉此計算實際費用。

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 來自 <BaseByGuestAmt> 的比率，而 50 來自 AdultCharge amount="50"。NumberOfGuests="3"

下層費用

兒童費用會以年齡區間 (最高 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>

上述訊息指出，如果產品的房型為「queen」或「king」，且費率方案為「free-wifi」或「hot-breakfast」，則在 2020 年 9 月 1 日至 2020 年 9 月 14 日期間，成人應支付任何產品的費用。

重疊費用

本節顯示無效訊息的範例，其中針對相同日期和產品組合指定了不同的費用。


<?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 日的「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 訊息的專屬 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>