環境、制限、バージョン管理

サンドボックスと本番、1つのベースURL

ベースURL：https://api.dubaitrip.com/v1。サンドボックスと本番で共通で、署名に使うキーによって環境が選択されます。dt_sbx_ キーは当社サプライヤーのテスト環境に対して実行されます。検索、価格確認、料金確認、オーダー、予約、発券、キャンセルがすべてテスト在庫上でエンドツーエンドに動作し、実際のチケットやバウチャーは発行されず、課金も一切発生しません。本番審査後に発行される dt_live_ キーは本番の在庫に接続し、デポジットから精算されます。

サンドボックスと本番の予約は開発者ポータル上で区別され（各予約にマークが付きます）、スコープ、制限、IPルールは環境ごとに管理されます。

レート制限と上限

各キーは、トークンバケット（1秒あたりの持続リクエスト数とバースト）と1日の上限によって制限されます。サンドボックスの既定値は、2リクエスト/秒、バースト5、2,000リクエスト/日です。本番の制限はアカウントごとに取り決めます。バケットを超えると Retry-After ヘッダー付きで 429 api_rate_limited が、上限を使い切ると UTC の午前0時まで 429 api_quota_exceeded が返されます。

重い検索は設計上非同期です。wait=false を指定するとすぐに searchId が返されるので検索エンドポイントをポーリングし、wait=true を指定すると1回の呼び出しで完全な結果を受け取れます。ポーリングも他のリクエストと同様に制限にカウントされます。

ルック・トゥ・ブック制限

検索は、お客様の予約数に応じても配分されます。直近の集計期間（既定では7日間）の1日ごとに無料の検索枠が付与され、その期間内の予約1件ごとにさらに cap 件の検索が追加されます。cap は、お客様のアカウントで取り決めた予約1件あたりの検索数で、開発者ポータルに表示されます。ポーリング、価格確認、運賃規則、コンテンツの読み取りはカウントされず、対象となるのは航空券とホテルの検索呼び出しのみです。

枠を使い切ると、検索は Retry-After ヘッダー付きで 429 look_to_book_exceeded を返します。Retry-After は、集計期間の最も古い日が外れる次の UTC 午前0時を指します。予約を1件行うと枠はすぐに回復します。開発者ポータルのルック・トゥ・ブックカードには、リアルタイムのカウンター、上限、残り枠が表示されます。連携の性質上、予約よりはるかに多くの検索が正当に必要な場合は、拒否に対して再試行を繰り返すのではなく、上限の引き上げを当社にご依頼ください。

冪等性

金銭や在庫を確定させるエンドポイント（オーダーや予約の作成、発券、キャンセル）には Idempotency-Key ヘッダーが必要です（128文字以内の任意の一意な文字列で、UUIDが最適です）。同じキーで再試行すると、重複を作成せずに元のレスポンスが返されます。再利用したキーで異なるボディを送ると 409 が返されます。

バージョン管理

バージョンはパスに含まれます（/v1）。追加的な変更（新しい任意フィールド、新しいenum値、新しいエンドポイント）はバージョンを上げずにリリースされるため、防御的にパースし、未知のフィールドは無視してください。互換性のない変更には移行期間付きで新しいメジャーバージョンが割り当てられます。すべての変更は変更履歴ガイドに記載されています。