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