محیط‌ها، محدودیت‌ها و نسخه‌بندی

محیط آزمایشی و محیط عملیاتی، یک URL پایه

URL پایه: https://api.dubaitrip.com/v1. محیط آزمایشی و محیط عملیاتی از آن مشترکاً استفاده می‌کنند؛ کلیدی که با آن امضا می‌کنید محیط را انتخاب می‌کند. کلید dt_sbx_ روی محیط‌های آزمایشی تأمین‌کنندگان ما اجرا می‌شود — جست‌وجو، قیمت‌گذاری، بررسی نرخ، سفارش، رزرو، صدور بلیت و لغو همگی روی موجودی آزمایشی از ابتدا تا انتها کار می‌کنند، بدون بلیت یا واچر واقعی و بدون هیچ هزینه‌ای. کلید dt_live_ که پس از بررسی محیط عملیاتی صادر می‌شود، به موجودی واقعی می‌رسد و از سپرده شما تسویه می‌شود.

رزروهای محیط آزمایشی و محیط عملیاتی در پورتال توسعه‌دهندگان شما جدا نگه داشته می‌شوند (هر رزرو علامت‌گذاری شده است) و دامنه‌های دسترسی، محدودیت‌ها و قواعد IP برای هر محیط جداگانه مدیریت می‌شوند.

محدودیت نرخ و سهمیه‌ها

هر کلید با یک سطل توکن (درخواست‌های پایدار در ثانیه به‌علاوه ظرفیت جهش) و یک سهمیه روزانه کنترل می‌شود. پیش‌فرض‌های محیط آزمایشی: 2 درخواست/ثانیه، جهش 5، 2,000 درخواست/روز. محدودیت‌های محیط عملیاتی برای هر حساب توافق می‌شود. عبور از سطل پاسخ 429 api_rate_limited را با هدر Retry-After برمی‌گرداند؛ اتمام سهمیه تا نیمه‌شب UTC پاسخ 429 api_quota_exceeded می‌دهد.

جست‌وجوهای سنگین ذاتاً ناهمگام‌اند: wait=false را بفرستید تا بلافاصله یک searchId بگیرید و اندپوینت جست‌وجو را پرس‌وجو کنید، یا wait=true تا نتیجه کامل را در یک فراخوانی دریافت کنید. پرس‌وجوهای دوره‌ای مانند هر درخواست دیگری از محدودیت‌های شما کم می‌کنند.

کنترل نسبت جست‌وجو به رزرو

جست‌وجوها همچنین بر اساس رزروهایی که انجام می‌دهید سهمیه‌بندی می‌شوند. هر روز از یک بازه غلتان (به‌طور پیش‌فرض 7 روز) سهمیه رایگانی از جست‌وجو می‌دهد، و هر رزروی که در آن بازه انجام شود به اندازه cap جست‌وجوی دیگر اضافه می‌کند — cap همان عدد جست‌وجو به ازای هر رزرو است که برای حساب شما توافق شده و در پورتال توسعه‌دهندگان نمایش داده می‌شود. پرس‌وجوهای دوره‌ای، قیمت‌گذاری، قوانین نرخ و خواندن محتوا هرگز شمرده نمی‌شوند؛ فقط فراخوانی‌های جست‌وجوی پرواز و هتل شمرده می‌شوند.

پس از اتمام سهمیه، جست‌وجوها پاسخ 429 look_to_book_exceeded را با هدر Retry-After می‌گیرند که به نیمه‌شب UTC بعدی اشاره می‌کند، زمانی که قدیمی‌ترین روز بازه خارج می‌شود. یک رزرو سهمیه را بلافاصله دوباره باز می‌کند. کارت «نسبت جست‌وجو به رزرو» در پورتال توسعه‌دهندگان شمارنده‌های زنده، سقف و مقدار باقی‌مانده را نشان می‌دهد؛ اگر یکپارچه‌سازی شما به‌طور مشروع بسیار بیشتر از رزروهایش جست‌وجو می‌کند، به‌جای تکرار درخواست‌های ردشده، از ما بخواهید سقف را بالا ببریم.

Idempotency (ایمنی تکرار)

اندپوینت‌هایی که پول یا موجودی را قطعی می‌کنند — ایجاد سفارش یا رزرو، صدور، لغو — به هدر Idempotency-Key نیاز دارند (هر رشته یکتا تا 128 نویسه؛ UUID ایده‌آل است). تکرار با همان کلید به‌جای ایجاد نسخه تکراری، پاسخ اصلی را برمی‌گرداند؛ بدنه متفاوت با کلید تکراری پاسخ 409 می‌گیرد.

نسخه‌بندی

نسخه در مسیر است (/v1). تغییرات افزایشی — فیلدهای اختیاری جدید، مقادیر enum جدید، اندپوینت‌های جدید — بدون افزایش نسخه منتشر می‌شوند، پس به‌صورت محتاطانه پارس کنید و فیلدهای ناشناخته را نادیده بگیرید. تغییرات ناسازگار با یک نسخه اصلی جدید و یک بازه مهاجرت همراه‌اند؛ راهنمای «تغییرات نسخه‌ها» همه تغییرات را فهرست می‌کند.