البيئات والحدود والإصدارات

البيئة التجريبية والإنتاج، عنوان URL أساسي واحد

عنوان URL الأساسي: https://api.dubaitrip.com/v1. تتشاركه البيئة التجريبية والإنتاج؛ والمفتاح الذي توقّع به هو ما يحدد البيئة. يعمل مفتاح dt_sbx_ على بيئات الاختبار لدى مورّدينا — تعمل عمليات البحث والتسعير والتحقق من الأسعار والطلبات والحجوزات وإصدار التذاكر والإلغاءات من البداية إلى النهاية على مخزون تجريبي، دون تذكرة أو قسيمة حقيقية ودون أي رسوم. أما مفتاح dt_live_، الذي يُصدَر بعد مراجعة الإنتاج، فيصل إلى المخزون الحي ويُسوّى من وديعتك.

تُفصل حجوزات البيئة التجريبية عن حجوزات الإنتاج في بوابة المطوّرين (كل حجز مُعلَّم)، وتُدار الصلاحيات والحدود وقواعد IP لكل بيئة على حدة.

حدود معدل الطلبات والحصص

يُقيَّد كل مفتاح بدلو رموز (طلبات مستمرة في الثانية إضافةً إلى دفعة) وحصة يومية. القيم الافتراضية للبيئة التجريبية: طلبان/ثانية، ودفعة 5، و2,000 طلب/يوم. تُتفق حدود الإنتاج لكل حساب على حدة. تجاوز الدلو يُرجع 429 api_rate_limited مع ترويسة Retry-After؛ واستنفاد الحصة يُرجع 429 api_quota_exceeded حتى منتصف الليل بتوقيت UTC.

عمليات البحث الثقيلة غير متزامنة بطبيعتها: مرّر wait=false للحصول على searchId فورًا ثم استطلع نقطة نهاية البحث، أو wait=true لتلقي النتيجة الكاملة في استدعاء واحد. يُحتسب الاستطلاع ضمن حدودك مثل أي طلب آخر.

ضابط نسبة البحث إلى الحجز

تُقنَّن عمليات البحث أيضًا وفقًا للحجوزات التي تُجريها. يمنح كل يوم من نافذة متحركة (7 أيام افتراضيًا) حصة مجانية من عمليات البحث، ويضيف كل حجز يتم خلال تلك النافذة عدد cap إضافيًا من عمليات البحث — و cap هو رقم عمليات البحث لكل حجز المتفق عليه لحسابك والمعروض في بوابة المطوّرين. لا تُحتسب أبدًا عمليات الاستطلاع والتسعير وقواعد الأسعار وقراءات المحتوى؛ بل تُحتسب فقط استدعاءات البحث عن الطيران والفنادق.

بمجرد استنفاد الحصة، تُرجع عمليات البحث 429 look_to_book_exceeded مع ترويسة Retry-After تشير إلى منتصف الليل التالي بتوقيت UTC، حين يخرج أقدم يوم من النافذة. أي حجز يعيد فتح الحصة فورًا. تعرض بطاقة نسبة البحث إلى الحجز في بوابة المطوّرين العدّادات الحية والحد والمتبقي؛ وإذا كان تكاملك يبحث بشكل مشروع أكثر بكثير مما يحجز، فاطلب منا رفع الحد بدلًا من إعادة المحاولة رغم الرفض.

عدم التكرار (Idempotency)

نقاط النهاية التي تُلزم بالمال أو المخزون — إنشاء طلب أو حجز، والإصدار، والإلغاء — تتطلب ترويسة Idempotency-Key (أي سلسلة فريدة حتى 128 حرفًا، ويُعد UUID مثاليًا). إعادة المحاولة بالمفتاح نفسه تُرجع الاستجابة الأصلية بدلًا من إنشاء نسخة مكررة؛ أما إرسال نص مختلف بمفتاح مُعاد استخدامه فيُرجع 409.

الإصدارات

يظهر الإصدار في المسار (/v1). التغييرات الإضافية — حقول اختيارية جديدة، وقيم تعداد جديدة، ونقاط نهاية جديدة — تُطرح دون رفع رقم الإصدار، لذا حلّل الاستجابات بحذر وتجاهل الحقول غير المعروفة. التغييرات الجذرية تحصل على إصدار رئيسي جديد مع فترة انتقال؛ ويسرد دليل سجل التغييرات كل تغيير.