XAP API 沙盒使用指南

簡介
什麼是「沙盒」？
申請沙盒存取權限
如何使用沙盒？
可支援的 API
- 住宿
- 機票
反應行為
- 依情境模擬的回應

簡介

為了協助開發人員更有效率地建置和測試整合功能，我們在「航班與住宿」領域下，針對一組精選的 API 提供沙盒環境。此環境透過模擬回應來模擬預期行為，協助合作夥伴在不影響實際運作系統的情況下測試 API 請求。

透過 Sandbox，您可以測試航班與住宿 API 的搜尋、空房狀況、預訂及取消功能。

注意：Sandbox 目前僅支援有限的動態行為。回應內容大多是靜態的，僅有部分元素會根據請求參數而有所變化。

什麼是「沙盒」？

The Sandbox 是一個基於 non-production 的模擬層，透過模擬回應來模擬真實 API 的行為。其目的是為了協助開發者：

驗證 API 結構與參數需求。
測試請求／回應流程。
在與生產環境整合之前，請先了解回應格式。
在受控環境中模擬常見的錯誤情況。

所有沙盒請求均應使用以下基礎 URL 和標頭：

curl https://apim.sandbox.expedia.com \
-H 'Authorization: ••••••'

請參閱Basic-Authentication 以了解如何對您的請求進行驗證。

沙盒環境與生產環境之間的關鍵差異：

沙盒使用模擬資料，不會影響實際庫存
在沙盒環境中，某些功能可能會受到限制或僅為模擬
回應時間可能與正式版本有所不同

申請沙盒存取權限

所有沙盒端點皆可透過與生產環境相同的 API 金鑰或憑證機制公開存取。

如果您在生產環境中已具備 XAP API 的存取權限，則可使用相同的 API 金鑰和密碼來存取沙盒環境。否則，請向您的 Expedia 客戶經理申請沙盒存取權限。

如何使用沙盒

我們的 API Explorer 提供便捷的 Try-It-Out 體驗，讓您無需撰寫任何程式碼，即可直接在瀏覽器中測試 Sandbox API。

請依照以下步驟開始操作：

開啟 API Explorer
前往Sandbox Playground 頁面。
請輸入驗證憑證
請在「基本驗證」區段中輸入您的使用者名稱及密碼。
請使用您在生產環境中使用的憑證，或專門用於存取沙盒環境的憑證。
選擇 API
請從可用清單中選擇您要測試的 API。
填寫參數
請使用本 Sandbox 指引文件中提供的範例值來填入請求參數。
點擊「試試看」
提交請求後，即可在「回應」區塊中查看模擬回應。
在 Postman 中使用 cURL 範例 (可選)
您也可以複製本文件中提供的 cURL 請求，並直接在 Postman、終端機或其他 REST 客戶端等工具中執行，以便在 API Explorer 介面之外進行測試。

可支援的 API

目前以下 API 支援 Sandbox 體驗：

住宿

API 名稱	方法與終點	說明
刊登內容	GET /hotels/listings	返回模擬的搜尋結果
詳情	GET /hotels/details	返回模擬的庫存資料
預訂	POST /hotels/bookings	模擬預訂啟動流程
擷取	GET /hotels/bookings	返回一個範例預訂的模擬詳細資訊
取消	PUT /hotels/bookings	模擬預訂取消
取消詳情	GET /hotels/bookings/canceldetails	返回某筆示例預訂的模擬取消詳細資訊

機票

API 名稱	方法與終點	說明
刊登內容	GET /航班/列表	返回模擬航班的搜尋結果
詳情	GET /航班/詳情	返回所選航班優惠的模擬可用性資料
預訂	POST /flights/bookings	模擬預訂啟動流程
擷取	GET /航班/預訂	返回一個範例預訂的模擬詳細資訊

隨著我們在更多 API 上推出沙盒支援功能，此清單可能會持續擴充。

反應行為

這些模擬回應並非完全動態，亦非 data-driven. 改為：

部分特定欄位 (例如 locationKeyword, ecomHotelIds 等) 可能會影響回應內容。
其他欄位僅為示範用途而設定為占位符或硬編碼。

API 測試的模擬回應情境

住宿 API

Search-to-Book「住宿」業務類別下的 API 範例及可能的錯誤情境

無日期搜尋

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/listings?ecomHotelIds=64187346` \
 -- header 'Authorization: ••••••'

飯店識別碼搜尋

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/listings?checkIn=2025-12-01&checkOut=2025-12-05&ecomHotelIds=64187346` \
 -- header 'Authorization: ••••••'

地點關鍵字搜尋

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/listings?checkIn=2025-12-01&checkOut=2025-12-05&locationKeyword=Seattle` \ 
 -- header 'Authorization: ••••••'

**詳細資訊 - 請求中包含有效的 offerToken **

curl --request GET \
 --url `GET https://apim.sandbox.expedia.com/hotels/details/CgcxMTYzNTI5EjIKCTMyNjA1MzkyMxIJMzk5O?price=901.26&currency=USD&locale=en_US` \
 -- header 'Authorization: ••••••'

**預訂 - 請求中有效的 offerToken **

curl --request POST \
 --url `https://apim.sandbox.expedia.com/hotels/bookings/CgcxMTYzNTI5EjIKCTMyNjA1MzkyMxIJMzk5O?price=901.26&currency=USD&locale=en_US` \ 
 -- header 'Authorization: ••••••'

檢索預訂 - 請求中包含有效的行程編號

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/bookings/79018026356` \ 
 -- header 'Authorization: ••••••'

取消預訂—請求中須提供有效的行程編號

curl --request PUT \
 --url `https://apim.sandbox.expedia.com/hotels/bookings/79018026356` \ 
 -- header 'Authorization: ••••••'

預訂取消詳情—請求中包含有效的行程編號

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/bookings/canceldetails/79018026356` \ 
 -- header 'Authorization: ••••••'

上述範例僅供示範之用。offerToken 及行程編號均為虛構數值，並不代表實際預訂。

以下列出您在沙盒環境中使用 Lodging API 時可能會遇到的常見錯誤情況。

清單「請求錯誤 - 未找到結果」錯誤

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/listings?ecomHotelIds=987654321` \ 
 -- header 'Authorization: ••••••'

列表「請求錯誤」－合併搜尋錯誤

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/listings?ecomHotelIds=64187346&locationKeyword=Seattle` \
 -- header 'Authorization: ••••••'

列表「請求無效」——位置不明確錯誤

curl --request GET \
 --url `GET https://apim.sandbox.expedia.com/hotels/listings?locationKeyword=amb` \ 
 -- header 'Authorization: ••••••'

**詳細資訊：請求錯誤 - 請求中包含無效的 offerToken **

curl --request GET \
 --url `https://apim.sandbox.expedia.com/hotels/details/<some-random-token>` \ 
 -- header 'Authorization: ••••••'

預訂錯誤請求 - 請求中 offerToken 無效

curl --request POST \
 --url `https://apim.sandbox.expedia.com/hotels/bookings/<some-random-token>` \ 
 -- header 'Authorization: ••••••'

航班 API

Search-to-Book「航班」業務線下的 API 範例及可能的錯誤情境

房源列表 - 單向搜尋

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/listings?segment1.origin=LAS&segment1.destination=FLL&segment1.departureDate=2025-12-01&adult=1` \
 -- header 'Authorization: ••••••'

房源 - 往返搜尋

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/listings?segment1.origin=LAS&segment1.destination=FLL&segment1.departureDate=2025-12-01&segment2.origin=FLL&segment2.destination=LAS&segment2.departureDate=2025-12-11&adult=1` \
 -- header 'Authorization: ••••••'

**詳細資訊 - 請求中包含有效的 offerToken **

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/details/v5-sos-9cf600b5edb24066bbdc70d03a9f2cd7-70-1~8` \
 -- header 'Authorization: ••••••'

**預訂 - 請求中包含有效的 offerToken **

curl --request POST \
 --url `https://apim.sandbox.expedia.com/flights/bookings/3e156944176b4f1099c26fd5347ee0b9-0-1~2?price=97.18&currency=USD` \
 -- header 'Authorization: ••••••'

檢索預訂 - 請求中包含有效的行程編號

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/bookings/71261078088` \
 -- header 'Authorization: ••••••'

上述範例僅供示範之用。offerToken 及行程編號均為虛構數值，並不代表實際預訂。

以下列出您在沙盒環境中使用 Lodging API 時可能會遇到的常見錯誤情況。

列表「請求錯誤」——缺少區段詳細資訊

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/listings` \ 
 -- header 'Authorization: ••••••'

**詳細資訊：請求錯誤 - 請求中包含無效的 offerToken **

curl --request GET \
 --url `https://apim.sandbox.expedia.com/flights/details/<some-random-token>` \ 
 -- header 'Authorization: ••••••'

預訂 - 請求中 offerToken 無效

curl --request POST \
 --url `https://apim.sandbox.expedia.com/flights/bookings/<some-random-token>?price=97.18&currency=USD` \
 -- header 'Authorization: ••••••'