購物

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

簡介

「購物 API」會針對指定旅宿傳回所有房型的房價和供應情況 (每項請求最多 250 家旅宿)。回應包含諸如促銷、房價是否為可退款、是否有取消罰款和完整價格明細等房價詳情，以符合您市場的價格顯示規定。

包含多個 occupancy 參數執行個體，即可要求相同房型的多個房間。每回傳送要求時，若同一客房有多次要求預訂，則只會回傳一組該標準房價。一次最多可要求預訂 8 間客房。若需一次預訂超過 8 間客房，請聯繫您的客戶經理。我們正在努力擴展團體預訂服務，分享您的需求將有助於我們完善解決方案。

價格顯示變化

請注意，因當地法規變更，近期將實施以下調整：

加州價格標示法規(加州議會第 537 號法案) 自#起生效 2024-07-01
明尼蘇達州價格標示法規(第 111 章 --H.F.No. 3438) 自#起生效 2025-01-01

我們預期將有其他法規陸續出台，且不會針對每項法規更新此頁面，此處僅列舉兩項範例。

為何要改變？

某些司法管轄區正在實施法律，強制規範如何向旅客顯示費率。每項法律雖略有不同，但我們實施變更的方式將允許個別化合規。

Expedia Group 已對其 API 進行調整，使 API 合作夥伴能夠以多種方式顯示價格資訊。然而，最終每位使用 Expedia Group's API 的合作夥伴，均須確保其顯示 Expedia 旅遊資訊與價格的方式符合法律規範。

Expedia 已強化預訂資料表 (Rapid API )，新增欄位 property_inclusive，該欄位包含總價格，涵蓋基本房價以及整個住宿期間的所有 Expedia 費用與旅宿收取的費用及稅金。此總價的刪除線版本亦可於新欄位中查閱property_inclusive_strikethrough。除了新增的旅宿整合顯示欄位外，我們也重新調整了 API 回應中稅金與費用的拆分方式。所有由 Expedia 收取的費用均屬於每晚及住宿費用的價格明細類型 (property_fee)，而所有由 Expedia 收取的稅金則屬於每晚及住宿費用的價格明細類型 (tax_and_service_fee)。

針對 Expedia Collect 費率，billable_currency 與property_inclusive 欄位的property_inclusive_strikethrough 將以供應商合約 (Expedia Group's) 中指定的貨幣顯示，該貨幣通常為旅宿的當地貨幣。此情況與request_currency 無關，因為property_inclusive 與property_inclusive_strikethrough 欄位可能包含在旅宿以當地貨幣收取的費用。此行為有別於inclusive 與inclusive_strikethrough 欄位，其中 Expedia Collect 費率的billable_currency 欄位將與request_currency 欄位保持一致。

商店回應中的旅宿匯總金額，其分組方式可能與內容回應中呈現的金額不同。總數仍應正確匹配。

此為針對所有屬性實施的全球性變更，若對變更內容有任何進一步疑問，請聯繫您的帳戶經理。

會員點數

商務旅客預訂參與 Expedia 企業房價計畫且提供會員計畫的飯店，即可在住宿期間獲得飯店會員點數。合作夥伴可利用購物回應的設施服務節點，在擷取旅客的會員資訊前，確認並顯示會員可累積資格。

合作夥伴也可在購物 API 要求中使用 loyalty 值篩選條件，僅搜尋符合會員計畫的企業房價。

**備註：**只有在飯店已有會員計畫的情況下，企業房價才可累積會員點數。

範例：

可累積會員點數的飯店企業房價，會在搜尋回應的 amenities 節點底下出現以下參數

{
  "id": "2096",
  "name": "Eligible for hotel loyalty points"
}

佣金獎勵

作為 Rapid API 合作夥伴，您可以獲得額外的佣金獎勵，在指定的預訂和住宿日期期間為旅宿提供更高的利潤。要找出含有效佣金獎勵的旅宿，只需在 Rapid 購物 API 要求中使用 include 參數的 rooms.rates.marketing_fee_incentives 值即可。針對全部或部分所要求住宿期間的佣金獎勵費率，購物 API 回應中的 marketing_fee_incentives 物件將內含相關的其他詳細資訊，包括獎勵來源和受影響的住宿期間。然後，您可以在庫存排序和選擇過程中考慮此欄位和現有的 marketing_fee 欄位；該欄位是行銷費用的估計值，其中包括所有可用的獎勵措施。

範例

旅宿 19248 為 12 月份的住宿提供更高的利潤。針對旅宿 19248 提出購物 API 請求，住宿日期為 12 月 22 日至 1 月 5 日。在購物 API 響應的marketing_fee_incentives 物件中，您將看到針對 12 月 22 日至 12 月 31 日期間部分預訂住宿的優惠方案，該方案涵蓋 14 個住宿晚數中的 10 個晚數。

要求範例

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
&currency=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
 -H "accept: application/json, application/json"\
 -H "accept-encoding: gzip"\
 -H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
 -H "user-agent: TravelNow/3.30.112"

回應範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "marketing_fee_incentives": [
              {
                "source": "property",
                "start": "2023-12-22",
                "end": "2023-12-31"
              }
            ],
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": { ... },
                  "strikethrough": { ... },
                  "marketing_fee": {
                    "billable_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    },
                    "request_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    }
                  },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

旅遊目的

travel_purpose參數可讓您將旅客指定為商務或休閒旅客。所有 Rapid 合作夥伴皆可使用travel_purpose 參數，協助住宿設施更有效地識別並服務企業差旅旅客。

對於符合資格可選購商業稅率的合夥人，需在選購請求中使用travel_purpose=business 參數，方能在選購回應中取得商業稅率。如果要求中未提供 travel_purpose 參數，將假設其為休閒旅行，並且不會回傳企業房價。

範例

要指定旅客的旅遊目的為商務性質，只需在供應情況 API 要求中加入 24 個字元，非常簡單。

&travel_purpose=business

產品銷售

我們已對購物 API 進行以下變更，以支援merchandising 流程，並讓您無縫整合商品管理 API：

合作夥伴可使用「快速購物庫存」端點中新增的deal 篩選器，僅接收包含有效促銷活動的價格資訊。這使合作夥伴能夠靈活地建立以商品化為核心的購物請求，並確保所有返回的費率均具備deal 屬性。
Rapid 的購物可用性端點現已新增名為Campaign-Id 的請求標頭，供您標示當前發起的購物可用性 API 呼叫並非常規操作，而是源於您的商品促銷活動 (換言之，此標頭將表明當旅客因促銷活動進入購物體驗時，系統發起了購物可用性 API 請求)。我們僅接受每次購物 API 呼叫中傳入一個活動 ID。

刪除線價格

strikethrough 欄位提供適用任何飯店資助折扣之前的不含稅總價。此欄位應在美國等地區使用，這些地區通常在搜尋結果中顯示不含稅金和其他費用的基本價格。
inclusive_strikethrough 欄位顯示折扣前的總價，包括稅金和其他費用。此欄位旨在讓您更清楚地顯示提供全包價格 (即基本價格、稅金和其他費用) 的區域中適用的折扣。該欄位回傳以計費貨幣和要求貨幣表示的值。

範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": {
                    "billable_currency": {
                      "value": "726.63",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "549.60",
                      "currency": "USD"
                    }
                  },
                  "strikethrough": {
                    "billable_currency": {
                      "value": "650.00",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "491.64",
                      "currency": "USD"
                    }
                  },
                  "marketing_fee": { ... },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

促銷及折扣價格顯示

顯示根據促銷活動提供的折扣優惠金額，或是供應情況與價格檢查 API 所提供的原價與優惠價比較金額時，特定銷售點會要求提供標準房價的詳細資訊 (也就是用來計算折扣的價格基礎)。有關用詞使用規定，請參閱下方說明。

**歐盟：**請提供標準房價的清楚詳細資訊 (例如：「此為根據您的搜尋，旅宿所提供的標準房價」)。

**義大利：**請使用以下文字敘述：「Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date.」

退款選項

「可退款選項」欄位 (current_refundability) 讓合作夥伴能完整呈現所有退款選項，為旅客提供費率透明度與更高的彈性選擇。

三個選項如下：

refundable
non_refundable
partially_refundable

部分可退還的意思是什麼？

部分可退費指的是以下情況的費率：

的取消罰金高於 0 但低於預訂總金額。

及／或

住宿期間內包含 non-refundable 個日期區間。

相較於僅使用可退還的布林標記，運用 current_refundability 欄位有何優勢？

refundable布林標誌用於標示費率是否可全額退款，但對於部分退款費率，其會返回false 結果，此情況易使旅客產生誤解。「current_refundability」欄位提供更細緻的選項，能更精確地呈現費率的退費可能性資訊。

合作夥伴如何在商店回應中接收「 current_refundability 」欄位？

合作夥伴需在商店請求中，於current_refundability 參數下請求include 欄位。

範例

"property_id": "23060",
  "status": "available".
  "rates": [
    {
      "id": "201392692",
      "status": "available",
      ...
      ...
      ...
      ...
      "current_refundability": partially_refundable,
      "cancel_penalties":[
        {
          "start": "2024-10-08T23:59:00.000+02:00",
          "end": "2024-10-09T23:59:00.000+02:00",
          "nights":"1",
          "currency": "EUR"
        }
      ]
    }
  ]

無法提供的原因

unavailable_reason 功能可讓您查詢旅宿在特定住宿條件下 (住宿日期和入住人數) 完全無法提供入住的原因，並提供可採取的行動資訊。購物時，必須包含可選的要求參數 include=unavailable_reason，才能在回應中接收此資訊。然而，並非所有無法提供的旅宿都有不可預訂的可訴理由。這些旅宿不會在回應中回傳。

「購物」回應可能包括可提供和無法提供的旅宿混合。無法提供的旅宿將包括 property_id、score 和 unavailable_reason 部分，其中包含 code 和對該旅宿無法提供的簡短說明 (以英文提供)，以及 data 以獲得可在要求中調整的其他資訊來提供旅宿/客房/房價計畫。例如，如果 unavailable_reason code 為 adults_exceed_threshold，則 data 中的 2 表示該客房/房價允許的最大人數為 2 名成人，任何大於 2 的入住人數都會回傳錯誤。

**注意：**旅宿可以套用多個限制，但只會回傳一個 unavailable_reason。

範例

[
  {
    "property_id": "824739",
    "score": 12345,
    "unavailable_reason": {
      "code": "adults_exceed_threshold",
      "data": "2"
    }
  }
]

請參閱獲取完整代碼清單。

設施服務篩選條件

或者，您可以使用 amenity_category 要求參數以及一項或多項特定設施服務來篩選在 Rapid 購物回應中回傳的旅宿。

請參閱此處「內容參考清單」所列的「設施服務類別」一節，了解可用於篩選回應的設施服務清單。

範例

單一設施服務篩選條件：

&amenity_category=free_breakfast

多項設施服務篩選條件：

&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino

速率限制

我們對合作夥採取速率限制，以實現流量最佳化。這些速率限制確保我們能夠為合作夥伴提供穩定且不間斷的服務，同時保證 Expedia Group 系統的使用效率。對於商店流量，決定負載的重要因素是每個要求中搜尋的旅宿數量、客房數量和住宿天數。

進一步了解速率限制

價格檢查

確認「購物」回應傳回的價格。使用此 API 驗證先前選取的價格在預訂前仍然有效。若價格相符，則回應會傳回連結以要求預訂。若價格已變更，則回應會傳回新價格詳細資訊以及新價格的預訂連結。若房價不再適用，則回應會傳回新的購物要求連結以重新搜尋其他房價。

在PriceCheck 網站上顯示的totals.property_fees 與fees 帳單金額，相較於先前商店回應可能存在約 0.1% 的微小差異 (每客房 × 人 × 夜)，此差異可能包含調整為零的金額。當「request_currency」與「billable_currency」在 Expedia 代收費率中出現差異時，便會產生旅宿應繳費用的落差。此差異不會影響 API 功能。

保留和復原

部分庫存不適用保留與恢復功能。採用暫停與恢復功能的合作夥伴，可透過採用購物指標的 non-holdable 費率來取得這些遞增費率。更多詳情請參閱此處。

付款選項

返回接受的付款選項，其中 Expedia 將直接向終端旅客收取費用 (EPS MOR)。使用此 API 啟動付款頁面，並顯示有效的付款方式，確保順利進行預訂。

重要注意事項

language 僅使用兩位數的語言與國家/地區代碼連字號配對。整合任何代碼前，請檢查我們的支援語言。
此兩位數 country 代碼會設定旅客的銷售點，但不會影響已本地化的內容。
不會傳回任何靜態資料 (名稱、星級評等、地理資訊等等)。僅提供供應情況與房價相關資料。
記號化連結會在短時間內到期。若記號傳回 HTTP 503 錯誤，表示連結可能已到期。透過更新的「購物」回應取得新價格檢查或訂金連結，然後再試一次。請勿儲存連結值供長期重覆使用。
Rapid API 允許旅宿隨時更新其內容。我們要求您致力向旅客提供最新的資訊。「購物 API」提供可預訂的房型和房價最新資訊。若要取得此回應未傳回的額外旅宿層級、客房層級和房價等級資訊，請使用我們的「旅宿內容 API」。
API 提供的價格僅限一間客房，若要預訂多個房間，需另自行計算。啟動條件也要求您的整合在預訂過程的某些特定步驟，向使用者顯示詳細價格明細。故障分析詳見此安全文件連結：。

若要針對此服務執行測試要求，請參閱我們的「測試要求」說明文件。

購物