本文へスキップ
ブログ

航空券予約API連携:ドキュメントに書かれていないこと

Tekravel 編集部
AI の支援を受けて執筆

ボードのチケットには「フライトを追加」とだけ書かれています。決済連携も、送料計算も、もしかすると地図連携もやってきたあなたが持ち込むのは、いちばん素直なモデルです。検索して、結果を見せて、カードを決済して終わり。ところが最初の本番予約は結果画面と違う価格で返ってきて、二件目はタイムアウトし、お客様に座席があるのか誰にも分からず、運用チームからは「予約はあるのに航空券がないのはなぜか」と聞かれます。航空券予約API連携は、外から見ればECのチェックアウトそっくりです。しかしその下にあるのは、RESTよりはるか昔に設計されたシステムを相手にした分散トランザクションで、驚きのほとんどはその隔たりから生まれます。

この記事は、PNRを一度も見たことのない開発者のためのものです。特定サプライヤーのエンドポイントの話ではありません。名前はプロバイダーごとに変わっても、形は変わりません。

航空券予約API連携の呼び出し順序

ほぼすべてのフライトAPIは、メソッド名が何であれ、同じ四つのステップをたどります。ステップ間の境界を正しく引くことが、仕事の大半です。

ステップ得られるもの保存すべきもの起こりがちな問題
検索価格と、中身の読めないオファーキーまたは運賃キー付きの旅程永続化するものはない。結果はすぐ古くなる価格を確定値として扱う。決済前にキーが失効する
価格確認・検証確定価格、運賃規則、手荷物、場合によっては必須の搭乗者項目検証済みオファーとその有効期限価格が変わる。クラスが売り切れる。表示した規則と違う
予約予約記録(PNR)、予約番号、発券期限自前の参照番号、予約番号、期限、実際に送信した搭乗者データそのもの応答のないタイムアウト。PNRの重複。氏名の拒否
発券発行された電子航空券番号。ここで実際にお金が確定するすべての航空券番号を、対応する搭乗者と区間に紐づけて一部だけ発券。期限切れで航空会社が予約を取り消す

議論になりやすいのは三行目です。多くのAPIが予約と発券を一回の呼び出しで済ませられるからです。使っても構いません。ただ航空会社の世界では、二つは依然として別物です。航空券のないPNRは存在しうるし、PNRができた後に発券が失敗することもあります。一体型のエンドポイントは、片方が成功しもう片方が失敗した瞬間を隠すだけなので、データモデルにはその状態の置き場所が必要です。

検索が返さないものにも注目してください。それは約束です。検索結果は広告にすぎません。価格確認が見積もりで、販売になるのは航空券だけです。

検索した価格で予約できない理由

Web開発者は商品カタログを想定します。航空会社の在庫はカタログではありません。一便の座席は予約クラスごとに売られ、各クラスは特定運賃の座席の枠で、航空会社は搭乗率に応じてこの枠を絶えず開け閉めしています。検索結果は、すでに少し遅れているかもしれない空席情報から素早く組み立てられます。ユーザーがパスポート二冊分を入力し終えるころには、その便の最安クラスが閉じているかもしれません。価格確認で改めて問い合わせると、正直な答えが高くなっていることがあるのです。

税金も独自に動きます。税は価格確認の時点で実際の搭乗者と経路に対して再計算され、小児や幼児は検索が想定した大人とは価格が異なります。販売サイトが円で表示し、サプライヤーが別の通貨で見積もる場合は、為替換算も数字が動くもう一つの要因になります。

設計上の結論はシンプルで、しかも見落とされがちです。検索時の価格で決して決済しないこと。決済の前に価格確認を実行して比較し、金額が変わっていれば新しい金額を見せて同意を取ります。上乗せするマークアップは、結果画面の値を持ち越すのではなく、再確認した運賃に対して計算し直す必要があります。旅行会社がオンラインでマークアップ戦略を組むときと同じ理屈で、土台の価格が動けば同じように崩れます。

冪等性と、予約中のタイムアウトが意味すること

この節は二度読んでください。

予約の呼び出しがタイムアウトしたとき、何が起きたのかは分かりません。リクエストが届いていないかもしれない。届いて失敗したかもしれない。あるいは、いちばん痛いケースとして、届いて、サプライヤーが航空会社にPNRを作成し、レスポンスだけが帰り道で失われたのかもしれません。コードから見れば三つとも同じです。航空会社から見れば、三つ目はお客様の名前で座席を押さえている生きた予約です。

他の連携で身についた反射はリトライです。ここで闇雲にリトライすると、同じ搭乗者、同じ便に二つ目のPNRができかねません。航空会社は重複予約を規約違反とみなします。航空会社や旅行会社の契約によって、結果は片方または両方の予約の自動取消から、発券した側に送られる精算請求であるADM(Agency Debit Memo)まで幅があります。受け取った旅行会社は、なぜあなたのシステムが二重に予約したのかを知りたがるでしょう。

有効な対策を、おおよその順に挙げます。

  • 外部に呼び出す前に自前の予約参照番号を作る。保存し、APIがクライアント参照を受け付ける箇所ではすべてリクエストに添えて送ります。APIが冪等キーに対応していれば使い、対応していなくても、その参照番号があとで予約を探す手がかりになります。
  • 「不明」状態を明示的にモデル化する。保留、確定、失敗、そして不明。タイムアウトは予約を失敗ではなく不明に移します。
  • 不明は繰り返しではなく照会で解決する。再試行を決める前に、参照番号で予約を取得するか、その搭乗者の最近の予約一覧を確認します。
  • 突合ジョブを回す。不明のまま残ったものを洗い出してサプライヤーの報告と照らし合わせ、決着がつかないものは推測せず人が見るキューに回します。

発券時のタイムアウトは、お金が絡んだ同じ問題です。発券前にカードを売上確定し、発券が止まれば、支払い済みで航空券のないお客様が生まれるかもしれません。売上確定前に発券し、確定が失敗すれば、誰かが航空会社に代金を払わなければならない書類を発行したことになります。一般的なのは、まずカードをオーソリし、発券し、成功したら売上確定する形です。肝心なのは意図して決めることで、本番で発見することではありません。

Web開発者が驚く航空業界の概念

どれも難しくはありません。ただ、それぞれが「そんなものがあるとは知らなかった」誰かの一週間を奪ってきました。

PNRは航空券ではない

PNRは予約記録で、搭乗者、区間、連絡先、期限が入っています。航空券は搭乗の権利を与える、支払い済みの書類です。未発券のPNRは発券期限で失効し、座席は再び販売に戻ります。あなたの側では何の知らせもなく、ということもあります。

氏名はほぼ変更できない

発券後、多くの運賃は軽微な訂正を超える氏名変更を認めず、何が軽微かは航空会社によって異なります。氏名は渡航書類と一致していなければなりません。姓と名は別々に受け取り、パスポートのローマ字表記どおりに入力してもらい、自由入力欄の敬称が氏名欄に紛れ込まないようにし、検証は予約の呼び出しの前に行います。後ではありません。

搭乗者区分は飾りではなく価格である

大人、小児、幼児は運賃の区分で、どれに当たるかを決める年齢は通常、予約日ではなく搭乗日時点のものです。膝上の幼児はたいてい座席を使わず、大人と一緒でなければ搭乗できません。区分を誤れば、価格確認は失敗するか、誤った運賃を返します。

時刻は現地時刻、区間はレグではない

出発・到着時刻は各空港の現地時刻で与えられます。表示のためにユーザーのタイムゾーンへ変換してはいけないし、時差を考慮せずに引き算で所要時間を出してもいけません。旅程は区間からなり、テクニカルストップのある区間には複数のレグが含まれます。UIとデータで、何を「経由」と呼ぶのかを揃えておく必要があります。

販売後にも物事は起きる

航空会社は発券後もスケジュールを変更します。発券時に正しかった予約が、数週間後には新しい時刻、新しい便名、途切れた乗り継ぎを示すことがあり、サプライヤーによって通知、キュー、予約の再取得のいずれかでそれを知ることになります。見なくなった後も予約は変わる、という前提で設計してください。

Voidは払い戻しではない

発券直後には通常、航空券を最初からなかったかのようにvoidできる時間枠があります。それを過ぎると運賃規則に基づく払い戻ししかできず、手数料がかかったり、何も戻らなかったりします。その時間枠と規則はサプライヤーと発券契約しだいなので、「キャンセル」ボタンを作る前に読んでおきましょう。

失敗の代償

フライト連携の失敗は、独特のかたちで高くつきます。ログではなく人に降りかかるのです。重複予約は航空会社への電話になり、旅行会社のアカウントへの請求になるかもしれません。決済されたのに航空券がないお客様は、返金、苦情、チャージバックのリスクになります。決済が成功しないまま発行された航空券は、誰かが清算しなければならない航空会社への債務になります。誰も処理しなかったスケジュール変更は、すでに早く出発した便を待って空港に立つ旅行者になります。

どれも正常系のテストには現れません。異常系から先に書いてください。予約中のタイムアウト、上がった価格、PNR作成後に失敗した発券、決済成功後のvoid。これらが処理できていれば、正常系は簡単な部分です。

フライトAPIに対するテスト

サプライヤーのテスト環境は便利ですが、完全ではありません。本番より静かなことが多く、売り切れや価格変動はまれで、タイムアウトをまったく再現しないものもあります。呼び出しの形や検証エラーの確認に使い、そのうえで、運用チームに周知したうえで、本番で実際に予約し時間枠内にvoidする管理されたテストを計画してください。

そもそも連携すべきかどうかは別の問いです。本当に必要なのが自社システム内の生の在庫ではなく販売サイトなら、その損得はホワイトレーベルと自社開発の比較で整理しており、同じ考え方はサブエージェント向けB2Bポータルにも当てはまります。在庫を自社のコードに置きたいなら、このプラットフォームは航空券・ホテルAPIを提供しており、アクセスはセルフサービスのキーではなく、ユースケースについての対話から始まります。上の質問を一つずつ投げかけるのにも、ちょうどよいタイミングです。

Tekravel 編集部

旅行テクノロジー担当

Tekravelの旅行テクノロジー担当は、業界の読者に向けて書いています。旅行会社の経営者、ホールセラー、そして両者をつなぐ開発者です。すべての記事は、公開前に記事が扱うプラットフォーム上で確認されます。