APIの設定

このセクションでは、APIとの統合を成功させるための重要なステップについて説明します。Webhooks経由でプッシュイベントを受信したい場合も、エンドポイントからデータをプルしたい場合も、弊社にお任せください。

プッシュAPI： TAAPやWhite Label Templateパートナーに最適なプッシュイベントは、near-real-timeのアップデートをシステムに直接配信します。サブスクリプションの設定、認証の管理、再試行の処理方法について説明します。
プルAPI：ホワイトレーベルテンプレートパートナーのために設計され、必要なときにデータを要求することができます。安全なアクセスのためのtoken-based認証の設定について説明します。

以下のガイダンスに従って、スムーズな統合と安全なデータ転送を実現してください。

Push-based配達

TAAPまたはWhite Label Templateのパートナーで、旅程データにご興味のある方は、こちらをご覧ください。プッシュイベントはWebhook経由で配信され、お客様が指定したURLにHTTP POST メッセージとして送信されます。

イベントの受信を開始するには、イベントタイプを購読し、エクスペディアを送信者として認証する必要があります。

購読とイベント

弊社のSubscriptions APIを使用すると、push-based配信サービスを通じて受信したいイベントを作成および管理できます。現在、旅程更新イベントの購読を作成および管理することができます。

APIクライアントIDとシークレットが必要です。

サブスクリプションAPIへのアクセス

すべてのAPIリクエストに、あなたのビジネスに固有のアクセストークンを含めます。HTTPベーシック認証の仕組みを使って、API認証情報を使ってこのトークンをリクエストします。

トークンのエンドポイントに、APIクライアントIDとsecretをBase64エンコードした文字列を含むAuthorizationヘッダを追加しますhttps://analytics.ean.com/*/v1/oauth/token。URLの* を、パートナーシップに応じて、template またはtaap に置き換えてください。
トークン・エンドポイントは、以降のAPIリクエストで使用するアクセストークンを返します。詳細については、Subscriptions 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} エンドポイントを使用します。有効なトークンを使用する必要があります。

詳細については、Subscriptions API詳細を参照してください。

エクスペディアを送信者として認証

私たちは、あなたが提供するエンドポイントにプッシュイベントを送信し、各イベントは認可ヘッダに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日間にわたり指数バックオフパターンを使用して再試行します。失敗した場合は再試行します：

200以外のHTTPステータスコード
タイムアウト
エンドポイントからの例外

購読APIの詳細

Subscriptions APIの詳細については、OpenAPI仕様をダウンロードしてください。

Pull-based配達

White Label Templateサイトをお持ちの場合、使用しているAPIに応じて、旅程やロイヤルティEarnデータのpull-based配信を実装できます。

ロイヤルティのEarnとItinerariesエンドポイントにアクセスするには、APIクライアントIDとシークレットが必要です。すべてのAPIリクエストに、あなたのビジネスに固有のアクセストークンを含めます。HTTPベーシック認証の仕組みを使って、API認証情報を使ってこのトークンをリクエストします。

トークン・エンドポイントhttps://analytics.ean.com/template/v1/oauth/token に、APIクライアントIDとシークレットをBase64エンコードした文字列を含むAuthorizationヘッダーを追加します。
トークン・エンドポイントは、以降の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}

トークンを受け取ったら、ロイヤルティEarnまたはItinerariesエンドポイントに対してリクエストを開始できます。

重要

すべてのパートナーに安定した保守可能なサービスを提供するため、すべてのAPIコールにレート制限を適用しています。当社のシステムは異常な API トラフィックを監視し、システム自体を保護するためのアクションを自動的に実行します。API呼び出しに変更を加えたり、APIアクセスのパフォーマンステストを実施したりする前に、エクスペディアの営業担当者と計画を確認してください。

サービスをリクエストする際には、APIのバージョンを指定する必要があります。ダウンロード可能なOpenAPI仕様ファイルの一番上にあるservers.url。これは常に、あなたがテストしている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配信