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。根據您的合作關係，將 URL 中的 *替換為 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 進行驗證後，您可以管理您的訂閱，包括列出現有訂閱、建立新訂閱以及刪除不再適用的訂閱。

建立訂閱

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

您想要接收事件的端點 URL。
您想要訂閱的活動類型，包括您的合作關係指標：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 憑證請求此令牌。

將包含 API 用戶端 ID 和金鑰的 Base64 編碼字串的授權標頭新增至令牌端點https://analytics.ean.com/template/v1/oauth/token。
令牌端點將傳回一個存取令牌，您將在後續 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 版本。使用servers.url在我們可下載的 OpenAPI 規範檔案頂部找到的值。它將始終與您正在測試的 API 服務的版本號碼相對應。

URL 應遵循以下結構：

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 交付