行程的 API 傳輸

透過「行程」功能，您可以顯示客戶的預訂資訊，並協助他們尋找 booking-related 的產品或服務，例如旅遊行程或體驗活動。您也可以利用這些數據來分析預訂趨勢，並為相關人士製作報告。

配送選項

您的行程資料 API 傳輸可採用推送或拉取機制。

推播機制

推播服務會在行程有更新時即時發送通知。核心預訂欄位會在交易完成後數分鐘內提供，而附加及擴充欄位則會在 2 至 4 小時內跟進。此選項可讓您：

在您的網站上顯示客戶的預訂資訊，或 App
為旅客提供更多可供購買的旅遊相關產品與服務

推送事件將透過 Webhook 傳送至您提供的 URL，格式為HTTP POST 訊息。這些訊息的傳送順序可能不固定，因此請參閱creation_date 和update_date_time 中的元素來確定順序。

有關如何採用此傳送選項的詳細資訊，請參閱API 設定。

處理推送事件

由於行程資料是隨取得而即時傳送的，您可能會收到同一行程的多個事件——首先是包含核心欄位的初始事件，隨後隨著輔助資料的補充或行程的更新，會陸續收到後續事件。請參閱中的「可用欄位」頁面 ()，以查看哪些欄位會即時更新，哪些則會在 2 至 4 小時內更新。

應做：

每個行程表中預期會包含多個活動：請使用itinerary_id 來關聯活動，並始終以具有最新update_date_time 的活動為準
選擇更新處理方式：當您收到現有行程的新事件時，您可以選擇以最新資料覆寫先前記錄，或將每個事件追加至末端以保留變更歷史紀錄
妥善處理缺失欄位：早期事件中可能缺少輔助欄位；處理前請先檢查欄位是否存在

請勿：

假設第一個事件包含完整的有效載荷：其餘輔助欄位將在後續事件中出現
將同一行程中的多個事件視為錯誤處理：這是預期中的行為
請將 real-time 上的財務數值視為最終結果：這些數值可能會在 24 小時內進行調整

提取機制

注意

「拉取式交付」服務僅限於白標旅遊平台合作夥伴使用。

此拉取服務提供詳細的行程資料，以支援：

資料分析
將預訂記錄與 Expedia Group 上的資料進行對帳
針對推送傳送失敗的時間區間進行資料擷取
服務台調查

與推送傳輸相同，拉取傳輸的行程資料亦分為兩個層級：核心欄位 (itinerary_ID、status、gross_booking_value、checkin_date 及checkout_date) 可在預訂或更新後數分鐘內取得，而附加及擴充欄位則會在 2 至 4 小時內跟進提供。請參閱及，以查看各領域的完整細項。

此服務包含兩個HTTP GET 端點，可讓您：

使用變數 creation_date_start、creation_date_end、update_date_time_start 及 ``update_date_time_end ，建立在指定時間範圍內建立或更新的行程清單
根據其...檢索特定行程 itinerary_id

有關驗證流程的詳細資訊，請參閱API 設定。

依時間區間擷取行程資料

若要擷取特定時間區間的行程資料，請透過GET /itineraries 和update_date_time_start 作為查詢區間，向update_date_time_end 端點發送輪詢請求。

建議做法：

請使用 update_date_time 中的欄位作為查詢視窗：請使用update_date_time_start 和update_date_time_end 作為查詢視窗，以檢索在指定期間內建立或更新的行程。若僅使用creation_date，將無法收到行程更新。
儲存您上次成功擷取的汲取時間戳記：將此值用作下一次的 update_date_time_start，並逐步推進擷取視窗。
重複資料刪除：請在查詢中使用itinerary_id +update_date_time。隨著輔助欄位的資料日益豐富，同一行程可能會出現在多個投票視窗中。請始終以最新版《update_date_time》中的記錄為準。

若您的使用情境需要最完整且即時的行程資料，建議採用推送傳送方式。

可用欄位

下表列出我們推播和提取交付方法所提供的欄位，包括所有嵌入物件。「可用性」欄位顯示各欄位在預訂事件或更新後，通常何時可供存取：

即時：預訂或更新後數分鐘內即可取得
Near-real-time：預訂或更新後 2 至 4 小時內即可取得

以名稱開頭並緊接英文句號的欄位名稱 (例如，<variable>.<nested variable>) 可指出嵌入關係。

白牌旅遊平台

欄位名稱	定義	範例	供應情況
`itinerary_id`	行程編號或銷售點訂單參考編號。	72622069245694	即時
`status`	行程和當中個別項目的狀態。	可能的值：已確認已取消	即時
`creation_date`*	預訂的初始日期，以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-05	即時
`update_date_time`*	行程的最後更新日期與時間，以 ISO 8601 日期格式表示 (YYYY-MM-dd'T"HH:mm:ss.SSSZ)。	2023-10-21T00:00:00.000Z	即時
`online`	表示行程是透過線上預訂 (true) 還是透過旅行社預訂 (false)。以布林值表示。	true	Near-real-time
`package`	表示該行程是套裝行程的一部分，還是獨立預訂。以布林值表示。	false	Near-real-time
`payment_type`	付款時使用的付款方式。	可能的值：信用卡點數分期付款	即時
`point_of_sale_country_code`	旅客預訂所用銷售點的國家/地區代碼。以雙字母 ISO 3166-1 alpha-2 格式表示。	GB	Near-real-time
`purchaser`	預訂者的身分識別。請參閱 `purchaser` 表格以取得嵌入項目清單。
`property_booking_items`	做為行程一部分而預訂的住宿項目。請參閱 `property_booking_items` 表格以取得嵌入項目清單。
`flight_booking_items`	做為行程一部分而預訂的機票項目。請參閱 `flight_booking_items` 表格以取得嵌入項目清單。
`car_booking_items`	做為行程一部分而預訂的租車項目。請參閱 `car_booking_items` 表格以取得嵌入項目清單。
`activity_booking_items`	做為行程一部分而預訂的活動項目。請參閱 `activity_booking_items` 表格以取得嵌入項目清單。
`insurance_booking_items`	做為行程一部分而預訂的保險項目。請參閱 `insurance_booking_items` 表格以取得嵌入項目清單。
`rate`	預訂項目或整體行程的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。
`coupon`	套用至行程的優惠券 (如果適用)。請參閱 `coupon` 表格以取得嵌入項目清單。

訂購者

這些欄位會識別進行預訂的人員。

欄位名稱	定義	範例	供應情況
`purchaser.email`**	預訂者的電子郵件地址。	smith@example.com	即時
`purchaser.loyalty_id`**	會員計畫的識別碼。	12345678	Near-real-time
`purchaser.first_name`**	預訂者的名字。	珍	即時
`purchaser.last_name`**	預訂者的姓氏。	Smith	即時

property_booking_items

這些欄位會列出做為行程一部分而預訂的住宿項目。

欄位名稱	定義	範例	供應情況
`booking_item_id`	做為行程一部分而預訂的特定元素識別碼。	1400882912	即時
`status`	特定住宿元素的狀態。	可能的值：已確認已取消	即時
`checkin_date`*	相應住宿元素的入住日期。以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-01	即時
`checkout_date`*	相應住宿元素的退房日期。以 ISO 8601 日期格式表示 (YYYY-MM-DD).	2023-02-05	即時
`property.id`	Expedia Group's 飯店或度假租屋旅宿的唯一識別碼。	1400882912	Near-real-time
`property.chain_name`	旅宿隸屬的連鎖體系名稱 (如果適用)。	獨立住宿	Near-real-time
`property.brand_name`	旅宿隸屬的品牌名稱 (如果適用)。單一連鎖體系可能包含多個品牌。	Savoy Signature	Near-real-time
`property.name`	飯店或出租度假屋的名稱。	飯店 1	即時
`property.city`	旅宿所在城市的名稱。	多倫多	即時
`property.state_province_name`	旅宿所在州/省的名稱。	安大略	Near-real-time
`property.country_code`	旅宿所在國家/地區的名稱。以雙字母 ISO 3166-1 alpha-2 格式表示。	CA	即時
`property.star_rating`	旅宿星級。	3.0	Near-real-time
`room_name`	預訂編號客房的類型，由飯店或度假租賃公司所定義。	Comfort 雙人房客房 (附獨立衛浴)	Near-real-time
`adult_count`	相應預訂所包含的成人人數。	2	即時
`child_count`	相應預訂所包含的兒童人數。	0	即時
`expedia_collect`	布林值，用來表示預訂是否已在付款頁面支付 (true)，還是必須直接支付給供應商 (false)。	true	Near-real-time
`property_confirmation_id`	由飯店或度假租屋公司提供的確認編號。	1516171819	Near-real-time
`rate`	住宿預訂的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。

flight_booking_items

這些欄位會列出做為行程一部分而預訂的機票項目。

欄位名稱	定義	範例	供應情況
`booking_item_id`	做為行程一部分而預訂的特定元素識別碼。	1400882911	即時
`status`	特定機票行程的狀態。	可能的值：已確認已取消	即時
`departure_date`*	相應機票行程元素的開始日期。以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-01	即時
`arrival_date`*	相應機票行程元素的結束日期。以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-02	即時
`airline.plating_carrier_name`	開立機票的航空公司名稱。	加拿大航空	Near-real-time
`airline.plating_carrier_code`	開立機票之航空公司的國際航空運輸協會 (IATA) 代碼。	AC	即時
`carrier_pnr`	開立機票之航空公司所記錄的乘客姓名。	SMITH	Near-real-time
`trip_type`	預訂的旅行類型。	可能的值：單程來回多個目的地	Near-real-time
`fare_class`	機票艙等。	經濟艙	Near-real-time
`airport_origin_code`	出發地機場的 IATA 代碼。	LHR	即時
`airport_origin_location`	出發地機場的所在地。	倫敦，英國 (LHR-希斯洛機場)	Near-real-time
`airport_destination_code`	目的地機場的代碼。以 IATA 格式表示。	YYZ	即時
`airport_destination_location`	目的地機場的所在地。	多倫多，安大略 (YYZ-列斯特 B. 皮爾森國際機場)	Near-real-time
`ticket_number`	航班的機票號碼。	123456789	Near-real-time
`expedia_collect`	布林值，用來表示預訂是否已在付款頁面支付 (true)，還是必須直接支付給供應商 (false)。	true	Near-real-time
`segment_count`	機票的航段數量。	1	Near-real-time
`rate`	機票預訂的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。

car_booking_items

這些欄位會列出做為行程一部分而預訂的租車項目。

欄位名稱	定義	範例	供應情況
`booking_item_id`	做為行程一部分而預訂的特定元素識別碼。	1400882910	即時
`status`	特定租車行程的狀態。	可能的值：已確認已取消	即時
`pickup_date`*	租車行程元素的開始日期。以 ISO 8601 日期格式表示 (YYYY-MM-DD).	2023-02-02	即時
`return_date`*	租車行程元素的結束日期。以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-05	即時
`rental_company.name`	租車公司的名稱。	Hertz	即時
`car_type`	租車的類型。	2/4 門小型車	Near-real-time
`pickup_location`	租車的取車地點。	鹿湖，紐芬蘭與拉布拉多 (YDF-鹿湖地方機場)	即時
`pickup_country_code`	取車地點的國家/地區代碼。以雙字母 ISO 3166-1 alpha-2 格式表示。	CA	即時
`return_location`	租車的還車地點。	鹿湖，紐芬蘭與拉布拉多 (YDF-鹿湖地方機場)	即時
`return_country_code`	還車地點的國家/地區代碼。以雙字母 ISO 3166-1 alpha-2 格式表示。	CA	即時
`trip_type`	預訂的旅行類型。	可能的值：單程來回多個目的地	Near-real-time
`rental_company_confirmation_id`	租車公司提供的確認編號。	ABC1234	Near-real-time
`expedia_collect`	布林值，用來表示預訂是否已在付款頁面支付 (true)，還是必須直接支付給供應商 (false)。	false	Near-real-time
`rate`	租車預訂的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。

activity_booking_items

這些欄位會列出做為行程一部分而預訂的活動項目。

欄位名稱	定義	範例	供應情況
`booking_item_id`	做為行程一部分而預訂的特定元素識別碼。	1400882910	即時
`status`	特定活動的狀態。	可能的值：已確認已取消	即時
`activity_start_date`*	活動的開始日期。以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-03	即時
`activity_end_date`*	活動的結束日期。以 ISO 8601 日期格式表示 (YYYY-MM-DD).	2023-02-03	即時
`vendor.name`	提供活動的廠商名稱。	奧莉維亞旅遊	即時
`vendor.city`	活動廠商所在的城市。	鹿湖，紐芬蘭與拉布拉多 (YDF-鹿湖地方機場)	即時
`vendor.country_code`	活動廠商所在的城市代碼。以雙字母 ISO 3166-1 alpha-2 格式表示。	CA	即時
`offering_name`	活動名稱。	Passions of Paradise Great Barrier Reef	Near-real-time
`expedia_collect`	布林值，用來表示預訂是否已在付款頁面支付 (true)，還是必須直接支付給供應商 (false)。	true	Near-real-time
`rate`	活動預訂的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。

insurance_booking_items

這些欄位會列出做為行程一部分而預訂的保險項目。

欄位名稱	定義	範例	供應情況
`booking_item_id`	做為行程一部分而預訂的特定元素識別碼。	1400882610	即時
`status`	所選特定保險的狀態。	可能的值：已確認已取消	即時
`rate`	所選保險的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。

房價

這些欄位會列出預訂項目或整體行程的房價和價格詳情。這些包含描述預訂金額的嵌套值，並細分為預訂總額以及稅金和手續費。

欄位名稱	定義	範例	供應情況
`rate_plan_name`	用來為項目定價的房價計畫名稱。僅適用於旅宿預訂項目。	僅訂客房	Near-real-time
`rate_plan_type`	預訂使用的房價類型。僅適用於旅宿預訂項目。	經銷房價	Near-real-time
`refundable`	對應的預訂項目是否可退款 (true) 或不可退款 (false)。	true	Near-real-time
`pricing`	記錄預訂金額的項目，細分為預訂總額、稅金及手續費。
`pricing.gross_booking_value`	用以記錄預訂金額的物件。
`pricing.gross_booking_value.billable_currency`	代表預訂金額的物件，其貨幣單位為付款所使用的貨幣。
`pricing.gross_booking_value.billable_currency.currency`	旅客在預訂時使用的支付貨幣。以 ISO 4217 格式表示。	GBP	即時
`pricing.gross_booking_value.billable_currency.value`	總預訂金額。	2520.80	即時
`pricing.taxes_and_fees`	預訂所含稅金和費用的價值與貨幣。
`pricing.taxes_and_fees.billable_currency`	預訂所含稅金和費用的貨幣價值 (以付款所用的貨幣表示)。
`pricing.taxes_and_fees.billable_currency.currency`	旅客在預訂時使用的支付貨幣。以 ISO 4217 格式表示。	GBP	即時
`pricing.taxes_and_fees.billable.currency.value`	預訂的總預訂金額。	491.10	即時

優惠券

欄位名稱	定義	範例	供應情況
`code`	預訂使用的優惠代碼。	ABCD	Near-real-time
`name`	優惠券名稱。	PRIME	Near-real-time
`description`	優惠券詳情。	BoGo 5%	Near-real-time
`currency`	所套用優惠券價值的貨幣。以 ISO 4217 格式表示。	GBP	Near-real-time
`value`	優惠券的貨幣價值。	126.04	Near-real-time

所有白標旅遊平台欄位的說明

日期欄位採用協調世界時 (UTC)。
** 此為個人識別資訊 (PII) 資料。請務必依照貴公司的指引正確處理此事。僅在絕對必要時才包含。

旅行社聯盟計畫 (TAAP)

欄位名稱	定義	範例	供應情況
`itinerary_id`	行程編號或銷售點訂單參考編號。	72622069245694	即時
`agency_reference_code`	旅行社於結帳時提供的客製化行程參考。	86549B_GB	即時
`status`	行程和當中個別項目的狀態。	可能的值：已確認已取消	Near-real-time
`creation_date`*	預訂的初始日期，以 ISO 8601 日期格式表示（YYYY-MM-DD).	2023-02-05	即時
`update_date_time`*	行程的最後更新日期與時間，以 ISO 8601 日期格式表示（YYYY-MM-dd'T"HH:mm:ss.SSSZ).	2023-10-21T00:00:00.000Z	即時
`online`	表示行程是透過線上預訂 (true) 還是透過旅行社預訂 (false)。以布林值表示。	true	Near-real-time
`point_of_sale_country_code`	客戶進行預訂的國家代碼。以雙字母 ISO 3166-1 alpha-2 格式表示。	GB	Near-real-time
`purchaser`	預訂者的身分識別。請參閱 `purchaser` 表格以取得嵌入項目清單。
`agency`	請提供 TAAP 網站上負責預訂的機構及人員的相關資訊。請參閱 `agency` 表格以取得嵌入項目清單。
`payment`	此行程的付款資訊。請參閱 `payment` 表格以取得嵌入項目清單。
`property_booking_items`	做為行程一部分而預訂的住宿項目。請參閱 `property_booking_items` 表格以取得嵌入項目清單。
`flight_booking_items`	做為行程一部分而預訂的機票項目。請參閱 `flight_booking_items` 表格以取得嵌入項目清單。
`car_booking_items`	做為行程一部分而預訂的租車項目。請參閱 `car_booking_items` 表格以取得嵌入項目清單。
`activity_booking_items`	做為行程一部分而預訂的活動項目。請參閱 `activity_booking_items` 表格以取得嵌入項目清單。
`rate`	預訂項目或整體行程的房價和價格詳情。請參閱 `rate` 表格以取得嵌入項目清單。
`earnings`	某筆預訂項目或整個行程的佣金明細。請參閱 `earnings` 表格以取得嵌入項目清單。

訂購者

這些欄位是用來識別即將出行的旅客。

欄位名稱	定義	範例	供應情況
`purchaser.email`**	旅客的電子郵件地址。	smith@example.com	即時
`purchaser.first_name`**	旅客的名字。	珍	即時
`purchaser.last_name`**	旅客的姓氏。	Smith	即時

代理機構

這些欄位用於識別負責預訂的 TAAP 旅行社及其業務代表。

欄位名稱	定義	範例	供應情況
`agency.name`	負責預訂的 TAAP 代理商名稱。	環球旅行	Near-real-time
`agency.id`	負責預訂的 TAAP 旅行社之追蹤編號。	WS02555	即時
`agency.agent.first_name`**	負責預訂的 TAAP 客服人員的名字。	Bob	即時
`agency.agent.last_name`**	負責預訂的 TAAP 客服人員的姓氏。	Jones	即時
`agency.agent.email`**	負責預訂的 TAAP 客服專員的電子郵件地址。	bjones@worldtravel.com	即時

付款

這些欄位包含行程的付款詳細資訊。

欄位名稱	定義	範例	供應情況
`payment_type`	付款時使用的付款方式。	可能的值：信用卡個百分點分批支付	即時
`status`	表示行程是否已付款。	可能的值：已付費未支付	Near-real-time
`deferred`	行程費用是否已延期支付 (是) 或已支付 (否)。以布林值表示。	true	Near-real-time
`payment_due_date`	付款到期日 (ISO 8601 日期格式)(YYYY-MM-DD). 僅適用於延期付款。	2023-02-05	Near-real-time
`payee`	此處標示負責支付行程費用的人員。	可能的值：代理機構客戶	Near-real-time