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 相符。Hotel Center 也會列出飯店 ID。
ExtraGuestCharges / HotelExtraGuestCharges / @action 0..1 enum 指定更新的套用方式。系統僅支援 overlay，預設值為 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 房源 (房型) 的專屬 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> 與 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>

上述訊息明確指出，如果產品房型為「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 日的「queen」或「king」房型，若提供「free-wifi」或「hot-breakfast」等服務，應向額外成人收取 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>