建構請求網址
請求網址——即從附加模組返回結果的網址——由網域名稱、終端點、請求參數及簽名參數組成。此範例顯示一筆已確認的洛杉磯國際機場 (LAX) 航班，行程為兩位成人於 2023 年 1 月 2 日出發，2023 年 1 月 12 日返回，該航班於 2022 年 11 月 12 日預訂完成。
//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundEndDateTime=2023-01-02T12%3A55%3A00%2B08%3A00&returnStartDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&destinationTLA=LAX&numOfAdults=2&locale=en_US¤cyCode=USD&bookingDateTime=2022-11-12T12%3A32%3A15%2B08%3A00&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI
建構請求參數
一般而言，請求參數包含預訂行程的相關細節，例如目的地以及旅程的起始與結束日期。此資訊用於為附加模組生成建議。某些參數在請求中屬可選性質，但部分參數卻是返回結果的必要條件。
重要事項
為確保安全性，請確認所有參數值皆為percent-encoded UTF-8 編碼格式。
可用請求參數
| 參數 | 說明 | 範例值 | 必填 |
|---|---|---|---|
partnerId | 由 Expedia 提供的字串值，用於在請求參數中識別您的組織 | partnername_hotel_conf_overlay | 是 |
bookingStatus | 字串值，用於指定預約狀態，該狀態決定是否可套用附加費率；若預約狀態為待處理或失敗，則不會套用任何附加費率。 | 已確認 | 是 |
bookingDateTime | 指定預約日期的字串值；包含日期、時間及時區，格式為ISO 8601 格式 | 2024-08-29T05:54:02 編碼值： 2024-08-29T05%3A54%3A02 | 是 |
outboundEndDateTime | 指定抵達目的地的字串值；包含日期、時間及時區，格式為 ISO 8601 標準 | 2024-08-29T05:54:02 編碼值： 2024-08-29T05%3A54%3A02 | 是 |
returnStartDateTime | 指定出發地與目的地之間距離的字串值；包含日期、時間及時區，格式為 ISO 8601 標準註：若未指定，行程預設長度為 7 天 | 2024-08-29T05:54:02 編碼值： 2024-08-29T05%3A54%3A02 | — |
locale | 由 Expedia 提供的 5 位字元字串，用以標示預訂所使用的語言。查看完整的地區設定詳情請參閱此處： | en_US | 是 |
currencyCode | 由 Expedia 提供的字串，用以標示預訂所使用的貨幣 | USD | 是 |
destinationTLA | 3 個字元的字串，表示國際航空運輸協會 (IATA) 目的地機場代碼 注意：請求網址必須包含此參數 (適用於包含航班的預訂) 或 latitude 及longitude（若未包含航班）。 | LAX | 條件式要求 |
latitude 以及 longitude | 浮點數值，最多可達 12 位小數，用於指定旅程目的地的座標注意：請求網址必須包含此參數 (若未包含航班) 或destinationTLA（適用於包含航班的預訂） | 緯度=40.7141667 經度=-74.0063889 | 條件式要求 |
signature | 基於我們提供的密鑰所產生的 27 位元組英數字串值詳見建構請求網址 獲取更多資訊 | BcND1F7KElTyGtyUHeXHd2JJLFs | 是 |
numOfAdults | 指定預訂中的成人人數的整數；最低為 1 | 2 | — |
numOfChildren | 指定保留區內兒童數量的整數 | 3 | — |
childAges | Comma-delimited 整數陣列，用於指定保留地內所有兒童的年齡；僅在傳遞numOfChildren 參數時才需提供 | 5,4,2 | 是的，如果傳遞了numOfChildren |
我們列舉了若干情境，以協助您理解簡單與較複雜行程的相關數值。
建立請求網址
所有請求網址皆包含網域名稱與終端點，其後接續請求參數，並以使用密鑰所產生的簽名作為結尾。
私密金鑰
私密金鑰是由英數字元組成的字串，由 Expedia 安全共享，用於生成驗證交易的簽名。它將長達 36 個字元，並與#相關聯 partnerId.
注意
請將您的私鑰存放於安全位置，並僅用於生成簽名。請勿在建立網址時將密鑰作為參數傳遞。
網域、終端點與請求參數
您的請求網址以網域名稱開頭。我們建議您保留用於請求網址的 Expedia 網域：protocol-agnostic: 及//xsell.expedia.com/。URL 的下一部分是請求字串，包含 case-sensitive 端點/xsell-pwa.js? 以及請求參數。請注意，請求參數應為 UTF-8 percent-encoded.
步驟 1：構建請求字串
請求字串包含端點和請求參數 (但不包含網域)。它應該看起來像這樣。
/xsell-pwa.js?partnerId=partner123&outboundEndDateTime=2023-01-02T12%3A55%3A00%2B08%3A00&returnStartDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&destinationTLA=LAX&numOfAdults=2&locale=en_US¤cyCode=USD&bookingDateTime=2022-11-12T12%3A32%3A15%2B08%3A00&bookingStatus=confirmed
步驟二：簽署申請書
從步驟 1 獲得的字串 (包含前導的/) 應使用 的 hash-based 訊息驗證演算法（HMAC-SHA1）進行簽署，並採用 Expedia 共享的密鑰。在大多數加密函式庫中，產生的簽名將以二進位格式呈現。
此加密雜湊函數在 RFC 2104 標準 () 中定義，並為多種電腦語言與框架提供了多種實作版本。可用的實作包括：
步驟 3：對生成的簽名進行編碼
使用修改過的Base64 編碼 () 對二進位簽名進行編碼，該編碼會將 Base64 輸出的+ 與/ 字元分別替換為-（連字號）和_（底線），以生成 URL 保險箱 (更多資訊請參閱RFC 4648)。它應該看起來類似這樣：
bj01fgT85mUiRmzxxSufSmlGpiI還需特別注意的是，若存在填充字元 (=)，應從 Base64 編碼字串中予以移除。
步驟 4：建立最終請求網址
將步驟 3 的簽名附加至步驟 1 的字串，作為signature 的參數。簽名應始終作為最終請求網址的最後一個參數。
//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundEndDateTime=2023-01-02T12%3A55%3A00%2B08%3A00&returnStartDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&destinationTLA=LAX&numOfAdults=2&locale=en_US¤cyCode=USD&bookingDateTime=2022-11-12T12%3A32%3A15%2B08%3A00&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI
在生成的字串前加上協定 (// 或http:// 或https://) 及網域名稱 (針對 protocol-agnostic 的網址，我們建議使用//xsell.expedia.com)。
//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundStartDateTime=2024-10-22T11%3A55%3A00%2B08%3A00&outboundEndDateTime=2024-10-22T13%3A55%3A00%2B08%3A00&returnStartDateTime=2024-10-30T20%3A30%3A00%2B08%3A00&returnEndDateTime=2024-10-30T22%3A30%3A00%2B08%3A00&destinationTLA=LAX&numOfAdults=2&locale=en_US¤cyCode=USD&bookingDateTime=2024-04-12T12%3A32%3A15%2B08%3A00&bookingId=123ABC&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI
步驟 5：加入 JavaScript 程式碼
您將使用最終請求網址作為模組應顯示頁面上的 JavaScript src 屬性。例如：
<<script src="//xsell.expedia.com/xsell-pwa.js?partnerId=partner123&outboundEndDateTime=2023-01-02T12%3A55%3A00%2B08%3A00&returnStartDateTime=2023-01-12T22%3A30%3A00%2B08%3A00&destinationTLA=LAX&numOfAdults=2&locale=en_US¤cyCode=USD&bookingDateTime=2022-11-12T12%3A32%3A15%2B08%3A00&bookingStatus=confirmed&signature=bj01fgT85mUiRmzxxSufSmlGpiI"></script>>
一旦您創建了請求網址，即可將其整合至您的頁面程式碼中。