API 設定

本節涵蓋成功整合至我們 API 的關鍵步驟。無論您想透過 Webhooks 接收推送事件，還是從我們的端點拉取資料，我們都能滿足您的需求。

推送 API：此服務專為 TAAP 及白標旅遊平台合作夥伴設計，透過推送事件將 near-real-time 的更新直接傳送至您的系統。瞭解如何設定訂閱、管理驗證以及處理重試。
拉取 API：專為白標旅遊平台合作夥伴設計，讓您能在需要時隨時請求資料。我們將向您說明如何設定 token-based 驗證機制，以實現安全存取。

請遵循以下指引，以確保整合過程順利進行，並保障資料傳輸安全。

Push-based 送貨

若您是 TAAP 或白標旅遊平台的合作夥伴，且對行程資料感興趣，這則資訊可能與您相關。推送事件將透過 Webhook 傳遞，並以HTTP POST 訊息的形式發送至您提供的 URL。

要開始接收事件，您需要訂閱某種事件類型，並驗證 Expedia 為事件發送方。

訂閱與活動

我們的訂閱 API 允許您建立並管理欲透過我們的 push-based 傳遞服務接收的事件。您目前可建立並管理行程更新事件的訂閱服務，我們將隨功能上線持續新增更多訂閱項目。

您需要一個 API 客戶端 ID 和密鑰，您的商業聯絡人可提供這些資訊。

存取訂閱 API

您將在所有 API 請求中包含專屬您企業的存取權杖。請透過 HTTP 基本驗證機制，使用您的 API 憑證請求此驗證碼。

在令牌端點中添加一個包含 API 客戶端 ID 和密鑰的 Base64 編碼字串的授權標頭https://analytics.ean.com/*/v1/oauth/token。請將網址中的* 替換為template 或taap，具體取決於您的合作夥伴關係。
代幣端點將返回一個存取代幣，您可將其用於後續的 API 請求。如需更多詳細資訊，請參閱訂閱服務 API 說明文件：。
在未來的 API 端點請求中包含存取憑證值。

初始授權標頭範例

Authorization: Basic base64.b64encode({client-id}:{client-secret})

代幣請求範例

securitySchemes:
  oauth:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://analytics.ean.com/taap/v1/oauth/token

經認證的授權標頭範例

Authorization: Bearer {access-token}

管理您的訂閱

在您透過訂閱 API 完成驗證後，即可管理您的訂閱項目，包括列出現有訂閱清單、建立新訂閱，以及刪除不再適用的訂閱項目。

建立訂閱

建立訂閱時，您需要指定：

您希望接收事件的終端點網址。
您欲訂閱的事件類型，包含合作夥伴關係的識別碼：taap.itinerary.change 或template.itinerary.change。

注意：雖然您可以建立多個訂閱，但重複的訂閱將導致事件交付重複。為避免此情況，請在建立新訂閱前列出現有訂閱項目。

建立訂閱時，您將收到一組獨特的密鑰，用於驗證事件傳遞中包含的 HMAC (hash-based 訊息驗證碼)。

重要事項

當您收到私密金鑰時，請務必將其儲存於安全檔案中——基於安全考量，該金鑰將不會再次顯示。

若要列出或刪除訂閱項目，請分別使用HTTP GET /subscriptions 或HTTP DELETE /subscriptions/{subscription_id} 端點。您必須使用有效的憑證。

如需更多詳細資訊，請參閱訂閱 API 說明文件：。

驗證 Expedia 為發件者

我們將向您提供的終端點發送推送事件，每個事件的授權標頭中都包含 HMAC 簽名。您應使用我們提供的共享密鑰驗證此簽名，以確保資料傳輸的安全性與可信度。

授權標頭範例

"authorization": "MAC ts='1731524372777',nonce='f88e57ed-aaf5-4edd-8e58-9105817fb4cb',bodyhash='8YLHy71r5dx3PQjdcOkRuVYXaakjhbJSROEnlreQEIA=',mac='bDxvx41INtDxtkbZwTmAMADZGiFl6/xyXC1lE5ixPuY='"

步驟 1：設定驗證

將這些 HMAC 設定新增至您的推送 API 端點：

hmac.validator.sharedSecretKey={mySecretKey}
hmac.validator.endpoint=https:{//example.com}
hmac.validator.methodType=POST

步驟 2：新增驗證模組

在終端點中加入此公開類別程式碼以驗證 HMAC 簽名：

@Component
public class HmacValidator {
    private static final String HMAC_SHA256 = "HmacSHA256";
    private static final String DEFAULT_PORT = "443";
    private final String sharedSecretKey;
    private final String endpoint;
    private final String methodType;

    // Constructor for initialization
    public HmacValidator(@Value("${hmac.validator.sharedSecretKey}") String sharedSecretKey,
                         @Value("${hmac.validator.endpoint}") String endpoint,
                         @Value("${hmac.validator.methodType:POST}") String methodType) {
        this.sharedSecretKey = sharedSecretKey;
        this.endpoint = endpoint;
        this.methodType = methodType; // Default to POST if not provided
    }

    public boolean validate(String signature) {
        //Validation logic here
    }
}

步驟 3：實作驗證邏輯

簽名驗證的邏輯應遵循以下步驟：

解析授權標頭以提取元件。
使用提取的元件與sharedSecretKey 生成 HMAC 簽名。
將生成的簽名與授權標頭中的簽名進行比對。

程式碼範例

// Validate the signature
    public boolean validate(String signature) {
        Map<String, String> components = parseSignature(signature);
        if (components == null || components.isEmpty()) {
            return false; // Invalid format or empty signature
        }

        String generatedHmacSignature = generateHmacSignature(components);
        System.out.println("Generated HMAC Signature: " + generatedHmacSignature);
        System.out.println("Received HMAC Signature: " + components.get("mac"));
        return generatedHmacSignature.equals(components.get("mac"));
    }

    // Parse the signature into its components
    private Map<String, String> parseSignature(String signature) {
        // Define the pattern for each key-value pair in the format "key='value'"
        Pattern pattern = Pattern.compile("([a-zA-Z]+)='([^']*)'");
        Matcher matcher = pattern.matcher(signature);

        // Store results in a map
        Map<String, String> components = new HashMap<>();

        // Extract each key-value pair
        while (matcher.find()) {
            components.put(matcher.group(1), matcher.group(2));
        }
        return components;
    }

    // Generate the HMAC signature using components
    public String generateHmacSignature(Map<String, String> components) {
        try {
            URL url = new URL(endpoint);
            String signature = String.format("%s/n%s/n%s/n%s/n%s/n%s/n%s/n",
                    components.get("ts"),
                    components.get("nonce"),
                    methodType.toUpperCase(),
                    url.getPath(),
                    url.getHost(),
                    url.getPort() == -1 ? DEFAULT_PORT : String.valueOf(url.getPort()),
                    components.get("bodyhash"));

            return calculateHMAC(signature);
        } catch (Exception e) {
            throw new RuntimeException("Failed to generate HMAC signature", e);
        }
    }

    // Calculate the HMAC from the signature string
    private String calculateHMAC(String signature) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(sharedSecretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
            mac.init(secretKeySpec);
            byte[] hmacBytes = mac.doFinal(signature.getBytes(StandardCharsets.UTF_8));
            return bytesToBase64(hmacBytes);
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC", e);
        }
    }

    // Convert byte array to Base64 string
    private String bytesToBase64(byte[] bytes) {
        return Base64.getEncoder().encodeToString(bytes);
    }
}

重新嘗試事件失敗

若事件失敗，系統將採用指數退避模式在 7 天內進行重試：首次間隔 5 分鐘，次次間隔 60 分鐘，此後每 12 小時重試一次。我們將重新嘗試因以下原因導致的任何失敗：

非 200 的 HTTP 狀態碼
暫停
來自您終端點的例外狀況

訂閱服務 API 詳情

如需訂閱 API 的更多詳細資訊，請下載 OpenAPI 規格說明文件。

Pull-based 送貨

若您擁有白標旅遊平台網站，可依據所使用的 API，為行程規劃與忠誠度積分數據實作 pull-based 傳輸功能。

要存取「忠誠度累積」與「行程」端點，您需要取得 API 客戶端 ID 與密鑰，可向您的商業聯絡窗口索取。您將在所有 API 請求中包含專屬您企業的存取權杖。請透過 HTTP 基本驗證機制，使用您的 API 憑證請求此驗證碼。

在令牌端點https://analytics.ean.com/template/v1/oauth/token 添加一個包含 API 客戶端 ID 和密鑰的 Base64 編碼字串的授權標頭。
代幣端點將返回一個存取代幣，您可將其用於後續的 API 請求。更多詳細資訊，請參閱 OpenAPI 規格。
在未來的 API 端點請求中包含存取憑證值。

初始授權標頭範例

Authorization: Basic base64.b64encode({client-id}:{client-secret})

代幣請求範例

securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://analytics.ean.com/template/v1/oauth/token

經認證的授權標頭範例

Authorization: Bearer {token}

收到您的代幣後，即可開始對任何「忠誠度賺取」或「行程」端點發送請求。

重要事項

為確保我們能為所有合作夥伴提供穩定且可維護的服務，我們對所有 API 呼叫皆實施速率限制。我們的系統會監控異常的 API 流量，並自動採取保護措施。在您修改 API 呼叫或進行涉及 API 存取的效能測試前，請務必與您的 Expedia 商業聯絡人審核相關計畫。

在請求服務時，您需要指定您的 API 版本。請使用我們可下載的 OpenAPI 規格文件頂端所載的servers.url 值。它將始終與您正在測試的 API 服務的版本號相對應。

網址應遵循以下結構：

https://analytics.ean.com/[product]/[API version]/[path]

您可透過替換路徑在端點間切換，但務必保留 OpenAPI 規格中規定的通訊協定、網域名稱、產品及 API 版本號。

終端點範例

https://analytics.ean.com/template/v1/loyalty/earn/last_update
https://analytics.ean.com/template/v1/itineraries

要探索資料範圍與 API 設定，請參閱 API 傳遞的架構：
行程 API 交付
 忠誠度賺取 API 配送