Webhooks و REST API

يكشف HiLucy عن REST API شاملة تحت namespace hilucy/v1. تغذي هذه API كلاً من تطبيقات الواجهة الأمامية والتكاملات مع الأطراف الثالثة. إذا كنت تبني تكاملات مخصصة أو تربط أنظمة خارجية، يغطي هذا الدليل مجموعات نقاط النهاية الرئيسية وطرق المصادقة وأنماط webhook.

مجموعات نقاط نهاية API

الـ API منظمة في مجموعات وظيفية، كل منها يتعامل مع مجال محدد:

طلبات الخدمة والعمليات

أكبر مجموعة نقاط نهاية تتعامل مع العمليات اليومية للعقار -- طلبات الخدمة وجهات الاتصال والقوائم والحجوزات والعملاء وإدارة المخزون. أكثر من 30 مسارًا يغطي عمليات CRUD لجميع البيانات التشغيلية.

الوصولات

نقاط نهاية لتدفق تسجيل وصول الضيف: حل الرموز ومطابقة الحجوزات وتحديثات الضيف وإجراء الوصول المتكافئ الذي ينقل الحجز إلى حالة المقيم.

ضيوف الحجز

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

الدفع والمالية

• صلاحية الدفع -- إعداد متعدد الدافعين: إنشاء setup intents، تأكيد طرق الدفع، إلغاء الصلاحيات، وتهيئة الفواتير لكل دافع
• المالي -- استعلامات دفتر الأستاذ، بحث الأرصدة، إدارة قواعد العمولة، والتقارير المالية

الدردشة

نقطة نهاية بث Server-Sent Events (SSE) تعمل كوكيل للمحادثات مع مساعد LucyAI. تُستخدم بواسطة واجهة الدردشة في بوابة الضيف لاستجابات الذكاء الاصطناعي في الوقت الفعلي.

المصادقة

تسجيل دخول اجتماعي (Google، Apple)، تجديد رموز JWT، إنشاء روابط سحرية والتحقق من الروابط السحرية. راجع قسم المصادقة أدناه للتفاصيل.

الموصلات والمدفوعات

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

بوابة WiFi

نقاط نهاية البوابة المقيدة لـ WiFi الضيوف: إدارة الجلسات، تعريف الضيوف، التفويض، وتتبع الأجهزة.

Webhooks (الواردة)

يتلقى HiLucy webhooks من عدة خدمات خارجية:

• Cloudbeds -- أحداث إنشاء/تحديث/إلغاء الحجوزات التي تزامن الحجوزات في HiLucy
• Stripe -- تأكيدات الدفع والنزاعات وأحداث الصرف
• Acuity Scheduling -- حجوزات وإلغاءات المواعيد
• WhatsApp (Meta) -- تحديثات حالة تسليم الرسائل
• Monday.com -- أحداث إنشاء وتغيير حالة المهام

كل نقطة نهاية webhook واردة تتحقق من توقيع الطلب قبل المعالجة.

المصادقة

تدعم API أوضاع مصادقة متعددة حسب نقطة النهاية:

• JWT Bearer Token -- الطريقة الرئيسية للطلبات المصادق عليها. احصل على رمز عبر نقاط نهاية المصادقة (تسجيل دخول اجتماعي أو رابط سحري)، ثم ضمّنه كـ Authorization: Bearer <token> في الطلبات اللاحقة.
• رمز جلسة الوصول -- مصادقة بالرمز لتدفق تسجيل الوصول. لا يتطلب حساب مستخدم؛ الرمز نفسه يمنح وصولاً محدودًا لحجز محدد.
• جلسة WordPress -- مصادقة قياسية بملف تعريف الارتباط لطلبات سياق الإدارة من لوحة التحكم.
• عام -- بعض نقاط النهاية (مثل تعريف بوابة WiFi) يمكن الوصول إليها عامًا بدون مصادقة.

أنماط تكامل Webhooks

إذا كنت تبني نظامًا يرسل webhooks إلى HiLucy أو يستهلك بيانات من أحداث HiLucy:

• Webhooks الواردة تُهيأ لكل تكامل في الإعدادات > التكاملات. كل تكامل يوفر عنوان URL الخاص بـ webhook والمفاتيح السرية المطلوبة.
• التكافؤ -- نقاط النهاية الرئيسية (مثل إجراء الوصول) متكافئة، مما يعني أن تسليمات webhook المكررة لن تنشئ تغييرات حالة مكررة.
• التحقق من التوقيع -- يتم التحقق من جميع webhooks الواردة باستخدام توقيعات HMAC أو التحقق الخاص بالمنصة (مثل توقيعات webhook الخاصة بـ Stripe، رموز التحقق من Meta).

حدود المعدل وأفضل الممارسات

• نقاط النهاية المصادق عليها لها حد معدل لكل رمز مستخدم. تجنب الاستقصاء؛ استخدم webhooks للتحديثات في الوقت الفعلي حيثما أمكن.
• دائمًا ضمّن معالجة أخطاء مناسبة لاستجابات 401 (رمز منتهي)، 403 (أذونات غير كافية)، و 429 (تجاوز حد المعدل).
• للعمليات المجمعة، جمّع الطلبات حيث تدعم API ذلك بدلاً من إجراء مكالمات فردية لكل سجل.

نصائح

• استخدم نقطة نهاية تجديد JWT لتجديد الرموز قبل انتهاء صلاحيتها بدلاً من إعادة المصادقة من الصفر
• اختبر تكاملات webhook ضد بيئة التطوير (dev.hilucy.com) قبل توجيهها إلى الإنتاج
• تحقق من مؤشرات حالة التكامل في الإعدادات إذا بدت أحداث webhook تتوقف عن الوصول