آلية الربط مع الأنظمة الخارجية عبر API و Webhooks

توفر منصة متجرة آلية تكامل مرنة وآمنة تتيح ربط المتاجر الإلكترونية مع الأنظمة الخارجية مثل الأنظمة المحاسبية، أنظمة ERP، أنظمة إدارة المخزون وغيرها، وذلك من خلال واجهات API و Webhooks المتاحة داخل لوحة تحكم المتجر.

يهدف هذا المقال إلى توضيح:

• الفرق بين API و Webhooks

• ماذا يجد التاجر في كل صفحة إعدادات

• آلية الربط الصحيحة بين متجرة والأنظمة الخارجية

• أخطاء شائعة يجب تجنبها أثناء التكامل

أولًا: نظرة عامة على آلية التكامل

تعتمد متجرة على مبدأ واضح في التكامل:

• API: يُستخدم عندما يكون النظام الخارجي هو الطرف الذي يبدأ الطلب (Request)

• Webhook: يُستخدم عندما تكون متجرة هي الطرف الذي يرسل إشعارًا بحدوث حدث (Event)

🔑 لا يوجد تكامل مباشر ثنائي الاتجاه بدون استخدام API للإرسال و Webhooks للاستقبال.

ثانيًا: إعدادات إدارة الـ API في لوحة التحكم

من خلال صفحة إدارة الـ API في لوحة تحكم المتجر، يمكن للتاجر إنشاء مفاتيح API لاستخدامها من قبل الأنظمة الخارجية.

خطوات إنشاء مفتاح API:

1. الدخول إلى إعدادات إدارة الـ API

2. الضغط على إضافة مفتاح API

3. اختيار الصلاحيات المطلوبة (يمكن اختيار صلاحية واحدة أو عدة صلاحيات)

4. الضغط على حفظ ليتم إنشاء مفتاح API

   

الصلاحيات المتاحة:

• عرض الطلبات

• تحديث حالة الطلبات

• قراءة المنتجات

• إضافة منتجات جديدة

• تحديث المنتجات

• تحديث المخزون

• عرض العملاء

• تحديث العملاء

• عرض السلات المتروكة

⚠️ يجب منح النظام الخارجي أقل قدر ممكن من الصلاحيات حسب الحاجة الفعلية للتكامل.

يتم استخدام مفتاح الـ API هذا من قبل المبرمج لإرسال الطلبات من النظام الخارجي إلى متجرة وفقًا لما هو موثق في صفحة الدوكيومنتيشن.

ثالثًا: إعدادات إدارة Webhooks في لوحة التحكم

توفر صفحة إدارة Webhooks إمكانية استقبال الأنظمة الخارجية للإشعارات الصادرة من متجرة عند حدوث أحداث معينة داخل المتجر.

خطوات إضافة Webhook:

1. الدخول إلى إعدادات Webhooks

2. الضغط على إضافة Webhook

3. إدخال رابط الاستقبال (Webhook URL) الخاص بالنظام الخارجي

4. اختيار نوع الحدث المطلوب

5. الضغط على حفظ

   

ملاحظات مهمة:

• كل Webhook مرتبط بحدث واحد فقط

• يمكن إضافة عدة Webhooks لنفس المتجر حسب الحاجة

• يجب أن يكون رابط الاستقبال قادرًا على استقبال طلبات POST ومعالجة البيانات المرسلة

الأحداث المتوفرة:

• إنشاء طلب

• تحديث حالة طلب

• تحديث المخزون

• إضافة منتج

• تحديث منتج

رابعًا: سيناريوهات التكامل الشائعة

1️⃣ إنشاء طلب من النظام المحاسبي الى متجرة

في حال تم إنشاء طلب بيع من داخل النظام المحاسبي:

• يقوم النظام المحاسبي بإرسال طلب إلى متجرة عبر API

• يتم إنشاء الطلب أو تحديث المخزون حسب العملية

• تقوم متجرة بخصم الكمية تلقائيًا من مخزون المتجر

👉 في هذا السيناريو لا يتم استخدام Webhooks.

2️⃣ إنشاء طلب من المتجر الإلكتروني الى النظام المحاسبي

في حال تمت عملية بيع من المتجر الإلكتروني:

• تقوم متجرة بإرسال Webhook إلى النظام المحاسبي عند حدوث الحدث (مثل إنشاء طلب)

• يستقبل النظام المحاسبي البيانات

• يتم تسجيل الطلب وخصم الكمية داخليًا في النظام المحاسبي

👉 في هذا السيناريو لا يقوم النظام المحاسبي باستدعاء API.

خامسًا: الأخطاء الشائعة في التكامل

• ❌ الاعتماد على روابط أو واجهات داخلية غير موثقة (مثل SignalR أو Hubs داخلية)

• ❌ محاولة الاستماع للأحداث بدون استخدام Webhooks

• ❌ استخدام API بدون الصلاحيات المناسبة

• ❌ افتراض وجود مزامنة تلقائية بدون إعداد Webhooks

✅ المصدر الوحيد المعتمد للأحداث هو Webhooks، والمصدر الوحيد لإرسال العمليات هو API.

✨ باتباع هذه الآلية، تضمن التكامل السلس والآمن بين المتجر وأي نظام خارجي.