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 请求中包含一个特定于您企业的访问令牌。使用您的 API 凭据通过 HTTP 基本身份验证机制请求此令牌。

向令牌端点添加一个 Authorization 标头，其中包含以 Base64 编码的 API 客户端 ID 和密钥字符串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}

管理您的订阅

通过 Subscription 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 交付。

要访问 Loyalty Earn 和 Itineraries 端点，您需要一个 API 客户端 ID 和密钥，您可以从您的商业联系人处获得这些信息。您需要在所有 API 请求中包含一个特定于您企业的访问令牌。使用您的 API 凭据通过 HTTP 基本身份验证机制请求此令牌。

在令牌端点中添加一个 Authorization 标头，其中包含以 Base64 编码的 API 客户端 ID 和密钥字符串。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 交付