دليل تكامل التجارة الإلكترونية مع Nama ERP

جدول المحتويات

1. مقدمة
2. نظرة عامة على الوحدة
3. منصات التجارة الإلكترونية المدعومة
4. الكيانات الأساسية
   • MAGMagentoSite
   • MagentoItemLinker
   • MagentoPriceUpdaterDoc
   • EcommerceProductConfig
   • EcommerceCategoryConfig
5. سير عمل التكامل
6. دليل الإعداد
7. البنية التقنية
   • معالجة Webhook
   • مزامنة البيانات
   • معالجة الأخطاء
8. استكشاف الأخطاء وإصلاحها
9. الدعم الفني
10. الملاحق

---

مقدمة

توفر وحدة تكامل التجارة الإلكترونية في Nama ERP ربطاً سلساً بين Nama ERP ومنصات التجارة الإلكترونية المختلفة. يغطي هذا الدليل الشامل الإعداد والتهيئة وإدارة تكاملات التجارة الإلكترونية للمستخدمين النهائيين وفريق الدعم الفني.

الفوائد الرئيسية

• دعم متعدد المنصات: الاتصال بـ Magento وShopify وSalla وBigCommerce وZid وWooCommerce وأطر التجارة الإلكترونية المخصصة
• مزامنة فورية: مزامنة تلقائية للمنتجات والأسعار والمخزون والطلبات
• تهيئة مرنة: تعيين حقول قابل للتخصيص وقواعد أعمال مرنة
• تتبع شامل: سجل مراجعة كامل ومعالجة للأخطاء

---

نظرة عامة على الوحدة

معلومات الوحدة:

• الاسم العربي: Magento Integration
• الاسم الإنجليزي: Magento Integration
• معرّف الوحدة: magento
• مسار القائمة: ims > Master Files > Magento Site

تتكون الوحدة من خمسة كيانات أساسية تعمل معاً لتوفير وظائف تكامل شاملة مع التجارة الإلكترونية:

1. MAGMagentoSite - الكيان الرئيسي لإعداد مواقع التجارة الإلكترونية
2. MagentoItemLinker - يربط أصناف Nama بمنتجات منصة التجارة الإلكترونية
3. MagentoPriceUpdaterDoc - يدير تحديثات الأسعار إلى منصات التجارة الإلكترونية
4. EcommerceProductConfig - يهيئ الإعدادات الخاصة بكل منتج
5. EcommerceCategoryConfig - يدير إعدادات التصنيفات

---

منصات التجارة الإلكترونية المدعومة

تدعم وحدة التكامل المنصات التالية:

المنصات الأساسية

• Magento (الإصداران 1.x و2.x)
• Shopify
• Salla
• BigCommerce
• Zid
• WooCommerce

منصات الشحن والخدمات اللوجستية

• OTO - تكامل منصة الخدمات اللوجستية لمزامنة كميات المخزون

المنصات المخصصة

تتيح البنية المرنة للوحدة التكامل مع أي إطار تجارة إلكترونية مخصص من خلال واجهات API وwebhooks قابلة للتهيئة.

---

الكيانات الأساسية

MAGMagentoSite

نوع الكيان: MAGMagentoSite
الاسم العربي: Magento Site
الاسم الإنجليزي: Magento Site
النوع: ملف رئيسي

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

مناطق الإعداد الرئيسية

إعدادات الاتصال

• URL: رابط موقع التجارة الإلكترونية
• Username/Password: بيانات المصادقة
• إعدادات Gateway: Client ID وClient Secret وGateway URL لـ OAuth
• إعداد API: نقاط نهاية REST API أو GraphQL
• إعداد Webhook: رابط Webhook والمفتاح السري للتحديثات الفورية

سلوك التكامل

• نوع الموقع: نوع المنصة (Magento، Shopify، Salla، إلخ)
• اسم المكامل: معرّف التكامل المخصص
• قدرات التحديث: التحكم في البيانات التي يمكن مزامنتها
• تكرار المزامنة: مدى تكرار مزامنة البيانات

معالجة الطلبات

• إعدادات استيراد الطلبات: تهيئة كيفية استيراد الطلبات من منصة التجارة الإلكترونية
• إنشاء المستندات: إنشاء تلقائي لمستندات المبيعات
• إنشاء العملاء: إنشاء عملاء تلقائياً إذا لم يكونوا موجودين
• تعيين طرق الدفع: ربط طرق دفع التجارة الإلكترونية بأنواع الدفع في Nama

مزامنة المنتجات

• إعدادات مزامنة الأصناف: التحكم في مزامنة بيانات المنتجات
• إعداد تحديث الأسعار: إدارة مزامنة الأسعار
• إدارة المخزون: مزامنة مستويات المخزون
• تحديثات حالة المنتج: إدارة حالة النشاط/عدم النشاط

مجموعات التفاصيل

يتضمن كيان MAGMagentoSite عدة مجموعات تفاصيل للإعداد الدقيق:

1. طرق الدفع (paymentMethods)

   • ربط طرق دفع التجارة الإلكترونية بأنواع الدفع في Nama
   • تهيئة أنواع حساب طرق الدفع

2. أصناف الشحن (shippingItems)

   • تعريف أصناف خدمة الشحن
   • تهيئة تعيينات طرق التوصيل

3. نسخ إلى سطور أصناف التجارة الإلكترونية (copyToEcommerceItemLines)

   • تعريف تعيينات الحقول من أصناف Nama إلى منتجات التجارة الإلكترونية
   • تحديد حقول الأصناف التي سيتم مزامنتها

4. سطور معلومات إنشاء المستندات (documentGenerationInfoLines)

   • تهيئة إنشاء المستندات التلقائي بناءً على معايير الطلب
   • تعريف قواعد الأعمال لإنشاء المستندات

5. سطور إجراءات أحداث التجارة الإلكترونية (ecommerceEventActionsLines)

   • تعريف الإجراءات الآلية التي تُطلقها أحداث التجارة الإلكترونية
   • تهيئة إجراءات الاستجابة لـ Webhook

6. سطور مستودعات التجارة الإلكترونية (ecommerceWarehouseLines)

   • ربط معرّفات مستودعات التجارة الإلكترونية بمستودعات Nama
   • تهيئة مزامنة المخزون لمتعدد المستودعات

7. سطور GraphQL (graphQLLines)

   • تهيئة استعلامات GraphQL وعمليات التحويل
   • تعريف عمليات GraphQL المخصصة

8. معايير تحديث الصنف (updateItemFor)

   • تعريف المعايير المتعلقة بموعد تحديث معلومات الصنف
   • تهيئة قواعد المزامنة الانتقائية

9. تحديث حالة الطلب (updateOrderStatusTo)

   • ربط حالات مستندات Nama بحالات طلبات التجارة الإلكترونية
   • تهيئة مزامنة حالة الطلب

10. معايير تحديث الكمية (updateQtyFor)

    • تعريف المعايير لتحديثات المخزون
    • تهيئة قواعد مزامنة الكميات

11. استعلام الأصناف الخدمية الأصلية المرتبطة لتحديث الكميات (relatedParentServiceItemsQueryForQtyUpdate)

    • استعلام SQL للعثور على الأصناف الخدمية الأصلية التي يجب تحديث كميتها
    • يتيح تتبع الكميات لمنتجات الحزم من نوع الخدمة

الإجراءات المتاحة

يوفر كيان MAGMagentoSite إجراءات عديدة لإدارة تكامل التجارة الإلكترونية:

إدارة المبيعات والطلبات

• Read Sales: استيراد طلبات المبيعات من منصة التجارة الإلكترونية
• Read Sales From Date: استيراد طلبات المبيعات من تاريخ محدد
• Read Returns: استيراد طلبات الإرجاع
• ReRead Selected Orders: إعادة محاولة استيراد طلبات محددة

إدارة المخزون

• Update All Qtys: مزامنة جميع كميات المخزون
• Retry Selected Lines: إعادة محاولة طلبات تحديث الكمية الفاشلة
• Delete Finished Requests: حذف طلبات المزامنة المكتملة

إدارة الأسعار

• Price Retry Selected Lines: إعادة محاولة طلبات تحديث الأسعار الفاشلة
• Delete Finished Price Requests: حذف طلبات مزامنة الأسعار المكتملة

إدارة الأصناف

• Item Retry Selected Lines: إعادة محاولة طلبات تحديث الصنف الفاشلة
• Delete Item Entries: إزالة إدخالات مزامنة الأصناف
• Delete Finished Item Requests: حذف طلبات مزامنة الأصناف المكتملة

إجراءات خاصة بالمنصة

• Read Salla Access Token: استرداد رمز وصول منصة Salla
• Request Token: طلب رمز مصادقة من المنصة
• Register Webhooks: إعداد إشعارات Webhook

إجراءات الصيانة

• Delete Error: إزالة إدخالات الأخطاء
• Delete Requests: حذف طلبات المزامنة

MagentoItemLinker

نوع الكيان: MagentoItemLinker
الاسم العربي: ملف ربط الأصناف بموقع ماجنتو
الاسم الإنجليزي: ملف ربط الأصناف بموقع ماجنتو
النوع: ملف رئيسي

يُنشئ كيان MagentoItemLinker الرابط الحيوي بين أصناف Nama ERP ومنتجات منصة التجارة الإلكترونية. يدير تعيينات المنتجات ويضمن تناسق البيانات عبر الأنظمة.

الحقول الرئيسية

المعلومات الأساسية

• الكود: معرّف فريد للرابط
• موقع Magento: مرجع إلى موقع التجارة الإلكترونية المرتبط
• حقول الوصف: حقول وصف متعددة للرجوع الداخلي

إعداد الربط

• الفرع/القسم/القطاع: تصنيف تنظيمي
• الشركة: ارتباط الشركة/الكيان القانوني

مجموعات التفاصيل

1. التفاصيل (details)
   • يحتوي على تعيينات الصنف إلى المنتج الفعلية
   • يربط أصناف Nama بـ SKU منتجات التجارة الإلكترونية
   • يدير تعيينات تباينات المنتج

MagentoPriceUpdaterDoc

نوع الكيان: MagentoPriceUpdaterDoc
الاسم العربي: مستند تحديث أسعار ماجنتو
الاسم الإنجليزي: مستند تحديث أسعار ماجنتو
النوع: ملف مستند

كيان MagentoPriceUpdaterDoc هو نظام قائم على المستندات لإدارة تحديثات الأسعار إلى منصات التجارة الإلكترونية. يوفر قدرات معالجة الدُفعات لمزامنة الأسعار.

الميزات الرئيسية

رأس المستند

• حقول المستند القياسية: رقم المستند والتاريخ وسير عمل الاعتماد
• مرجع موقع Magento: ربط بإعداد موقع تجارة إلكترونية محدد
• التكامل المالي: يدعم التكامل المحاسبي لتغييرات الأسعار
• معلومات العميل: يمكن أن يتضمن سياق تسعير خاص بالعميل

ميزات التسعير المتقدمة

• دعم العملات المتعددة: التعامل مع عملات مختلفة
• إدارة الخصومات: هياكل خصم معقدة
• تكامل الضرائب: حساب الضريبة ومزامنتها
• تصنيف الأسعار: دعم مستويات أسعار مختلفة

التوصيل والخدمات اللوجستية

• تكامل الشحن: حقول إدارة التوصيل
• تتبع الموقع: إدارة عناوين الفوترة والشحن
• جدولة التوصيل: خيارات التوصيل المستند إلى الوقت

مجموعات التفاصيل

1. التفاصيل (details)
   • يحتوي على بنود تحديث الأسعار الفردية
   • يحدد الأصناف وأسعارها الجديدة
   • يدير حالة تحديث الأسعار ونتائجها

EcommerceProductConfig

نوع الكيان: EcommerceProductConfig
الاسم العربي: إعدادات منتج بالمتجر الالكتروني
الاسم الإنجليزي: إعدادات منتج بالمتجر الالكتروني
النوع: ملف رئيسي

يوفر كيان EcommerceProductConfig إعداداً تفصيلياً على مستوى المنتج لتكامل التجارة الإلكترونية. يدير الإعدادات الخاصة بالمنتج وخصائصه وخيارات العرض.

مناطق الإعداد الرئيسية

تعريف المنتج

• SKU: معرّف وحدة حفظ المخزون
• مرجع الصنف: ربط بصنف Nama ERP
• موقع Magento: موقع التجارة الإلكترونية المرتبط
• نوع المنتج: نوع المنتج (بسيط، قابل للتهيئة، إلخ)

تسلسل هرمي للمنتج

• المنتج الأصلي: لتباينات المنتج والحزم
• معرّف مجموعة السمات: إعداد مجموعة سمات Magento

إدارة الطلبات

• آخر طلب مُرسل: تتبع آخر محاولة مزامنة
• حالة الطلب: حالة المزامنة الحالية

مجموعات التفاصيل

1. سطور الفئات (categoryLines)

   • يدير تعيينات فئات المنتج
   • يعالج تحديد موضع المنتج متعدد الفئات
   • إعدادات وسمات خاصة بالفئة

2. سطور السمات المخصصة (customAttributesLines)

   • يعرّف سمات المنتج المخصصة
   • يدير قيم السمات وتعييناتها
   • إعداد السمات الخاص بالمنصة

3. سطور المعرض (galleryLines)

   • الاسم العربي: سطور العرض بالمتجر الالكتروني
   • يدير صور المنتج والوسائط
   • يتحكم في عرض المنتج في منصة التجارة الإلكترونية

4. سطور سمات المنتج (productAttributesLines)

   • إعداد سمات المنتج القياسية
   • إدارة قيم السمات
   • دعم السمات متعددة اللغات

EcommerceCategoryConfig

نوع الكيان: EcommerceCategoryConfig
الاسم العربي: Ecommerce Category Config
الاسم الإنجليزي: Ecommerce Category Config
النوع: ملف رئيسي

يدير كيان EcommerceCategoryConfig إعدادات وتهيئات مستوى الفئة لمنصات التجارة الإلكترونية. يوفر التحكم في كيفية هيكلة فئات المنتجات وعرضها.

الميزات الرئيسية

إدارة الفئات

• الكود: معرّف فريد للفئة
• موقع Magento: موقع التجارة الإلكترونية المرتبط
• التسلسل الهرمي للفئات: علاقات الفئة الأصلية والفرعية

إعدادات التهيئة

• حقول الملف الرئيسي القياسية: خيارات إعداد شائعة
• أوصاف مخصصة: حقول وصف متعددة لمعلومات الفئة

مجموعات التفاصيل

1. السطور (lines)
   • الاسم العربي: التفاصيل
   • يحتوي على إعدادات تهيئة الفئة التفصيلية
   • يدير القواعد والسمات الخاصة بالفئة

---

سير عمل التكامل

1. سير عمل الإعداد الأولي

1. إنشاء إعداد MAGMagentoSite

   • تهيئة إعدادات الاتصال (URL، بيانات الاعتماد)
   • إعداد المصادقة (رموز OAuth، مفاتيح API)
   • تعريف تفضيلات المزامنة

2. تهيئة طرق الدفع والشحن

   • ربط طرق دفع التجارة الإلكترونية بأنواع الدفع في Nama
   • إعداد أصناف خدمة الشحن وطرق التوصيل

3. إعداد ربط المنتجات

   • إنشاء سجلات MagentoItemLinker
   • ربط أصناف Nama بـ SKU منتجات التجارة الإلكترونية
   • تهيئة قواعد مزامنة المنتجات

4. تهيئة تفاصيل المنتجات

   • إنشاء سجلات EcommerceProductConfig للإعدادات التفصيلية للمنتج
   • إعداد فئات المنتجات باستخدام EcommerceCategoryConfig
   • تهيئة سمات المنتج والمعارض

2. سير عمل معالجة الطلبات

1. استيراد الطلبات

   • يقرأ النظام الطلبات من منصة التجارة الإلكترونية
   • يتم التحقق من الطلبات ومعالجتها وفقاً للإعداد
   • يتم إنشاء سجلات العملاء تلقائياً عند الحاجة

2. إنشاء المستندات

   • يتم إنشاء مستندات المبيعات تلقائياً بناءً على معايير الطلب
   • يتم حجز المخزون أو تعديله وفق الإعداد
   • يتم إنشاء القيود المحاسبية إذا كان التكامل مفعلاً

3. تحديثات حالة الطلب

   • تتم مزامنة تغييرات حالة الطلب في Nama ERP مع منصة التجارة الإلكترونية
   • يتم التعامل مع تحديثات حالة الشحن والوفاء بالطلبات تلقائياً

3. سير عمل مزامنة المخزون

1. تغييرات المخزون في Nama ERP

   • تُطلق حركات المخزون طلبات المزامنة
   • يتم وضع تحديثات الكميات في قائمة انتظار لمنصة التجارة الإلكترونية

2. التحديثات الدُفعية

   • يعالج النظام تحديثات المخزون في دُفعات
   • يتم تتبع التحديثات الفاشلة وإمكانية إعادة محاولتها

3. المزامنة الفورية

   • تُطلق أحداث Webhook من منصة التجارة الإلكترونية تحديثات فورية
   • تتم مزامنة مستويات المخزون الحرجة في الوقت الفعلي

4. مزامنة كميات الحزم والأصناف الخدمية

يدعم النظام الآن تتبعاً متقدماً للكميات لمنتجات الحزم من نوع الخدمة من خلال ميزة Related Parent Service Items Query For Qty Update.

فهم التحدي

لا تتبع الأصناف الخدمية في Nama ERP الكميات عادةً لأنها تمثل منتجات غير مادية (كالضمانات والتركيبات والحزم). ومع ذلك، في منصات التجارة الإلكترونية، قد تمثل هذه الأصناف الخدمية حزم منتجات تحتاج إلى تتبع الكميات بناءً على مكوناتها المادية.

حالة الاستخدام الشائعة: تجزئة الأثاث

قد يمتلك بائع أثاث بالتجزئة:

• الأصناف المادية:

  • سرير كبير (SKU: BED-KING)
  • سرير متوسط (SKU: BED-QUEEN)
  • طاولة سرير (SKU: NIGHT-01)
  • خزانة ملابس (SKU: DRESS-01)

• الأصناف الخدمية/الحزم:

  • طقم غرفة النوم الرئيسية (SKU: ROOM-MASTER) - يحتوي على سرير كبير و2 طاولة سرير وخزانة ملابس
  • طقم غرفة النوم الضيافة (SKU: ROOM-GUEST) - يحتوي على سرير متوسط وطاولة سرير

الإعداد

لتفعيل تتبع الكمية لحزم الخدمات، هيّئ حقل relatedParentServiceItemsQueryForQtyUpdate باستعلام SQL يُرجع الأصناف الخدمية الأصلية عند تغيير كمية أحد المكونات.

مثال على الاستعلام:

-- Find all service items that contain the current physical item as a component
SELECT DISTINCT parent.id
FROM InvItem parent
INNER JOIN ItemBundleComponents bundle ON bundle.parent_id = parent.id
WHERE bundle.component_id = {item.id}
  AND parent.itemType = 'Service'
  AND bundle.item = {dimensions.item.id}

TIP

Any field accessible from the ItemDimensionsQty object is available to the query

آلية العمل

1. تغيير كمية الصنف المادي: عند تغيير كمية صنف مادي (مثلاً تحديث مخزون السرير الكبير)

2. تنفيذ الاستعلام: ينفذ النظام الاستعلام المهيأ للعثور على جميع الأصناف الخدمية الأصلية التي تحتوي على هذا الصنف المادي

3. تحديث الصنف الخدمي: لكل صنف خدمي أصلي يتم العثور عليه:

   • يتم إنشاء سجل كمية افتراضي أو تحديثه
   • يتم زيادة الكمية لتشغيل مزامنة التجارة الإلكترونية
   • تتلقى منصة التجارة الإلكترونية التحديث

4. مزامنة التجارة الإلكترونية: يتم تحديث توفر حزمة الخدمات على منصة التجارة الإلكترونية بناءً على توفر المكونات

5. سير عمل إدارة الأسعار

1. تحديثات الأسعار

   • إنشاء MagentoPriceUpdaterDoc لتحديثات الأسعار الدُفعية
   • تعريف تغييرات الأسعار وسير عمل الاعتماد
   • معالجة تغييرات الأسعار المعتمدة إلى منصة التجارة الإلكترونية

2. التسعير الديناميكي

   • حساب الأسعار في الوقت الفعلي بناءً على قوائم أسعار Nama ERP
   • دعم التسعير الخاص بكل عميل
   • تحويل العملات وحساب الضريبة

---

دليل الإعداد

إعداد موقع تجارة إلكترونية جديد

الخطوة الأولى: إعداد الموقع الأساسي

1. انتقل إلى ims > Master Files > Magento Site
2. أنشئ سجل MAGMagentoSite جديداً
3. هيّئ الإعدادات الأساسية:

   Code: [Unique site identifier]
   Name: [Descriptive site name]
   URL: [E-commerce site URL]
   Site Type: [Platform type - Magento, Shopify, etc.]

الخطوة الثانية: إعداد المصادقة

هيّئ المصادقة بناءً على منصتك:

لـ Magento:

Username: [Admin username]
Password: [Admin password]
Use GraphQL: [Enable if using GraphQL API]

للمنصات المعتمدة على OAuth (Shopify، BigCommerce):

Gateway Client ID: [OAuth client ID]
Gateway Client Secret: [OAuth client secret]
Gateway URL: [OAuth authorization URL]

للمنصات المعتمدة على الرمز (Salla، Zid):

Authorization Code: [Platform authorization code]
Zid Manager Token: [For Zid platform]
Zid Store ID: [For Zid platform]

لمنصة الشحن OTO:

Site Type: OTOUpdater
Password: [API refresh token from OTO platform]
Ecommerce Warehouse Lines: [Required - Map OTO location codes to Nama warehouses]

الخطوة الثالثة: إعدادات المزامنة

هيّئ البيانات المراد مزامنتها:

Send Items To Magento: [Enable product sync]
Link Items: [Enable item linking]
Read Orders From Date: [Starting date for order import]
Max Orders Per Read: [Batch size for order processing]
Update All Item Qtys: [Enable inventory sync]

الخطوة الرابعة: إعداد قواعد الأعمال

إعداد قواعد الأعمال:

Create Customer If Not Exist: [Auto-create customers]
Update Customer If Exist: [Update existing customer data]
Create Invoice For Returns If Invoice Not Found: [Handle returns]
Put Coupon Discount To: [Where to apply coupon discounts]
Put Header Discount In Line Discount: [Discount distribution]

تهيئة مزامنة المنتجات

إعداد ربط الأصناف

1. إنشاء سجلات MagentoItemLinker
2. في مجموعة التفاصيل، قم بتعيين:
   • كود صنف Nama → SKU التجارة الإلكترونية
   • تباينات المنتج وخياراته
   • تعيينات السمات

إعداد المنتج

1. إنشاء سجلات EcommerceProductConfig لكل منتج
2. التهيئة:
   • نوع المنتج (بسيط، قابل للتهيئة، حزمة)
   • علاقات المنتج الأصلي
   • السمات المخصصة وقيمها
   • إعدادات معرض الصور

إعداد الفئات

1. إنشاء سجلات EcommerceCategoryConfig
2. إعداد التسلسل الهرمي للفئات
3. تهيئة الإعدادات الخاصة بكل فئة

إعداد طرق الدفع

1. في MAGMagentoSite، انتقل إلى مجموعة طرق الدفع
2. أضف إدخالات للتعيين:
   • أسماء طرق دفع التجارة الإلكترونية → أنواع الدفع في Nama
   • طرق حساب الدفع
   • قواعد المعالجة الخاصة

إعداد الشحن

1. في MAGMagentoSite، انتقل إلى مجموعة أصناف الشحن
2. التهيئة:
   • أصناف خدمة الشحن
   • تعيينات طرق التوصيل
   • حسابات تكلفة الشحن

---

البنية التقنية

معالجة Webhook

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

EcommerceWebhookProcessor

تتعامل فئة EcommerceWebhookProcessor (com.namasoft.modules.magento.domain.utils.EcommerceWebhookProcessor) مع أحداث Webhook الواردة من منصات التجارة الإلكترونية:

الميزات الرئيسية:

• المعالجة الدُفعية: معالجة أحداث Webhook في دُفعات قابلة للتهيئة (افتراضياً 300 حدث)
• دعم متعدد المواقع: التعامل مع Webhooks من مواقع تجارة إلكترونية متعددة في آنٍ واحد
• ترتيب الأحداث حسب الأولوية: فرز الأحداث حسب تاريخ الإنشاء لضمان تسلسل المعالجة الصحيح
• إدارة المعاملات: معالجة كل حدث Webhook ضمن سياق معاملة خاص به
• استرداد الأخطاء: الاستمرار في المعالجة حتى في حال فشل أحداث فردية

تدفق المعالجة:

1. استرداد المواقع النشطة التي تم تفعيل تكامل Webhook فيها
2. جلب أحداث Webhook المعلقة من البوابة لكل موقع
3. فرز جميع الأحداث زمنياً عبر المواقع
4. معالجة كل حدث بشكل فردي مع معالجة الأخطاء
5. تحديث الطابع الزمني لآخر قراءة بعد المعالجة

خصائص الإعداد:

# Enable webhook processing in debug mode
run-ecommerce-webhook-in-debug=true

# Number of webhook events to read per batch
read-ecommerce-webhook-events-page-size=300

مزامنة البيانات

المزامنة الفورية

تدعم الوحدة آليات مزامنة متعددة:

1. المزامنة الدفعية (Push)

   • يُطلقها تغييرات في Nama ERP
   • إرسال التحديثات إلى منصة التجارة الإلكترونية عبر API
   • تدعم بيانات المخزون والأسعار والمنتجات

2. المزامنة السحبية (Pull)

   • استرداد مجدوَل أو يدوي من منصات التجارة الإلكترونية
   • استيراد الطلبات والعملاء والمرتجعات
   • فترات استطلاع قابلة للتهيئة

3. المزامنة القائمة على Webhook

   • إشعارات أحداث فورية من منصات التجارة الإلكترونية
   • المعالجة الفورية للأحداث الحرجة (الطلبات، الإلغاءات)
   • تقليل الحمل على استطلاع API

إدارة قائمة انتظار المزامنة

يستخدم النظام قوائم انتظار داخلية لإدارة طلبات المزامنة:

• MAGUpdateQtyRequestEntry: يدير طلبات تحديث المخزون
• MAGUpdatePriceRequestEntry: يتعامل مع مزامنة الأسعار
• MAGUpdateItemRequestEntry: يدير تحديثات بيانات المنتج

يتتبع كل إدخال في قائمة الانتظار:

• حالة الطلب (معلق، قيد المعالجة، مكتمل، فاشل)
• عدد مرات إعادة المحاولة والطابع الزمني لآخر محاولة
• رسائل الأخطاء للمحاولات الفاشلة
• مراجع الكيانات المرتبطة

معالجة الأخطاء

آليات استرداد الأخطاء

1. منطق إعادة المحاولة التلقائي

   • التراجع الأسي للطلبات الفاشلة
   • الحد الأقصى القابل للتهيئة لمحاولات إعادة المحاولة
   • إعادة المحاولة الذكية بناءً على نوع الخطأ

2. تسجيل الأخطاء والإشعارات

   • سجلات أخطاء مفصلة مع تتبع المكدس
   • إشعارات بريد إلكتروني للأخطاء الحرجة
   • تنبيهات لوحة التحكم للمشكلات التشغيلية

3. أدوات الاسترداد اليدوي

   • إجراءات "Retry Selected Lines" للطلبات الفاشلة
   • "ReRead Orders" لأخطاء استيراد الطلبات
   • أدوات تنظيف الأخطاء

أنواع الأخطاء وحلها

نوع الخطأ	الأسباب الشائعة	خطوات الحل
Authentication Failed	رموز منتهية الصلاحية، بيانات اعتماد خاطئة	استخدام إجراء "Request Token"، التحقق من بيانات الاعتماد
Network Timeout	اتصال بطيء، حمولة كبيرة	زيادة إعدادات المهلة، تقليل حجم الدُفعة
Data Validation	حقول مطلوبة مفقودة، مشكلات في التنسيق	التحقق من تعيينات الحقول، التحقق من صحة تنسيقات البيانات
Rate Limiting	طلبات API كثيرة جداً	تطبيق التحكم في معدل الطلبات، ضبط تكرار المزامنة
Concurrent Update	تعارضات الوصول المتزامن	تفعيل قفل Semaphore، المعالجة التسلسلية

---

إدارة الأخطاء

عرض الأخطاء

• استخدام سجلات أخطاء النظام لتحديد المشكلات المحددة
• مراجعة طلبات المزامنة الفاشلة
• التحقق من سجلات أحداث Webhook لمشكلات المزامنة الفورية

تنظيف الأخطاء

• استخدام إجراء "Delete Error" لإزالة إدخالات الأخطاء التي تم حلها
• استخدام إجراءات "Delete Finished Requests" لتنظيف طلبات المزامنة المكتملة
• الصيانة الدورية تمنع تراكم البيانات في النظام

الدعم الفني

أدوات التشخيص

الإجراءات المتاحة لاستكشاف الأخطاء

1. Read Sales: اختبار وظيفة استيراد الطلبات
2. Update All Qtys: إجبار مزامنة كاملة للمخزون
3. Request Token: اختبار اتصال المصادقة
4. Register Webhooks: التحقق من إعداد Webhook

تحليل السجلات

يحتفظ النظام بسجلات تفصيلية لـ:

• طلبات API واستجاباتها
• محاولات المزامنة ونتائجها
• حالات الأخطاء ومحاولات الحل
• مقاييس الأداء

جمع معلومات الدعم

عند التواصل مع الدعم الفني، قدّم:

1. إعداد الموقع:

   • تفاصيل إعداد MAGMagentoSite
   • نوع المنصة وإصدارها
   • طريقة المصادقة المستخدمة

2. تفاصيل الأخطاء:

   • رسائل الخطأ المحددة
   • توقيت وتكرار الأخطاء
   • الكيانات والعمليات المتأثرة

3. عينات البيانات:

   • طلبات نموذجية تفشل في الاستيراد
   • منتجات بها مشكلات مزامنة
   • لقطات شاشة للإعداد

أفضل الممارسات

الأمان

• تغيير مفاتيح API والرموز بشكل دوري
• استخدام HTTPS لجميع اتصالات موقع التجارة الإلكترونية
• تطبيق ضوابط الوصول المناسبة
• مراقبة سجلات المصادقة

الأداء

• جدولة العمليات الجماعية خلال ساعات الذروة المنخفضة
• مراقبة موارد النظام أثناء المزامنات الكبيرة
• استخدام المزامنة التدريجية قدر الإمكان
• صيانة دورية للطلبات المكتملة

تكامل البيانات

• التحقق الدوري من دقة المزامنة
• تطبيق قواعد التحقق من صحة البيانات
• مراقبة السجلات المكررة
• الاحتفاظ بنسخ احتياطية من الإعدادات

معلومات الاتصال

للحصول على الدعم الفني:

• مراجعة سجلات النظام ورسائل الخطأ
• استخدام الإجراءات التشخيصية لاختبار الوظائف
• توثيق حالات الأخطاء المحددة وخطوات إعادة إنتاجها
• التواصل مع مسؤول النظام أو فريق دعم Nama ERP

---

نصائح لنجاح التكامل

• ابدأ ببيئة اختبار قبل إعداد أنظمة الإنتاج
• هيّئ تكامل منصة واحدة في كل مرة
• اختبر جميع سير العمل بدقة قبل الإطلاق
• راقب المزامنة الأولية عن كثب
• احتفظ ببيانات اعتماد المصادقة آمنة ومحدّثة

اعتبارات مهمة

• احتفظ دائماً بنسخة احتياطية من إعداداتك قبل إجراء التغييرات
• اختبر المصادقة والاتصال قبل إعداد المزامنة
• راقب أداء النظام أثناء المزامنة الجماعية الأولية
• تأكد من وجود ضوابط الوصول المناسبة لمستخدمي تكامل التجارة الإلكترونية

توثيق الوحدة

يغطي هذا الدليل وحدة تكامل التجارة الإلكترونية في Nama ERP. للحصول على تفاصيل تقنية إضافية أو مراجع API أو متطلبات تكامل مخصصة، راجع مسؤول النظام أو التوثيق التقني.

---

الملاحق

أ. مرجع تعيينات الحقول

تعيينات حقول المنتج القياسية

حقل Nama ERP	حقل التجارة الإلكترونية	نوع البيانات	ملاحظات
Item.Code	SKU	String	معرّف المنتج الفريد
Item.Name1	Product Name	String	الاسم الأساسي للمنتج
Item.Description1	Short Description	Text	وصف مختصر للمنتج
Item.Description2	Description	Text	وصف تفصيلي للمنتج
Item.SalesPrice	Price	Decimal	سعر البيع العادي
Item.SpecialPrice	Special Price	Decimal	السعر الترويجي
Item.Weight	Weight	Decimal	وزن المنتج للشحن
Item.Barcode	Barcode/EAN	String	باركود المنتج
Item.Active	Status	Boolean	حالة التفعيل/التعطيل

تعيينات حقول العميل

حقل Nama ERP	حقل التجارة الإلكترونية	نوع البيانات	ملاحظات
Customer.Code	Customer ID	String	معرّف العميل الفريد
Customer.Name1	First Name	String	الاسم الأول للعميل
Customer.Name2	Last Name	String	اسم العائلة للعميل
Customer.Email	Email	Email	عنوان البريد الإلكتروني الأساسي
Customer.Mobile	Phone	String	رقم الهاتف الأساسي
Customer.TaxRegNo	VAT Number	String	رقم تسجيل الضريبة
Customer.CreditLimit	Credit Limit	Decimal	الحد الأقصى للائتمان المسموح به

ب. الإعداد الخاص بالمنصة

إعداد Magento 2.x

الإضافات المطلوبة:

• REST API مفعّل
• مصادقة OAuth مهيأة
• وحدة Webhook مثبتة (للمزامنة الفورية)

نقاط نهاية API:

Base URL: https://yourstore.com/rest/V1/
OAuth URL: https://yourstore.com/oauth/
Webhook URL: https://yourstore.com/webhooks/

الصلاحيات المطلوبة:

• Catalog (قراءة/كتابة)
• Sales (قراءة/كتابة)
• Customers (قراءة/كتابة)
• Inventory (قراءة/كتابة)

إعداد Shopify

الإعداد المطلوب:

• تطبيق خاص تم إنشاؤه بالصلاحيات المناسبة
• إشعارات Webhook مهيأة
• الإصدار 2024-01 من API أو أحدث (يُوصى بـ GraphQL API 2025-04)

إعداد API:

API Key: [From private app]
API Secret: [From private app]
Access Token: [Generated after app installation]
API Version: 2025-04 (for GraphQL)

تفاصيل تكامل Shopify GraphQL

يستخدم نظام Nama ERP واجهة GraphQL API الخاصة بـ Shopify لمزامنة البيانات والعمليات بكفاءة. يوفر هذا القسم تفاصيل تقنية لفريق الدعم لفهم تكامل Shopify GraphQL واستكشاف أخطائه.

بنية GraphQL API

إعداد نقطة النهاية:

• Base URL: https://[store-name].myshopify.com/admin/api/2025-04/graphql.json
• المصادقة: رأس X-Shopify-Access-Token
• إصدار API: 2025-04 (أحدث إصدار مستقر مع دعم GraphQL الكامل)

فئات التكامل الأساسية:

• ShopifyQraphQLApi: عميل API الرئيسي لعمليات GraphQL
• ShopifyProductsQLApi: عمليات GraphQL الخاصة بالمنتجات
• ShopifyOrdersQLApi: عمليات GraphQL لإدارة الطلبات

عمليات GraphQL المدعومة

يدعم التكامل عمليات GraphQL التالية المعرّفة في EcommerceGraphEntityOperation:

العملية	الغرض	GraphQL Query/Mutation
ProductCreate	إنشاء منتجات جديدة	productSet mutation
ProductUpdate	تحديث المنتجات الموجودة	productSet mutation with ID
ProductPriceUpdate	تحديث أسعار المنتجات	productVariantsBulkUpdate mutation
ProductSpecialPriceUpdate	تعيين أسعار خاصة/تخفيضات	productVariantsBulkUpdate with compareAtPrice
ProductQuantityUpdate	تحديث كميات المخزون	inventorySetQuantities mutation
GetOrderList	استرداد الطلبات	orders query with pagination
GetOrderById	الحصول على طلب محدد	order query by ID
GetProductById	الحصول على منتج بالمعرف	productByIdentifier query
GetProductList	سرد جميع المنتجات	products query with pagination
GetProductBySku	البحث عن منتج بالـ SKU	products query with SKU search filter
UpdateOrderStatusAndComment	تحديث ملاحظات الطلب	orderUpdate mutation

تحسين البحث بالـ SKU

مشكلات التنفيذ السابق:

• كان النظام يجلب جميع المنتجات ويبحث محلياً عن SKUs
• تسبب ذلك في تقييد API مع كتالوجات المنتجات الكبيرة
• تدهور الأداء مع الكتالوجات التي تضم أكثر من 1000 منتج

التنفيذ المحسّن الحالي:

query GetProductBySku($sku: String!, $nestedLinesSize: Int!) {
  products(first: 1, query: $sku) {
    nodes {
      title
      status
      id
      variants(first: $nestedLinesSize) {
        nodes {
          id
          sku
          title
          inventoryItem { id measurement { weight { value }}}
          price
          inventoryQuantity
        }
      }
    }
  }
}

المتغيرات:

{
  "sku": "sku:YOUR_PRODUCT_SKU",
  "nestedLinesSize": 250
}

الفوائد الرئيسية:

• استدعاء API واحد بدلاً من التصفح عبر جميع المنتجات
• بحث من جانب خادم Shopify باستخدام معامل query
• منع تقييد معدل API
• أوقات استجابة أقل من ثانية بغض النظر عن حجم الكتالوج

إعداد استعلام GraphQL

البناء الديناميكي للاستعلام: يبني النظام استعلامات GraphQL ديناميكياً بناءً على نوع العملية. كل عملية تحتوي على:

1. قالب الاستعلام/الـ Mutation
2. تعيين المتغيرات
3. اختيار الحقول بناءً على المتطلبات

تعيين حقول المتغيرات: يستخدم النظام تعليمات خاصة لتعيين حقول Nama ERP إلى متغيرات GraphQL:

• namaFieldId: يحدد مسار الحقل للاستخراج من كيانات Nama
• .emptyStringIfNull: يُرجع سلسلة فارغة إذا كانت قيمة الحقل null
• .dashIfBlank: يُرجع "-" إذا كان الحقل فارغاً أو null

مثال على إعداد المتغيرات:

map.put("sku", ShopifyQLUtils.fieldMap("productsApi.productInfo.sku"));
map.put("price", ShopifyQLUtils.fieldMap("item.currentPrice.primitiveValue"));

معالجة الأخطاء والتحكم في المعدل

تقييد المعدل:

• تعتمد Shopify GraphQL API تقييداً قائماً على التكلفة
• لكل استعلام تكلفة محسوبة بناءً على التعقيد
• يراقب النظام رأس X-Shopify-API-Call-Limit

معالجة استجابات الأخطاء:

// ShopifyQLUtils.throwsExceptionIfError checks for:
- GraphQL errors in response
- User errors in mutations
- Network and authentication errors

آلية إعادة المحاولة:

• إعادة محاولة تلقائية مع التراجع الأسي
• الحد الأقصى 3 محاولات إعادة
• معالجة خاصة لأخطاء التقييد (الحالة 429)

تكامل Webhook

موضوعات Webhook المدعومة:

• orders/create - تم تقديم طلب جديد
• orders/updated - تغيرت حالة الطلب
• orders/cancelled - تم إلغاء الطلب
• products/update - تغيرت معلومات المنتج
• inventory_levels/update - تغير مستوى المخزون

معالجة Webhook:

• تتم معالجة Webhooks بواسطة EcommerceWebhookProcessor
• الأحداث في دُفعات (افتراضياً 300 حدث)
• معالجة زمنية عبر مواقع متعددة
• عزل المعاملة لكل حدث

تفاصيل مزامنة المنتجات

تعيينات حقول المنتج:

// Core product fields synchronized
- title → Item.Name1
- description → Item.Description1
- status → Item.Active
- variants.sku → Item.Code
- variants.price → Item.SalesPrice
- variants.compareAtPrice → Item.SpecialPrice
- variants.inventoryQuantity → Item.AvailableQty

إدارة التباينات:

• كل تباين في المنتج مرتبط بـ SKU فريد
• الحفاظ على علاقات الأصل والفرع
• تتبع المخزون على مستوى التباين
• دعم التسعير لكل تباين

سير عمل معالجة الطلبات

عملية استيراد الطلبات:

1. استعلام عن الطلبات باستخدام نطاق التاريخ أو pagination بـ after_id
2. تحويل بنية طلب Shopify إلى تنسيق Nama
3. إنشاء/تحديث سجلات العملاء
4. توليد مستندات المبيعات بناءً على الإعداد
5. تحديث حالة الطلب مرة أخرى إلى Shopify

تعيين حالة الطلب:

حالة Shopify	حالة Nama	ملاحظات
pending	Draft	الدفع معلق
authorized	Approved	تم تفويض الدفع
paid	Confirmed	تم استلام الدفع
fulfilled	Delivered	تم شحن الطلب
cancelled	Cancelled	تم إلغاء الطلب
refunded	Returned	تم استرداد المبلغ كاملاً

إدارة المخزون

دعم المواقع المتعددة:

• ربط مواقع Shopify بمستودعات Nama
• تتبع مستويات المخزون لكل موقع
• دعم أوامر التحويل

استعلام تحديث المخزون:

mutation UpdateInventory($calculatedQuantityArray: [InventorySetQuantityInput!]!) {
  inventorySetQuantities(input: $calculatedQuantityArray) {
    inventoryItem {
      id
      inventoryLevels {
        edges {
          node {
            location { id name }
            available
          }
        }
      }
    }
    userErrors { field message }
  }
}

نصائح تحسين الأداء

للدعم الفني:

1. العمليات الدُفعية:

   • استخدام Mutations الجماعية للتحديثات المتعددة
   • تجميع العمليات المتماثلة معاً
   • تحديد حجم الدُفعة بـ 100 صنف

2. تحسين الاستعلام:

   • طلب الحقول المطلوبة فقط
   • استخدام pagination لمجموعات النتائج الكبيرة
   • تطبيق pagination القائم على المؤشر

3. استراتيجية التخزين المؤقت:

   • تخزين تعيينات المنتجات محلياً
   • تخزين توقيعات Webhook لإزالة التكرار
   • الاحتفاظ بذاكرة تخزين مؤقت لاستعلامات GraphQL

4. المراقبة:

   • تتبع تكاليف استدعاءات API في رؤوس الاستجابة
   • مراقبة معدل نجاح تسليم Webhook
   • تسجيل أوقات تنفيذ الاستعلام

استكشاف أخطاء GraphQL

المشكلات الشائعة وحلولها:

المشكلة	الأعراض	الحل
Rate Limiting	أخطاء 429، رسالة "Throttled"	تقليل أحجام الدُفعات، تطبيق تأخيرات
Query Timeout	لا استجابة بعد 30 ثانية	تبسيط الاستعلام، تقليل الحقول المتداخلة
Invalid SKU Search	المنتج غير موجود بالـ SKU	التأكد من تنسيق SKU: "sku:VALUE"
Mutation Errors	userErrors في الاستجابة	التحقق من الحقول المطلوبة، التحقق من أنواع البيانات
Authentication Failed	أخطاء 401	التحقق من رمز الوصول، التحقق من الصلاحيات

وضع التصحيح: تفعيل تسجيل GraphQL للتصحيح:

shopify.graphql.debug=true
shopify.graphql.log.queries=true
shopify.graphql.log.responses=true

اختبار استعلامات GraphQL: استخدم إجراء اختبار GraphQL في MAGMagentoSite:

1. انتقل إلى إعداد الموقع
2. استخدم إجراء "Test GraphQL Query"
3. أدخل نوع العملية وبيانات الاختبار
4. راجع الاستجابة والأخطاء

صلاحيات تطبيق Shopify المطلوبة

لتكامل GraphQL الكامل، تأكد من تفعيل النطاقات التالية:

المنتجات:

• read_products - قراءة معلومات المنتجات
• write_products - إنشاء/تحديث المنتجات
• read_inventory - قراءة مستويات المخزون
• write_inventory - تحديث المخزون

الطلبات:

• read_orders - استيراد الطلبات
• write_orders - تحديث حالة الطلب
• read_customers - الوصول إلى بيانات العملاء
• write_customers - إنشاء/تحديث العملاء

إضافية:

• read_locations - دعم المواقع المتعددة
• read_shipping - معلومات الشحن
• read_fulfillments - حالة الوفاء بالطلبات

إعداد Salla

الإعداد المطلوب:

• تطبيق OAuth مسجّل في بوابة شركاء Salla
• نقاط نهاية Webhook مهيأة
• الحصول على معرّف المتجر

إعداد OAuth:

Client ID: [From Salla app]
Client Secret: [From Salla app]
Redirect URL: [Your callback URL]

إعداد منصة OTO

نظرة عامة على المنصة: OTO (https://tryoto.com/) هي منصة لوجستية وشحن توفر خدمات إدارة المستودعات والمخزون. يركز تكامل Nama ERP مع OTO حصراً على مزامنة كميات المخزون إلى مستودعات OTO.

نطاق التكامل:

• مدعوم: تحديثات كميات المخزون إلى مواقع مستودعات OTO
• غير مدعوم: إنشاء المنتجات، تحديثات الأسعار، معالجة الطلبات

الإعداد المطلوب:

1. الحصول على رمز تحديث API من لوحة تحكم منصة OTO
2. تحديد رموز مواقع مستودعات OTO الخاصة بك
3. ربط مواقع OTO بمستودعات Nama ERP

إعداد API:

Site Type: OTOUpdater
URL: https://api.tryoto.com/ (or your OTO instance URL)
Password: [API refresh token from OTO platform]

تعيين المستودعات (مطلوب): في إعداد MAGMagentoSite، يجب عليك تهيئة مجموعة ecommerceWarehouseLines:

سلوك مزامنة الكميات:

• يتم إرسال التحديثات باستخدام نقطة نهاية API createInventoryOrder
• نوع الإجراء دائماً "inbound" لتحديثات الكمية
• يتم إرسال الكميات لكل موقع مستودع بناءً على SKU
• يتم تحديث كل موقع مستودع بشكل مستقل
• يتم تتبع التحديثات الفاشلة وإمكانية إعادة محاولتها

القيود:

• لا يمكن مزامنة معلومات المنتج (الاسم، الوصف، السعر)
• لا يمكن استيراد الطلبات أو تحديثها
• يدعم فقط تحديثات كميات المخزون
• يتطلب أن تكون المنتجات موجودة بالفعل في نظام OTO

ج. مرجع جداول قاعدة البيانات

جداول التكامل الأساسية

اسم الجدول	الوصف	الحقول الرئيسية
MAGMagentoSite	إعدادات مواقع التجارة الإلكترونية	id, code, url, siteType
MagentoItemLinker	تعيينات الصنف إلى المنتج	id, magentoSite, code
MagentoItemLinkerLine	روابط الأصناف الفردية	itemId, sku, magentoItemId
MagentoPriceUpdaterDoc	مستندات تحديث الأسعار	id, documentNo, issueDate
MagentoPriceUpdaterLine	بنود تحديث الأسعار	itemId, newPrice, status
EcommerceProductConfig	إعدادات المنتجات	id, item, sku, attributeSetId
EcommerceCategoryConfig	إعدادات التصنيفات	id, code, magentoSite

جداول قائمة انتظار المزامنة

اسم الجدول	الوصف	الحقول الرئيسية
MAGUpdateQtyRequestEntry	قائمة انتظار مزامنة المخزون	id, itemId, quantity, status, retryCount
MAGUpdatePriceRequestEntry	قائمة انتظار مزامنة الأسعار	id, itemId, price, status, retryCount
MAGUpdateItemRequestEntry	قائمة انتظار مزامنة المنتجات	id, itemId, status, lastAttempt
MAGSiteError	إدخالات سجل الأخطاء	id, errorType, errorMessage, timestamp

د. إعداد خصائص النظام

الخصائص الأساسية

# E-commerce Integration Properties
# ===================================

# Webhook Processing
run-ecommerce-webhook-in-debug=false
read-ecommerce-webhook-events-page-size=300

# Order Processing
max-orders-per-read=100
order-processing-batch-size=50
order-import-timeout=300000

# Inventory Synchronization
inventory-sync-enabled=true
inventory-sync-interval=300
inventory-sync-batch-size=500

# Price Synchronization
price-sync-enabled=true
price-sync-interval=600
price-sync-batch-size=200

# Error Handling
max-retry-attempts=3
retry-delay-seconds=60
error-notification-email=admin@company.com

# Performance Tuning
concurrent-sync-threads=5
api-request-timeout=30000
connection-pool-size=10

هـ. قائمة التحقق من استكشاف الأخطاء

قائمة تحقق الإعداد الأولي

• [ ] تم الحصول على بيانات اعتماد API لمنصة التجارة الإلكترونية
• [ ] تم إنشاء وإعداد سجل MAGMagentoSite
• [ ] تم اختبار المصادقة باستخدام إجراء "Request Token"
• [ ] تم تسجيل رابط Webhook (إذا كان منطبقاً)
• [ ] تم تعيين طرق الدفع
• [ ] تم إعداد طرق الشحن
• [ ] تم استيراد طلب اختبار بنجاح
• [ ] تمت مزامنة منتج اختبار بنجاح

قائمة تحقق العمليات اليومية

• [ ] التحقق من طلبات المزامنة الفاشلة
• [ ] مراجعة سجلات الأخطاء بحثاً عن مشكلات حرجة
• [ ] التحقق من دقة مستويات المخزون
• [ ] تأكيد استيراد الطلبات بشكل صحيح
• [ ] مراقبة مقاييس أداء النظام
• [ ] مسح طلبات المزامنة المكتملة

مراقبة الأداء

• [ ] أوقات استجابة API ضمن النطاق المقبول
• [ ] أحجام قوائم انتظار المزامنة قابلة للإدارة
• [ ] أداء استعلام قاعدة البيانات محسّن
• [ ] استخدام الذاكرة ضمن الحدود
• [ ] الاتصال بالشبكة مستقر

و. أفضل ممارسات التكامل

إدارة البيانات

1. التنظيف المنتظم: جدولة تنظيف دوري لطلبات المزامنة المكتملة
2. الأرشفة: أرشفة سجلات الأخطاء القديمة والمعاملات المكتملة
3. التحقق من الصحة: تطبيق قواعد التحقق من صحة البيانات قبل المزامنة
4. النسخ الاحتياطي: نسخ احتياطي منتظم لبيانات الإعداد والتعيين

اعتبارات الأمان

1. تخزين بيانات الاعتماد: استخدام آليات تخزين آمنة لبيانات الاعتماد
2. تغيير مفاتيح API: تغيير مفاتيح API والرموز بانتظام
3. التحكم في الوصول: تطبيق التحكم في الوصول المستند إلى الأدوار
4. تسجيل المراجعة: تفعيل تسجيل المراجعة الشامل
5. SSL/TLS: استخدام الاتصالات المشفرة دائماً

تحسين الأداء

1. المعالجة الدُفعية: استخدام أحجام دُفعات مناسبة للعمليات الجماعية
2. التخزين المؤقت: تطبيق التخزين المؤقت للبيانات التي يتم الوصول إليها بشكل متكرر
3. الفهرسة: ضمان الفهرسة الصحيحة لقاعدة البيانات
4. التحكم في المعدل: تطبيق التحكم في معدل طلبات API
5. المراقبة: إعداد مراقبة الأداء والتنبيهات

ز. المرجع التقني لـ Shopify GraphQL

تخزين إعداد GraphQL

بنية جدول EcommerceGraphQLLine: يتم تخزين عمليات GraphQL في مجموعة graphQLLines الخاصة بـ MAGMagentoSite:

الحقل	الوصف	مثال
operationName	معرّف العملية	GetProductBySku
graphQuery	قالب الاستعلام/الـ Mutation في GraphQL	query GetProductBySku($sku: String!)...
variablesFieldsMapASJson	تعيين JSON للمتغيرات	{"sku": {"namaFieldId": "productsApi.productInfo.sku"}}
isActive	تفعيل/تعطيل العملية	true
priority	أولوية التنفيذ	100

ذاكرة التخزين المؤقت لعمليات GraphQL

ينفذ النظام آلية تخزين مؤقت لإعدادات GraphQL:

// Cache structure in ShopifyQraphQLApi
private static Map<EcommerceGraphEntityOperation, EcommerceGraphQLLine> graphCacheMap;

فوائد التخزين المؤقت:

• تجنب عمليات البحث المتكررة في قاعدة البيانات
• تحسين أداء تنفيذ الاستعلام
• تقليل استهلاك الذاكرة

تفاصيل تنفيذ البحث بالـ SKU

الطريقة: findProductBySku الموقع: ShopifyProductsQLApi.java

public IEcommerceProduct findProductBySku(String sku) {
    // Set SKU in productInfo for query variable mapping
    this.productInfo.put("sku", "sku:" + sku);
    
    // Execute direct SKU search query
    Map<String, Object> response = apiClient.executeQueryForType(
        EcommerceGraphEntityOperation.GetProductBySku()
    );
    
    // Process response and validate SKU match
    // Returns ShopifyProductInterface or null
}

تنسيق الاستعلام: يجب تنسيق SKU كـ "sku:VALUE" لصياغة بحث Shopify.

نظام تعيين حقول المتغيرات

التعليمات الخاصة:

• التعيين القياسي: "field.subfield" - استخراج الحقل المباشر
• معالجة القيم الخالية: "field.emptyStringIfNull" - يُرجع "" إذا كانت القيمة null
• معالجة القيم الفارغة: "field.dashIfBlank" - يُرجع "-" إذا كانت القيمة فارغة

عملية التعيين:

1. تحليل إعداد المتغير من JSON
2. استخراج قيم الحقل باستخدام Reflection
3. تطبيق تحويلات القيم الخالية/الفارغة
4. إدراج القيم في متغيرات GraphQL

فئات معالجة الأخطاء

طرق خطأ ShopifyQLUtils:

public static void throwsExceptionIfError(Map<String, Object> response, String inputType) {
    // Check for GraphQL errors
    if (response.containsKey("errors")) {
        // Parse and throw appropriate exception
    }
    
    // Check for user errors in mutations
    if (response.containsKey("userErrors")) {
        // Handle mutation validation errors
    }
}

مقاييس الأداء

أوقات الاستجابة النموذجية:

العملية	متوسط الوقت	الحد الأقصى للسجلات
GetProductBySku	200-500 مللي ثانية	منتج واحد
GetProductList	500-2000 مللي ثانية	250 منتج
ProductUpdate	300-800 مللي ثانية	منتج واحد
InventoryUpdate	400-1200 مللي ثانية	100 موقع
GetOrderList	800-3000 مللي ثانية	100 طلب

حساب تكلفة API

نقاط تكلفة Shopify GraphQL:

• تكلفة الاستعلام الأساسية: 1 نقطة
• كل عقدة مطلوبة: 1 نقطة
• الاتصالات المتداخلة: النقاط × العدد المطلوب
• الحد الأقصى للدلو: 1000 نقطة
• معدل الاستعادة: 50 نقطة/ثانية

تحسين التكلفة:

• تحديد عمق الحقول المتداخلة
• استخدام اختيار حقول محدد
• تطبيق pagination لمجموعات البيانات الكبيرة
• تخزين البيانات التي يتم الوصول إليها بشكل متكرر مؤقتاً

ح. سيناريوهات التكامل الشائعة

السيناريو الأول: تجزئة متعددة القنوات

• نسخة واحدة من Nama ERP
• منصات تجارة إلكترونية متعددة (Magento، Shopify، Marketplace)
• إدارة مركزية للمخزون
• قاعدة عملاء موحدة

السيناريو الثاني: التجارة الإلكترونية بين الشركات (B2B)

• تسعير خاص بكل عميل
• إدارة حد الائتمان
• معالجة الطلبات الجماعية
• كتالوج مخصص لكل عميل

السيناريو الثالث: الوفاء بالطلبات متعدد القنوات

• مزامنة مخزون المتاجر
• طلبات الاستلام من المتجر (Click-and-collect)
• إدارة المستودعات المتعددة
• مرتجعات عبر القنوات

ط. مصفوفة توافق الإصدارات

المنصة	الإصدارات المدعومة	إصدار Nama ERP	نوع API	ملاحظات
Magento	2.3.x, 2.4.x	2023.1+	REST API V1	دعم REST الكامل
Shopify	كل الإصدارات الحالية	2023.1+	GraphQL 2025-04	بحث SKU محسّن، عمليات جماعية
Salla	الإصدار الحالي	2023.2+	REST + OAuth 2.0	دعم Webhook
BigCommerce	V2, V3 API	2023.1+	REST API	يُوصى بـ V3
WooCommerce	5.x, 6.x, 7.x	2023.1+	REST API v3	WordPress 5.8+
Zid	الإصدار الحالي	2023.3+	Custom API	يتطلب Manager Token
OTO	الإصدار الحالي	2025.10+	REST API v2	مزامنة المخزون فقط، مصادقة رمز التحديث