استجابات الأخطاء
تُنتج Hotspot API نوعين من النتائج: فشل المصادقة (HTTP 401) والاستجابة الناجحة (HTTP 200). وقائمة النزلاء الفارغة ليست خطأً. فيما يلي الحالات التي قد تواجهها وما يجب فعله في كل منها.
رموز حالة HTTP#
| الرمز | المتن | المعنى وما العمل |
|---|---|---|
200 | {"success": 1, "otelde": [...]} | نجاح. عالج القائمة. |
200 | {"success": 1, "otelde": []} | نجاح، ولا يوجد نزلاء مقيمون. راجع الملاحظة حول القائمة الفارغة أدناه. |
401 | {"success": 0} | ترويسة ApiKey مفقودة أو المفتاح غير معروف. لا تُعِد المحاولة؛ بل تحقق من المفتاح ونبّه المسؤول. |
404 | صفحة خطأ | مسار خاطئ. تأكد من أن المسار هو /public/json/customer/inhotel تمامًا. |
405 | صفحة خطأ | استُخدمت طريقة غير POST (مثل GET من المتصفح). |
5xx / انتهاء المهلة | — | خطأ مؤقت في الخادم أو الشبكة. أعد المحاولة بفواصل متزايدة (30 ثانية، ثم دقيقة، ثم 5 دقائق)، واستمر في استخدام آخر قائمة ناجحة في هذه الأثناء. |
القائمة الفارغة#
تعني otelde: [] عدم وجود نزلاء مسجّلي الوصول في الفندق، وهذا أمر طبيعي في الفنادق الصغيرة خارج الموسم. لكن القائمة التي كانت ممتلئة في الاستعلام السابق ثم أصبحت فارغة فجأة تشير عادةً إلى خطأ تشغيلي لدى الفندق (تسجيل مغادرة جماعي خاطئ، أو تغيير في حالة الحجز). قبل إغلاق جميع حسابات Wi-Fi، تأكد من أن القائمة عادت فارغة في استعلامين متتاليين.
إعادة المحاولة والمهلات#
- استخدم مهلة طلب مدتها 10 ثوانٍ؛ فالقائمة تُعاد خلالها حتى في الفنادق الكبيرة.
- أعد المحاولة عند
5xxوأخطاء الشبكة؛ ولا تُعِدها عند401أو404أو405، فهي أخطاء في الإعداد. - احتفظ بآخر قائمة ناجحة ما دام الاستعلام يفشل. ولا تُغلق إلا حسابات النزلاء الذين اختفوا من القائمة في استجابة ناجحة.
- احسب مرات الفشل المتتالية ونبّه المسؤول عند تجاوز حد معيّن (مثل 15 دقيقة).
حالات شائعة#
| الحالة | السبب المحتمل | ما العمل |
|---|---|---|
| النزيل غير موجود في القائمة | لم يسجّل الاستقبال وصول النزيل، أو أُلغي الحجز، أو النزيل غير مُعلَّم بأنه «مقيم في الفندق»، أو أنه سجّل مغادرته. | اعرض في البوابة رسالة «رقم الغرفة واسم العائلة غير متطابقين» ووجّه النزيل إلى الاستقبال. لا حاجة إلى إعادة الجلب؛ إذ سيظهر النزيل في المزامنة التالية. |
| عدة سجلات للغرفة نفسها | يقيم في الغرفة أكثر من نزيل، ولكل منهم سجل مستقل. | أمر طبيعي. افتح حسابًا لكل نزيل (unique). |
identityNumber فارغ | سُجّل النزيل دون بيانات هوية. | اعتمد في المطابقة على اسم العائلة + تاريخ الميلاد بديلًا؛ واترك الحقل فارغًا في سجل القانون رقم 5651 واربطه بـ unique. |
roomName غير مطابق | كتب النزيل «0104» أو «غرفة 104» بدلًا من «104»؛ والقيمة سلسلة نصية. | وحّد صيغة الطرفين قبل المقارنة، ولا تحوّل القيمة إلى رقم. |
checkout في الماضي لكن النزيل ما زال في القائمة | مدّد النزيل إقامته أو يغادر متأخرًا ولم يعالج الاستقبال ذلك بعد. | أبقِ الوصول مفتوحًا ما دام النزيل في القائمة، وحدّث نهاية الجلسة عندما تتغير قيمة checkout. |