انتقل إلى المحتوى
المدونة

ربط API توفر الفنادق دون انتظار أبطأ مورد

تحرير Tekravel
كُتب بمساعدة الذكاء الاصطناعي

تصل المهمة عادةً بصيغة بريئة: «أضيفوا البحث عن الفنادق إلى صفحة الحجز — المورد أعطانا API لتوفر الفنادق، وهناك بيئة تجريبية، والأمر لن يستغرق أكثر من سبرنت واحد». تقرأ التوثيق، وترسل طلباً لشخصين بالغين في دبي لثلاث ليالٍ، فيصلك الرد. ثم ترسل الطلب نفسه لمدينة فيها عدد أكبر من الفنادق، فلا يصلك شيء لوقت طويل ومحرج. وحين يصل، يكون ملفاً بحجم يجعل محلل JSON لديك يعيد النظر في مسيرته المهنية.

عند هذه اللحظة يتغير شكل العمل كله. توفر الفنادق ليس استعلاماً بسيطاً، بل عملية توزيع (fan-out): سؤال واحد من المستخدم يتحول إلى أسئلة كثيرة لموردين كثيرين، كل منهم يجيب بسرعته الخاصة، وبمفرداته الخاصة، وبتعريفه الخاص لما تعنيه كلمة «غرفة». والعميل الذي تبنيه يجب أن يبقى مفيداً بينما هذا التوزيع لم يكتمل بعد. هذا المقال عن تصميم ذلك العميل، وهو موجه إلى مطور يعرف REST وJSON جيداً، لكنه لم يضطر يوماً إلى أن يشرح لفندق لماذا ظهر سعر غير قابل للاسترداد للنزيل على أنه قابل للإلغاء المجاني.

لماذا يبدو ربط API توفر الفنادق أبطأ من كل ما اعتدت عليه

البحث عن رحلة طيران والبحث عن فندق يتشابهان من الخارج: استعلام يخرج، وخيارات مسعّرة تعود. لكنهما في الداخل مشكلتان مختلفتان. إن كنت قد قرأت ملاحظاتنا حول ما يتطلبه ربط API حجز الطيران فعلياً، فأنت تعرف أن السعر الذي تبحث عنه ليس دائماً السعر الذي تحجز به. والفنادق تضيف فوق ذلك صعوبة ثانية: الحجم.

المدينة الواحدة قد تضم مئات الفنادق. كل فندق يبيع عدة أنواع من الغرف. وكل نوع غرفة يُباع بعدة خطط أسعار: مع الإفطار أو بدونه، قابل للاسترداد أو غير قابل، سعر للأعضاء، سعر ضمن باقة. وكل خطة سعر قد تأتي من أكثر من مورد: bedbank، أو مدير قنوات، أو عقد مباشر، أو تاجر جملة تعاقدت معه لأن حصته (allotment) في فندق معين كانت أفضل من غيره. اضرب هذه المستويات ببعضها، وستجد أن البحث «البسيط» شجرة كبيرة مجمّعة من مصادر لا تتفق على الأسماء ولا على المعرّفات.

لذلك فالجزء البطيء نادراً ما يكون في الكود الذي كتبته. إنه أبطأ مورد اخترت أن تنتظره.

نتائج تدريجية أم الإجابة الكاملة: اختر عن وعي

هناك طريقتان صادقتان لإعادة نتائج البحث عن الفنادق، ومعظم عمليات الربط تنتهي في منطقة وسطى غير مريحة بينهما.

انتظار الجميع. الخادم يوزع الطلب، وينتظر كل مورد حتى يجيب أو تنتهي مهلته، ثم يدمج النتائج ويزيل المكرر ويرتب ويعيد قائمة واحدة كاملة. النتيجة نظيفة: طلب واحد، رد واحد، وأسعار يمكن مقارنتها لأنها كلها على الطاولة. الثمن أن المستخدم يحدق في مؤشر التحميل طوال الوقت الذي يستغرقه أبطأ مورد، في كل مرة.

بث ما وصل. الخادم يبدأ التوزيع ويعيد فوراً معرّفاً للبحث. العميل يستعلم عن هذا المعرّف دورياً، أو يبقي اتصالاً مفتوحاً، ويستقبل النتائج على دفعات كلما أجاب مورد. أولى الفنادق تظهر بسرعة. أما الثمن فهو التعقيد في كل مكان آخر: القائمة يتغير ترتيبها بينما المستخدم يقرؤها، وشارة «الأرخص» قد تنتقل، وفندق ظهر من مورد قد يحصل لاحقاً على سعر أرخص من مورد آخر.

إن كانت واجهتك صفحة بحث أمام إنسان، فالنتائج التدريجية هي الخيار الصحيح في الغالب — الشخص يتصفح ولا يشغّل مهمة دفعية، والصفحة التي تعمل أمام عينيه أفضل من صفحة تفكر بصمت. أما إن كان المستهلك نظاماً آخر — مهمة لمقارنة الأسعار، أو أداة حجز للشركات تحتاج إجابة نهائية واحدة — فالانتظار غالباً أبسط وأصح.

أياً كان اختيارك، ثلاث قواعد تحفظ توازن العميل التدريجي:

  • كل دفعة تحمل حالة اكتمال للبحث كله، حتى يميز العميل بين «لا نتائج إضافية حتى الآن» و«لا نتائج إضافية أبداً».
  • النتائج تُدمج على الخادم بمفتاح ثابت للفندق، ولا تُلحق ببعضها فقط. لا ينبغي أن يضطر العميل إلى استنتاج أن بطاقتين تخصان المبنى نفسه.
  • الترتيب حسب السعر مؤقت حتى يكتمل البحث، والواجهة تقول ذلك صراحة. المستخدم يتسامح مع قائمة تستقر تدريجياً، لكنه لا يتسامح مع شارة «أقل سعر» يتبين أنها خاطئة.

نمذجة الغرف وخطط الأسعار بحيث لا تنهار

هنا تفشل معظم عمليات ربط الفنادق بصمت، ويظهر الفشل بعد أشهر على شكل تذكرة دعم لا على شكل تقرير خطأ.

النموذج المغري مسطح: للفندق قائمة عروض، ولكل عرض اسم غرفة وسعر. يبدو جميلاً على الشاشة. ثم يعيد مورد «Deluxe King» و«Deluxe Room, 1 King Bed» لما هو بوضوح الغرفة نفسها، ويعيد مورد آخر الاسم نفسه لغرفتين مختلفتين فعلاً (واحدة تطل على المدينة وأخرى لا)، ويعيد ثالث سعراً لليلة الواحدة بينما الجميع يعيدون سعر الإقامة كاملة. القائمة المسطحة لا تستطيع أن تخبرك أي هذه الحالات أمامك. إنها تعرضها فقط.

النموذج الذي يصمد أمام الموردين الحقيقيين يتكون من أربعة مستويات على الأقل، ويبقيها منفصلة:

المستوىما يحتويهالخطأ الذي يجب تجنبه
الفندقمعرّفك الثابت الخاص، مربوطاً برمز كل مورداستخدام معرّف الفندق لدى المورد كمفتاح أساسي لديك
الغرفةالإشغال، ترتيب الأسرّة، ونص الغرفة الأصلي من المورد محفوظاً كما هو«تنظيف» أسماء الغرف حتى تندمج غرفتان مختلفتان في واحدة
خطة السعرنوع الوجبات، قابلية الاسترداد، طريقة الدفع، والمورد الذي جاءت منهمعاملة الإفطار أو قابلية الاسترداد كجزء من اسم الغرفة
السعرإجمالي الإقامة، العملة، ما يشمله من ضرائب ورسوم وما يُدفع في الفندقعرض سعر الليلة بجانب أسعار الإقامة الكاملة، أو إخفاء الرسوم المدفوعة عند الوصول

قد تختلف معنا في موضع الحدود — بعض الفرق تفصل الإشغال في مستوى خاص به، وهذا منطقي حين تبيع حجوزات متعددة الغرف. ما لا يجوز هو دمج المستويات لأن الواجهة تعرض اثنين منها فقط. الواجهة تستطيع التسطيح عند العرض. أما البيانات فلا.

تفصيل واحد يستحق جملة خاصة: احتفظ بوصف الغرفة الخام كما أرسله المورد إلى جانب أي نسخة موحدة تصنعها. حين يصل نزيل ويُعطى غرفة غير التي في قسيمته، فأول ما سيسأله الجميع: ماذا أرسل المورد فعلاً؟

سياسات الإلغاء بيانات، لا فقرة نصية

كثير من الموردين يعيدون شروط الإلغاء كنص حر: «إلغاء مجاني حتى 3 أيام قبل الوصول، وبعد ذلك غرامة ليلة واحدة». والإغراء كبير أن تعرض هذا النص وتمضي.

لا تفعل. النص لا يمكن مقارنته ولا ترتيبه ولا تصفيته ولا تطبيقه. المستخدم يريد تصفية النتائج إلى الأسعار القابلة للاسترداد. وفريق المالية يريد أن يعرف أي الحجوزات تصبح غير قابلة للاسترداد غداً حتى تتابع الوكالة العميل قبل انقضاء المهلة. ومسار ما بعد الحجز يحتاج أن يخبر العميل، لحظة ضغطه زر الإلغاء، بالمبلغ الذي سيُخصم بالضبط. لا شيء من ذلك يعمل على جملة.

نمذج كل سياسة كقائمة مرتبة من نوافذ الغرامة: من هذه اللحظة حتى تلك اللحظة، الغرامة هي هذا المبلغ (أو هذه النسبة من الإقامة، أو هذا العدد من الليالي). والحدود طوابع زمنية مع منطقة زمنية — منطقة الفندق، لا منطقة خادمك ولا منطقة المستخدم — لأن «3 أيام قبل الوصول» تعني لحظة مختلفة بحسب منتصف الليل الذي تحسب منه. احفظ النص الأصلي من المورد بجانب النسخة المنظمة، واعرض النسخة المنظمة، وتعامل مع أي تعارض بينهما كأمر يستحق التحقيق لا كأمر يُخفى.

وأعد التحقق من السياسة عند الحجز، لا عند البحث فقط. السياسات تتغير بين الاستدعاءين أكثر مما يتوقع أحد.

كم يكلفك الخطأ فعلاً

البحث البطيء يكلفك تحويلات، وهذا سيئ لكنه ظاهر — سيشتكي أحد ما. الإخفاقات المكلفة هي الصامتة.

سعر معروض كقابل للاسترداد بينما يعتبره المورد غير قابل، يعني نزاعاً مع عميل يحمل لقطة شاشة، وغالباً ما تدفع الوكالة الغرامة من جيبها. سعر الليلة المعروض كإجمالي للإقامة يبيع الغرف بأقل من التكلفة حتى يلاحظ أحد في المحاسبة. غرفة مدموجة مع غرفة مختلفة ترسل عائلة من أربعة أفراد إلى غرفة مصممة لشخصين. رسوم تُدفع في الفندق لم تُعرض قط تحوّل تقييماً ممتازاً إلى استرجاع مدفوعات. كل واحدة من هذه قرار نمذجة اتُّخذ في السبرنت الأول، غالباً تحت عنوان «سنرتبها لاحقاً».

التخزين المؤقت: ما يجوز الاحتفاظ به وما لا يجوز

كل فريق يربط API للفنادق يسأل في النهاية: هل يمكننا تخزين النتائج مؤقتاً لنجعل البحث أسرع وأرخص؟ الجواب نعم، لبعض الأشياء، والحد الفاصل بينها أهم من أي رقم أداء.

المحتوى الثابت — أسماء الفنادق، العناوين، الإحداثيات، الصور، قوائم المرافق، أوصاف الغرف — نادراً ما يتغير، وهو بالضبط ما يجب تخزينه بقوة في مخزنك الخاص. راجع شروط المورد بشأن طريقة تخزينه وعرضه، فبعض التراخيص تقيّد ذلك. جلبه مباشرة مع كل بحث بطيء بلا فائدة.

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

ما لا يجوز تخزينه أبداً هو أي شيء يمثل التزاماً: رمز سعر محجوز، أو مرجع حجز، أو عرض لتكلفة الإلغاء. هذه تخص مستخدماً واحداً ولحظة واحدة.

قبل أن تقول إن العمل انتهى

قائمة قصيرة تستحق أن تمررها على عملية الربط لديك قبل أن تحمل حجوزات حقيقية:

  • البحث يعيد حالة اكتمال، والعميل يتصرف بشكل مختلف قبلها وبعدها.
  • الفنادق مفهرسة بمعرّفك الخاص، مع ربط رمز كل مورد به.
  • الغرفة وخطة السعر والسعر كائنات منفصلة في بياناتك، أياً كان ما تعرضه الشاشة.
  • كل سعر يوضح إن كان لليلة أو للإقامة، وما الذي يُدفع عند الوصول.
  • سياسات الإلغاء محفوظة كنوافذ غرامة زمنية بتوقيت الفندق، مع الاحتفاظ بالنص الأصلي.
  • مسار الحجز يعيد التسعير ويعيد قراءة السياسة قبل أن يخصم من أحد.
  • لا شيء يمثل التزاماً يُقدَّم أبداً من ذاكرة مؤقتة.

إن كنت تفاضل بين بناء كل هذا مع كل مورد على حدة وبين البدء من منصة واجهت هذه المشكلات من قبل، فجانب العقود مهم بقدر الكود — مقالنا عن عقود الفنادق وأسعار bedbank يوضح ما يجب أن تطلبه. واجهات API الخاصة بنا للطيران والفنادق تُفتح عبر محادثة لا عبر مفتاح ذاتي الخدمة؛ وإن كان هذا هو الطريق الذي تريد استكشافه، ابدأ تلك المحادثة من صفحة واجهات API للسفر.

التوزيع على الموردين لن يختفي. العميل الجيد يتوقف فقط عن التظاهر بأنه غير موجود.

تحرير Tekravel

قسم تقنيات السفر

يكتب قسم تقنيات السفر في Tekravel لأهل المهنة: أصحاب الوكالات، والمجمّعين، والمطوّرين الذين يربطون أنظمتهم بها. تُراجَع كل مقالة أمام المنصة التي تصفها قبل نشرها.