تعمل خطافات الويب على تحويل SmartPOS AI إلى منصة تعتمد على الأحداث: في كل مرة يحدث فيها شيء مهم - عملية بيع، أو استرداد أموال، أو تغيير مخزون - يمكن للنظام إخطار خدماتك الخارجية في الوقت الفعلي. بدلاً من استقصاء واجهة برمجة التطبيقات (API)، تتلقى عمليات رد اتصال HTTP فورية. يشرح هذا الدليل كيفية تسجيل نقاط النهاية، وما يحتويه كل حدث، وكيفية إنشاء مستهلكين موثوقين للخطاف على الويب.
ما هي Webhooks ولماذا استخدامها
خطاف الويب هو طلب HTTP POST يرسله SmartPOS AI إلى عنوان URL الذي تحدده عند حدوث حدث محدد. على عكس استطلاع واجهة برمجة التطبيقات (API) التقليدي - حيث يسأل خادمك "هل هناك أي شيء جديد؟" كل بضع ثوانٍ — تقوم خطافات الويب بإرسال البيانات إليك لحظة حدوثها. يعد هذا أكثر كفاءة وأسرع ويقلل بشكل كبير من عدد مكالمات واجهة برمجة التطبيقات (تذكر الحد الأقصى لمعدل 100 طلب/دقيقة). تتضمن حالات الاستخدام الشائعة تحديث قاعدة بيانات المخزون الخارجية عند حدوث عملية بيع، أو نشر إشعار Slack للمبالغ المستردة، أو تشغيل سير عمل التنفيذ عندما يأتي طلب عبر الإنترنت عبر Wolt أو Glovo.
الأحداث المدعومة في SmartPOS AI
يقدم SmartPOS AI 10 أحداث خطاف ويب تغطي لحظات العمل الأكثر أهمية: اكتمال البيع، وإبطال البيع، وإصدار المبالغ المستردة، وإنشاء المنتج، وتحديث المنتج، وحذف المنتج، وتغيير مستوى المخزون، وفتح الوردية، وإغلاق الوردية، وإنشاء العميل. يحمل كل حدث حمولة JSON مع سياق كامل - كائن الإيصال لعملية بيع، وكائن المنتج لتغيير الكتالوج، وما إلى ذلك. يمكنك الاشتراك في جميع الأحداث أو اختيار الأحداث ذات الصلة بالتكامل الخاص بك فقط، مما يحافظ على تركيز عميل الويب هوك الخاص بك.
تسجيل نقطة نهاية Webhook
انتقل إلى الإعدادات ← Webhooks ← إضافة Webhook في المكتب الخلفي. أدخل عنوان URL الخاص بـ HTTPS وحدد الأحداث التي تريد تلقيها. يرسل SmartPOS AI اختبار اتصال للتأكد من إمكانية الوصول إلى عنوان URL ويستجيب برمز الحالة 200. بمجرد التحقق، تصبح نقطة النهاية نشطة وستبدأ في تلقي الأحداث على الفور. يمكنك تسجيل نقاط نهاية متعددة — على سبيل المثال، واحدة لنظام المحاسبة الخاص بك وأخرى لإدارة علاقات العملاء (CRM) — حيث تشترك كل نقطة في أحداث مختلفة. تعرض لوحة المعلومات حالة التسليم ووقت الاستجابة ومعدلات الخطأ لكل نقطة نهاية في لمحة واحدة.
تنسيق حمولة Webhook
تحتوي كل مشاركة ويب هوك على نص JSON ببنية متسقة: حقل event يحدد نوع الحدث، وtimestamp بتنسيق ISO 8601، وكائن data يحتوي على المورد الكامل. يتم تضمين رأس التوقيع (X-Webhook-Signature) حتى يتمكن خادمك من التحقق من أن الحمولة النافعة قد تم إرسالها بالفعل بواسطة SmartPOS AI ولم يتم العبث بها. تحقق من هذا التوقيع باستخدام سر خطاف الويب الخاص بك وHMAC-SHA256 قبل معالجة الحمولة. إن تضمين نوع الحدث في النص يعني أن نقطة النهاية الواحدة يمكنها توجيه أحداث متعددة إلى وظائف معالج مختلفة بشكل نظيف.
تقوم Webhooks من SmartPOS AI بتغذية لوحة المعلومات التحليلية الخاصة بنا في الوقت الفعلي - فنحن نرى كل عملية بيع لحظة حدوثها.
الموثوقية وإعادة المحاولة السلوك
تحدث مشكلات في الشبكة، لذلك يطبق SmartPOS AI سياسة إعادة المحاولة التلقائية لعمليات التسليم الفاشلة. إذا قامت نقطة النهاية الخاصة بك بإرجاع رمز حالة غير 2xx أو انتهت المهلة (نافذة 30 ثانية)، فسيقوم النظام بإعادة المحاولة حتى 5 مرات مع تراجع أسي (1 دقيقة، 5 دقائق، 30 دقيقة، ساعتين، 12 ساعة). تعرض لوحة معلومات webhook كل محاولة مع رمز الحالة ووقت الاستجابة، مما يجعل تصحيح الأخطاء أمرًا سهلاً. بعد استنفاد جميع عمليات إعادة المحاولة، يتم وضع علامة على الحدث على أنه فاشل ويمكنك تشغيل إعادة الإرسال يدويًا من واجهة المستخدم. بالنسبة للتدفقات المهمة، فكر في إضافة قائمة انتظار رسائل (مثل RabbitMQ أو SQS) بين نقطة النهاية لديك ومنطق المعالجة الخاص بك لفصل الاستقبال عن التنفيذ.