旅程に関するAPIの提供
「旅程」機能を使えば、お客様の予約情報を表示したり、ツアーや体験など、booking-relatedの商品やサービスをお客様が探せるようサポートしたりすることができます。また、このデータを活用して予約動向を分析したり、関係者の皆様向けのレポートを作成したりすることも可能です。
配送方法
旅程データのAPI配信に は、プッシュ方式またはプル方式のいずれかをご利用いただけます。
プッシュ方式
プッシュサービスは、旅程の更新情報が発生次第、その都度送信します。取引完了後、数分以内に主要な予約フィールドが利用可能となり、付随フィールドおよび詳細フィールドは2～4時間以内に利用可能になります。このオプションを使用すると、以下のことが可能になります：
- ウェブサイトやアプリに、お客様の予約情報を表示する
- 旅行者に、旅行中に購入できる追加の商品やサービスを提供します
プッシュイベントは、Webhookを介して、ご指定いただいたURLに、HTTP POST メッセージの形式で配信されます。これらのメッセージは順不同で届く場合がありますので、順序を特定するには、creation_date およびupdate_date_time 要素をご参照ください。
この配信オプションの導入方法の詳細については、「APIの設定」をご覧ください。
プッシュイベントの扱い
旅程データは入手可能になり次第配信されるため、同じ旅程に対して複数のイベントが届く場合があります。具体的には、基本項目を含む最初のイベントに続き、補助データが充実したり旅程が更新されたりした際に、追加のイベントが配信されることがあります。および の「利用可能なフィールド」をご覧ください。どのフィールドがリアルタイムで配信され、どのフィールドが2～4時間以内に配信されるかの詳細な内訳が記載されています。
すべきこと：
- 旅程ごとに複数のイベントが発生することが予想されます：
itinerary_idを使用してイベントを関連付け、常に最新のupdate_date_timeを基準として扱ってください - 更新の処理方法を選択してください：既存の旅程に対して新しいイベントを受け取った際、以前のレコードを最新のデータで上書きするか、各イベントを追加して変更履歴を維持するかを選択できます
- 欠落しているフィールドに適切に対処する: 初期のイベントでは補助フィールドが存在しない場合があります。処理を行う前に、フィールドが存在するかどうかを確認してください。
してはいけないこと
- 最初のイベントに完全なペイロードが含まれているものと仮定します：。付随するフィールドは、その後のイベントで続きます。
- 同じ旅程に対する複数のイベントをエラーとして扱う： これは想定された動作です
- real-timeの財務数値は確定値として扱ってください： 24時間以内に修正される可能性があります
プル方式
注意
プル配信は、ホワイトラベル旅行プラットフォームのパートナー様のみご利用いただけます。
このプルサービスは、以下の機能をサポートするための詳細な旅程データを提供します：
- データ分析
- 予約記録とExpedia Groupのデータを照合する
- プッシュ配信に失敗した時間枠のデータ取得
- ヘルプデスクの調査
プッシュ配信と同様に、プル配信においても旅程データは2段階に分けて提供されます。コアフィールド（itinerary_ID、status、gross_booking_value、checkin_date、checkout_date）は、予約または更新から数分以内に利用可能となり、付加情報および拡張フィールドはその後2～4時間以内に利用可能となります。各分野ごとの詳細な内訳については、および をご覧ください。
このサービスは、2つのHTTP GET エンドポイントで構成されており、これらを利用することで以下のことが可能になります：
creation_date_start、creation_date_end、update_date_time_start、およびupdate_date_time_end変数を使用して、指定された期間内に作成または更新された旅程の一覧を作成します。- 特定の旅程を、その
itinerary_id
認証プロセスの詳細については、APIの設定 をご覧ください。
時間枠ごとの旅程データの取得
特定の時間枠の旅程データを取得するには、クエリの時間枠として GET /itineraries` ` および update_date_time_start を指定して、update_date_time_end エンドポイントにポーリングを行ってください。
推奨されるアプローチ：
- クエリウィンドウには、update_date_timeのフィールドをご利用ください： 指定した期間内に作成または更新された旅程を取得するには、
update_date_time_startおよびupdate_date_time_endをクエリウィンドウとしてご利用ください。creation_dateのみを使用すると、旅程の更新情報を見逃してしまいます。 - 最後に正常に実行されたポーリングのタイムスタンプを保存してください： これを次の
update_date_time_startとして使用し、ウィンドウを段階的に進めてください。 - 重複排除： クエリでは、
itinerary_idとupdate_date_timeを組み合わせてご使用ください。補助フィールドの情報が充実するにつれて、同じ旅程が複数の投票ウィンドウに表示される場合があります。常に、最新のupdate_date_timeのレコードを正式なものとして扱ってください。
ご利用の用途において、最も完全かつ最新の旅程データが必要な場合は、プッシュ配信をお勧めします。
利用可能なフィールド
以下の表に、プッシュとプルの配信方法を通じて利用可能なフィールド (ネストされたオブジェクトを含む) の一覧を示します。「利用可能時期」の列には、予約の発生または更新後、各フィールドが通常いつから利用可能になるかが示されています：
- リアルタイムの：予約や更新から数分以内に利用可能
- Near-real-time: 予約または更新から2～4時間以内に利用可能になります
名前の後にピリオドが続くフィールド名 (例 : <変数>.<ネストされた変数>) はネスト関係を示しています。
ホワイトレーベル トラベル プラットフォーム
| フィールド名 | 定義 | 例 | 在庫 |
|---|---|---|---|
itinerary_id | 旅程番号または POS 注文参照番号。 | 72622069245694 | リアルタイム |
status | 旅程とその各項目のステータス。 | 取り得る値： confirmed cancelled | リアルタイム |
creation_date* | 予約が最初に作成された日付で、ISO 8601の日付形式で表記されています（YYYY-MM-DD). | 2023-02-05 | リアルタイム |
update_date_time* | 旅程の最終更新日時を、ISO 8601日付形式（YYYY-MM-dd'T"HH:mm:ss.SSSZ）で表したものです。 | 2023-10-21T00:00:00.000Z | リアルタイム |
online | 旅程がオンラインで予約されたか（true）、それとも旅行代理店を通じて予約されたか（false）を示します。ブール値で表されます。 | true | Near-real-time |
package | この旅程がパッケージツアーの一部であるか、それとも単独の予約であるかを示します。ブール値で表されます。 | false | Near-real-time |
payment_type | チェックアウト時に使用されたお支払い方法。 | 取り得る値 : credit card points split pay | リアルタイム |
point_of_sale_country_code | お客様が予約を行った販売サイトの国コード。2 文字の ISO 3166-1 alpha-2 形式で表されます。 | GB | Near-real-time |
purchaser | 予約者の識別情報。ネストされた項目の一覧は purchaser の表を参照してください。 | ||
property_booking_items | 旅程の一部として予約された宿泊施設の構成要素。ネストされた項目の一覧は property_booking_items の表を参照してください。 | ||
flight_booking_items | 旅程の一部として予約された航空券の構成要素。ネストされた項目の一覧は flight_booking_items の表を参照してください。 | ||
car_booking_items | 旅程の一部として予約されたレンタカーの構成要素。ネストされた項目の一覧は car_booking_items の表を参照してください。 | ||
activity_booking_items | 旅程の一部として予約された現地ツアーの構成要素。ネストされた項目の一覧は activity_booking_items の表を参照してください。 | ||
insurance_booking_items | 旅程の一部として予約された保険の構成要素。ネストされた項目の一覧は insurance_booking_items の表を参照してください。 | ||
rate | 予約項目または旅程全体の料金と価格設定の詳細。ネストされた項目の一覧は rate の表を参照してください。 | ||
coupon | 旅程に適用されるク ーポン (該当する場合)。ネストされた項目の一覧は coupon の表を参照してください。 |
ホワイトラベル旅行プラットフォームの全フィールドに関する注意事項
- 日付フィールドは協定世界時（UTC）で表示されています。
** これは、個人を特定できる情報（PII）に該当します。必ず、御社のガイドラインに従って適切に対処してください。どうしても必要な場合のみ含めてください。
旅行代理店アフィリエイトプログラム（TAAP）
| フィールド名 | 定義 | 例 | 在庫 |
|---|---|---|---|
itinerary_id | 旅程番号または POS 注文参照番号。 | 72622069245694 | リアルタイム |
agency_reference_code | チェックアウト時に旅行代理店から提供される、お客様専用の旅程表です。 | 86549B_GB | リアルタイム |
status | 旅程とその各項目のステータス。 | 取り得る値： confirmed cancelled | Near-real-time |
creation_date* | 予約が最初に作成された日付で、ISO 8601日付形式で表記されています（YYYY-MM-DD). | 2023-02-05 | リアルタイム |
update_date_time* | 旅程の最終更新日時を、ISO 8601日付形式で表したものです（YYYY-MM-dd'T"HH:mm:ss.SSSZ). | 2023-10-21T00:00:00.000Z | リアルタイム |
online | 旅程がオンラインで予約されたか（true）、それとも旅行代理店を通じて予約されたか（false）を示します。ブール値で表されます。 | true | Near-real-time |
point_of_sale_country_code | お客様が予約を行った国のコードです。2 文字の ISO 3166-1 alpha-2 形式で表されます。 | GB | Near-real-time |
purchaser | 予約者の識別情報。ネストされた項目の一覧は purchaser の表を参照してください。 | ||
agency | 予約を行ったTAAP代理店および担当者の特定。ネストされた項目の一覧は agency の表を参照してください。 | ||
payment | 旅程に関するお支払い情報です。ネストされた項目の一覧は payment の表を参照してください。 | ||
property_booking_items | 旅程の一部として予約された宿泊施設の構成要素。ネストされた項目の一覧は property_booking_items の表を参照してください。 | ||
flight_booking_items | 旅程の一部として予約された航空券の構成要素。ネストされた項目の一覧は flight_booking_items の表を参照してください。 | ||
car_booking_items | 旅程の一部として予約されたレンタカーの構成要素。ネストされた項目の一覧は car_booking_items の表を参照してください。 | ||
activity_booking_items | 旅程の一部として予約された現地ツアーの構成要素。ネストされた項目の一覧は activity_booking_items の表を参照してください。 | ||
rate | 予約項目または旅程全体の料金と価格設定の詳細。ネストされた項目の一覧は rate の表を参照してください。 | ||
earnings | 予約項目または旅程全体の手数料の詳細です。ネストされた項目の一覧は earnings の表を参照してください。 |
すべてのTAAPフィールドに関する注意事項
- 日付フィールドは協定世界時（UTC）で表示されています。
** これは、個人を特定できる情報（PII）に該当します。必ず、御社のガイドラインに従って適切に対処してください。どうしても必要な場合のみ含めてください。
API の詳細
貴社のビジネスにおける「Itineraries API」データの活用方法に基づ き、APIスキーマと設定の概要をご案内いたしました。OpenAPI仕様書をダウンロードし、APIテストツールを使用して、サンプルやスキーマ定義と実際の出力結果がどのように異なるかを確認することができます。
ホワイトレーベル トラベル プラットフォーム
当社のホワイトラベル旅行プラットフォームのパートナー様が、プッシュおよびプル方式を通じて利用可能なフィールド（ネストされたオブジェクトを含む）は以下の通りです：
タープ
当社のプッシュ配信方式を通じてTAAPパートナーが利用可能なフィールド（ネストされたオブジェクトを含む）は、以下の通りです：