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 這則訊息的合作夥伴帳戶。這個字串值為 列於 Partner key 個值 Hotel Center 的「帳戶設定」頁面。

注意：如果您的後端 多個帳戶，這個值必須符合 ID 在 <RequestorID> 中指定的屬性值 加入 <OTA_HotelRateAmountNotifRQ> 和 有 <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。這個值必須符合 使用 指定飯店 ID <listing> 元素中的 <id> 自動擷取廣告飯店 ID 也會列在 Hotel Center 中。
ExtraGuestCharges / HotelExtraGuestCharges / @action 0..1 enum 指定套用更新的方式，只有 overlay 是 且預設值為疊加層。先前 屬性會在套用更新前清除。
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge 0..99 ExtraGuestCharge

為房源產生的一組費用。這類內容可能包含 收費方式及費用計算方式 還是根據年齡或訪客類別來計算

中的每個 ExtraGuestCharge HotelExtraGuestCharges必須套用到一組不重複的日期 和產品如果兩個 ExtraGuestCharge 元素參照了相同的 date-product 的組合，則整封郵件都會遭到拒絕。
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(資源資料)。例如：未滿特定年齡的嬰兒 可能就不會再計入兒童容量
ExtraGuestCharges / HotelExtraGuestCharges / ExtraGuestCharge / AgeBrackets / ChildAgeBrackets / ChildAgeBracket / @amount 0..1 float 非負數小數值，用來指定要做為固定金額 因為本括弧有 1 個額外子本這筆費用使用了 與每晚房價所指定的貨幣相同。
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> 值。(現在是 <RoomID> 這個值也會由以下項目的 InvTypeCode 屬性參照： OTA_HotelRateAmountNotifRQ 訊息。)
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 值 顯示在交易 (資源資料) 訊息中，以及 RatePlanCode 屬性 兩者皆有 <StatusApplicationControl> <OTA_HotelRateAmountNotifRQ> 和 <OTA_HotelAvailNotifRQ> 訊息。 長度上限為 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 上搜尋 4 位成人，總費率會是 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>

上述訊息指出任何產品都應以成人收費 房間類型為「皇后」或「king」使用房價方案「免費 Wi-Fi」或 「節日早餐」針對 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> 個 指定以及「免費 Wi-Fi」9 月 1 日至 14 日 額外增加的 50 位成人第二個<ExtraGuestCharge> 會指定任一「皇后」或「king」連線至任何「免費 Wi-Fi」或 「節日早餐」9 月 1 日至 5 日則應為更多成人收取 20 的費用。 「皇后」出現重複的收費以及「免費 Wi-Fi」9 月 1 日至 第 5 次，還是與另外一名成人充電 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>