Rapid Activities API 概覽
透過 Rapid Activities API，讓旅客能輕鬆預訂各項活動與體驗
搶先體驗版
本文件屬於僅限特定合作夥伴參與的搶先體驗預覽計畫。試點計畫將於 2026 年第二季啟動，並於 2027 年全面推出。
如果您有興趣成為試用或 Beta 合作夥伴，請聯絡您的客戶經理。
Rapid Activities API 旨在協助您透過易於整合的 end-to-end 購物與預訂流程，向旅客展示各項活動。這不僅能為旅客提供更全面的體驗，同時也能 為您開拓新的收入來源。
關鍵概念
- 活動： 一場可預約的活動 (您展示與銷售的內容)。
- 活動群組： 一組類似的活動。
- 體驗： 一個可能包含多項活動的概念性／行銷封裝。
- 票券： 活動的票種 (成人／兒童／嬰兒等)。
- 行程： 包含一項活動及一張或多張門票的預訂 (活動預約)。
- 分類 ： High-level 將體驗與活動依主題進行分類的群組 (例如：城市導覽、博物館或戶外活動)。
- 屬性： 描述性標籤，用於呈現某項體驗或活動的特定特徵 (例如：輪椅無障礙、適合家庭、導覽行程或免排隊)。
端到端整合流程
透過此 API 預訂活動的流程大致如下。
步驟 1：查看庫存
了解在各旅遊目的地可銷售的項目，並依目的地建立一套結構化的活動目錄，以便隨時進行商品化。
- 請使用區域映射端點，將中的地理位置 API 區域 映射至底層清單 (體驗、活動及活動群組)。注意：在本次版本中，Activities API 僅支援 ``region_ID
- 擷取多種語言的豐富活動內容 (標題、描述、圖片、地點及分類)。
- 匯整各項活動的旅客評分與評論，協助旅客比較不同選項，並建立對該體驗的信任。
- 填充搜尋結果、活動詳情頁面及篩選條件 (例如：適合家庭或步行導覽)。
步驟 2：查詢空房狀況與價格
了解各項活動的開放時間及價格。善用可預約的日期/時段、票券選項及價格區間，為購物旅程注入動能。
- 如需了解具體活動及日期，請依票種查詢空位狀況與價格。
- 在購物體驗中顯示行事曆 (可預約/不可預約的日期)、時段以及起始價格。
- 單次呼叫中支援多項活動。
步驟 3：Pre-booking 價格比對
在付款前，請確認最終可預訂價格並取得所需預訂欄位清單。收到經確認的報價及預訂代碼，內容均依據最新的庫存狀況與政策而定。
- 即時驗證特定選項 (活動、日期、時間及票券)。
- 查看最終價格、稅金／費用及庫存狀況 (包括價格變動或售罄資訊)。
- 取得有關預訂必填欄位 (例如乘客資料或 pick-up 類型) 的詳細資訊，以及用於預訂的安全憑證。
步驟 4：建立預訂
將已確認的選項轉為預訂。您將收到一份已確認的行程單 (預訂)，可於您的系統中檢視及管理。
- 請將購物流程中的預訂代號作為查詢參數傳送，並將 Payments API 中的
payment_token包含在請求正文中，同時附上旅客詳細資料 ( 主要旅客及附加旅客)。 - 請輸入您的聯盟夥伴代碼，以便日後核對及搜尋訂單。
- 您將收到行程編號及用於查詢預訂詳情的連結。
第 5 步：管理預約
支援客戶與客服專員的預訂後工作流程。使用完整的預訂後管理工具組，以查看、取消現有預訂並提供兌換券。
- 透過行程編號或您的合作夥伴參考編號查詢預訂詳情。
- 在允許的情況下取消預訂，並將處理後的狀態顯示給客戶。
- 請為客戶調取活動當日出示的憑證文件。
測試錯誤回應
若要針對特定的 Rapid Activities API 方法發送測試請求，請在您的購物或預訂請求中加入一個名為 ``test 的額外 HTTP 標頭，並使用下表中的適當值。若未傳送測試標頭，或傳送了無效的測試標頭，該請求將會被視為正式請求進行處 理。
注意： 使用測試標頭會導致系統返回靜態回應訊息，因此所返回的速率與內容可能與正在測試的活動無關。
購物與內容 API
| 測試標題值 | HTTP 代碼與回應 | 狀態 |
|---|---|---|
| 標準 | 200 OK (標準成功回應) | 成功 |
invalid_input | 400 錯誤請求 (輸入無效) | 錯誤 |
bad_link | 400 錯誤請求 (連結錯誤) | 錯誤 |
internal_server_error | 500 內部伺服器錯誤 (未知錯誤) | 錯誤 |
service_unavailable | 503 服務無法使用 | 錯誤 |
預訂 API
| 測試標題值 | HTTP 代碼與回應 | 狀態 |
|---|---|---|
| 標準 | 200 OK (標準成功回應) | 成功 |
invalid_input | 400 錯誤請求 (輸入無效) | 錯誤 |
bad_link | 400 錯誤請求 (連結錯誤) | 錯誤 |
price_mismatch | 409 衝突 (價格不符) | 錯誤 |
sold_out | 409 衝突 (已售罄) | 錯誤 |
internal_server_error | 500 內部伺服器錯誤 (未知錯誤) | 錯誤 |
service_unavailable | 503 服務無法使用 | 錯誤 |
按使用案例劃分的端點摘要
| 用例 | 方法與路徑 | 必填查詢參數 / 備註 |
|---|---|---|
| 地區體驗 | GET /regions/{region_id}/experiences | language |
| 地區活動團體 | GET /regions/{region_id}/activity-groups | language |
| 地區活動 | GET /regions/{region_id}/activities | language |
| 體驗內容 | GET /experiences/content | experience_id[]、language |
| 活動群組內容 | GET /experiences/activity-groups/content | language、activity_group_id[] |
| 活動內容 | GET /experiences/activities/content | activity_id[]、language |
| 活動開放時間 | GET /experiences/activities/{activity_id}/operating-hours | start_date,end_date (≤ 90 天)，language |
| 經驗類別 | GET /experiences/categories | language、pagination_size |
| 經驗屬性 | GET /experiences/attributes | language、pagination_size |
| 活動類別 | GET /experiences/activities/categories | language、pagination_size |
| 活動屬性 | GET /experiences/activities/attributes | language、pagination_size |
| 旅客評語 | GET /experiences/activities/{activity_id}/guest-reviews | limit、sort |
| 供貨狀況與價格 | GET /experiences/activities/availability | activity_id[],start_date,end_date (≤14 歲),currency,language |
| 行事曆供應情況 | GET /experiences/activities/calendars/availability | activity_id[],start_date,end_date |
| 價格檢查 | GET /experiences/activities/{activity_id}/price-check | token (來自購物 API 呼叫) ， tickets |
| 建立預訂 | POST /itineraries/activity | 查詢： token（來自購物 API 呼叫）， 正文： CreateItineraryRequest、affiliate_reference_id、payment_token、primary_traveler |
| 依行程編號查詢 | GET /itineraries/{itinerary_id}/activity | — |
| 透過聯盟夥伴代碼檢索 | GET /itineraries/activity | affiliate_reference_id |
| 取消預訂 | DELETE /itineraries/{itinerary_id}/activity | 204(預訂已成功取消)，202 (狀態未知) |
| 領取優惠券 | GET /itineraries/{itinerary_id}/activity/voucher | 此連結可讓您領取已預訂活動的憑證 |
注意： 若參數後面跟有[]，表示該參數可在 comma-separated 陣列中擁有多個值。
API 詳細資料
請瀏覽本頁面的 activity-related 端點定義，然後使用 Postman 等測試軟體，比較範例與架構定義與實際輸出結果的差異。當此 API 通過試行階段後，其端點也將納入我們的 API Explorer 中。