دليل التكامل مع Omniful

نظرة عامة (Overview)

يتكامل نظام نما مع Omniful، وهي منصة موحدة لسلسلة التوريد توفر إمكانات شاملة لإدارة المستودعات وتنفيذ الطلبات. يتيح هذا التكامل مزامنة البيانات بسلاسة بين نما و Omniful لإدارة المخزون ومعالجة الطلبات وعمليات سلسلة التوريد.

بنية التكامل (Integration Architecture)

يعمل التكامل في اتجاهين:

1. صادر (Nama ERP → Omniful): يتم إرسال البيانات الرئيسية والمعاملات من نما إلى Omniful باستخدام مسارات الكيانات (Entity Flows)
2. وارد (Omniful → Nama ERP): يتم استقبال الطلبات وتحويلات المخزون وأوامر الشراء والإيصالات من Omniful عبر webhooks

إعداد التكوين (Configuration Setup)

1. كيان إعداد Omniful

انتقل إلى تكامل التجارة الإلكترونية ← الملفات ← Omniful Configuration لإنشاء وضبط إعدادات التكامل.

الحقول المطلوبة

الحقل	الاسم العربي	الوصف
User Name	-	اسم مستخدم Omniful API
Password	-	كلمة مرور Omniful API
Seller Code	اسم البائع	معرف البائع الفريد في Omniful
Webhook Secret Key	-	المفتاح السري لمصادقة webhook
Tenant API Username	المستخدم	اسم مستخدم Tenant API للعمليات المتقدمة
Tenant API Password	كلمة المرور	كلمة مرور Tenant API
Nama API Key	-	بيانات اعتماد API للوصول إلى نما

إعداد حقول المرجع

تربط هذه الحقول معرفات Omniful بحقول محددة في كيانات نما:

الحقل	الاسم العربي	الغرض
Omniful Reference Field For Orders	حقل مرجع أومنيفل في الطلبات	ربط أوامر البيع بمعرفات الطلبات في Omniful
Omniful Reference Field For Issue Stock Transfer	حقل مرجع أومنيفل في صرف تحويل مخزني	ربط تحويلات صرف المخزون
Omniful Reference Field For Receipt Stock Transfer	حقل مرجع أومنيفل في استلام تحويل مخزني	ربط تحويلات استلام المخزون
Omniful Reference Field For Purchase Order	حقل مرجع أومنيفل في أمر شراء	ربط أوامر الشراء
Omniful Reference Field For Stock Transfer Request	حقل مرجع أومنيفل في طلب التحويل المخزني	ربط طلبات تحويل المخزون
Omniful Reference Field For Stock Receipt	حقل مرجع أومنيفل في التوريد المخزني	ربط إيصالات المخزون

الأسعار والتخفيضات والشحن

تُشكّل هذه الحقول أسطر المستندات الواردة من Omniful:

الحقل	الاسم العربي	الغرض
Item Tax Plan Id Or Code	معرف أو كود ملف سياسة ضريبة الأصناف	كود (أو معرّف) سياسة ضريبة الأصناف التي تصل أصنافها من Omniful بأسعار شاملة للضريبة. للصنف التابع لهذه السياسة يقسم نما سعر الوحدة القادم من Omniful على 1.15 — إلا إذا أرسل Omniful مبلغ ضريبة على سطر غير مُعلَّم بأنه شامل للضريبة. أصناف أي سياسة أخرى تبقى بسعر Omniful كما هو. وإن تُرك فارغًا لا يُقسَم أي سعر.
Discount Location	مكان التخفيض	عمود التخفيض في السطر الذي يستقبل تخفيض السطر القادم من Omniful (من التخفيض 1 إلى التخفيض 8). وإن تُرك فارغًا يوضع في التخفيض 3.
Shipping Item	صنف الشحن	صنف خدمي؛ لا يُحفظ الإعداد إن وُضع هنا صنف مخزني. عند ضبطه، يُضاف إلى أمر البيع الوارد الذي تحمل فاتورته في Omniful سعر شحن سطرٌ إضافي بهذا الصنف، كميته 1 وسعره سعر الشحن (مقسومًا على 1.15 إذا علّم Omniful الشحن بأنه شامل للضريبة). وإعادة قراءة الطلب تستبدل هذا السطر ولا تضيف سطرًا ثانيًا.

حالات الطلب المقبولة لكل قناة بيع (Accepted Order Statuses Per Sales Channel)

يرسل Omniful حدث طلب في كل مرة يتغيّر فيها الطلب، وافتراضيًا تُنشئ كل حالات الطلب أمر البيع أو تُحدّثه — بما فيها new_order. وهذا الجدول يُضيّق ذلك لكل قناة بيع. لكل سطر عمودان:

العمود	الاسم بالإنجليزية	ما تضعه فيه
قناة البيع (مصدر الطلب)	Sales Channel	جزء من اسم قناة البيع كما يرسله Omniful، مثل Salla. لا يهم حجم الأحرف، وينطبق السطر على كل قناة يحتوي اسمها على هذا النص. اتركه فارغًا لسطر ينطبق على الطلبات التي تصل بلا قناة بيع.
حالات الطلب المقبولة (CSV)	Accepted Order Statuses (CSV)	حالات الطلب في Omniful التي يحق لها إنشاء مستند أو تحديثه لتلك القناة، مفصولة بفواصل، كما يسمّيها Omniful تمامًا. لا يهم حجم الأحرف.

يأخذ نما أول سطر يطابق قناة بيع الطلب. فإن كانت حالة الطلب ضمن قائمة ذلك السطر حُفظ الطلب، وإلا تُخطّي الحدث بصمت ولم يُنشأ شيء. والقناة التي لا يطابقها أي سطر — وكل القنوات ما دام الجدول فارغًا — تقبل كل الحالات. وتنطبق القاعدة نفسها على طلبات تحويل المخزون (STO) التي تُنشئ صرف تحويل مخزني، وعلى إجراءات القراءة عند الطلب أدناه.

2. إعداد توليد المستندات

لكل نوع مستند سيُستقبل من Omniful، قم بضبط سطور Document Generation Info:

أنواع المستندات المدعومة

• أمر بيع (SalesOrder)
• صرف تحويل مخزني (IssueStockTransfer)
• استلام تحويل مخزني (ReceiptStockTransfer)
• طلب تحويل مخزني (StockTransferReq)
• أمر شراء (PurchaseOrder)
• توريد مخزني (StockReceipt)

حقول الإعداد

الحقل	الوصف
Entity Type	اختر نوع المستند من القائمة المنسدلة
Apply When Query	استعلام اختياري لتطبيق هذا الإعداد بشكل مشروط
Book	دفتر المستند المراد تعيينه للمستندات المُنشأة
Term	توجيه المستند المراد تعيينه للمستندات المُنشأة
Save Doc With Errors As Draft	عند التفعيل، تُحفظ المستندات التي تحتوي على أخطاء تحقق كمسودات بدلاً من الفشل

مهم

• يجب تعريف سطر إعداد واحد على الأقل حتى يعمل التكامل
• يجب إعداد Webhook Secret Key أو Nama API Key
• خمسة من حقول المرجع الستة مطلوبة (حقل مرجع أومنيفل في طلب التحويل المخزني يجوز تركه فارغًا)، ويجب أن يشير كل منها إلى حقل مخصص صالح في الكيان المعني

مزامنة البيانات الصادرة (Nama ERP → Omniful)

تصل البيانات إلى Omniful عبر إجراءات تعمل على السجل المُرسَل. أضف الإجراء إلى مسار كيان على الشاشة المناسبة، واكتب اسمه الكامل في عمود إسم العنصر في سطر التفاصيل: com.namasoft.modules.magento.utils.omniful. يليه الاسم المختصر، مثل com.namasoft.modules.magento.utils.omniful.EASendCustomerToOmniful. الاسم المختصر وحده لا يُعثر عليه — اكتبه ثم اختر الاسم الكامل من قائمة الاقتراحات. المدخلات تُكتب نصًا عاديًا. المدخل 1 دائمًا كود (أو معرّف) سجل Omniful Configuration، والمدخل الذي يشير إلى حقل يأخذ معرّف الحقل.

أي إجراء يرسل ماذا

الإجراء	يعمل على	يصل إلى Omniful كـ	المدخل 2
EASendCustomerToOmniful	عميل	عميل	الحقل الذي يحمل معرّف العميل في Omniful (إلزامي)
EASendSupplierToOmniful	مورد	مورد	—
EASendItemToOmniful	صنف	SKU لكل سطر في «مقاسات و ألوان»	حقل نعم/لا — التأشير يعني تحديثًا (إلزامي)
EASendWarehouseToOmniful	مخزن	Hub	حقل نعم/لا — التأشير يعني تحديثًا (إلزامي)
EASendSalesInvoiceToOmniful	فاتورة مبيعات	أمر بيع	الحقل الذي يحمل معرّف الطلب في Omniful (إلزامي)
EASendSalesQuotationToOmniful	عرض أسعار	أمر بيع	الحقل الذي يستقبل معرّف الطلب في Omniful (إلزامي)
EASendReturnInvoiceToOmniful	مردودات مبيعات	مرتجع على الطلب الأصلي	الحقل الذي يشير إلى المستند الذي أُرسل منه الطلب (إلزامي)
EASendPurchaseOrderToOmniful	أمر شراء	أمر شراء	—
EASendStockTransferReqToOmniful	طلب تحويل مخزني	أمر تحويل مخزني (STO)	حقل نعم/لا — التأشير يعني تحديثًا (إلزامي)
EASendStockTransferReqAsPurchaseOrderToOmniful	طلب تحويل مخزني	أمر شراء إلى الـ Hub المستلم	الحقل الذي يحمل المورد (اختياري)
EASendIssueStockTransferToOmniful	صرف تحويل مخزني	أمر شراء إلى الـ Hub المستلم	الحقل الذي يحمل المورد (اختياري)

الإنشاء أو التحديث — كيف يقرر كل إجراء

• بحقل معرّف. العميل وفاتورة المبيعات وعرض الأسعار تُنشأ في Omniful ما دام الحقل المذكور في المدخل 2 فارغًا، ويُكتب المعرّف الذي يعيده Omniful في ذلك الحقل. في العميل وفاتورة المبيعات يجعل الحقلُ الممتلئ التشغيلَ التالي يرسل تحديثًا.
• بحقل نعم/لا. الصنف والمخزن وطلب التحويل المخزني (كأمر تحويل) ترسل تحديثًا إذا كان حقل نعم/لا في المدخل 2 مؤشَّرًا، وإنشاءً فيما عدا ذلك. استخدم علامة تُؤشَّر بعد أن يُرسَل السجل، مثل حقل «اعتُمد من قبل».
• بحقل المرجع في الإعداد. أمر الشراء وطلب التحويل المخزني (كأمر شراء) وصرف التحويل المخزني تقرأ حقل المرجع المحدد في Omniful Configuration — حقل مرجع أومنيفل في أمر شراء، وحقل مرجع أومنيفل في طلب التحويل المخزني، وحقل مرجع أومنيفل في صرف تحويل مخزني. الحقل الفارغ يعني إنشاءً، ويُكتب فيه معرّف أمر الشراء الذي يعيده Omniful.
• المورد يُنشأ دائمًا، ومردودات المبيعات ترسل دائمًا مرتجعًا جديدًا.

ما الذي يرسله كل إجراء

• العميل — الاسم العربي كاسم أول، والاسم الإنجليزي كاسم أخير، والبريد الإلكتروني، والجوال، وتليفون 1 كرقم بديل، والنوع، وتاريخ الميلاد، وعنوان الاتصال (تُفترض الدولة المملكة العربية السعودية إذا خلا العنوان منها)، وجواز السفر إن وُجد.
• المورد — الكود والاسم والبريد الإلكتروني والجوال.
• الصنف — كل سطر في جدول مقاسات و ألوان للصنف يصبح SKU واحدًا، ويُستخدم كوده كودًا للـ SKU وباركودًا له معًا. الصنف الذي ليس له أسطر مقاسات وألوان لا يُرسل شيئًا. يكون الـ SKU live ما لم يكن الصنف مؤشَّرًا عليه منع الاستعمال. تُرسل الـ SKUs الجديدة 50 في كل دفعة.
• المخزن — كود المخزن يصبح كود الـ Hub في Omniful. كل مستند يجد الـ Hub لاحقًا بهذا الكود، فأبقِ الاثنين متطابقين.
• فاتورة المبيعات / عرض الأسعار — كود المستند كاسم مستعار للطلب (order alias)، والمخزن كـ Hub، والعميل، وعنوانا الفاتورة والشحن، والأسطر (السعر والخصم والضريبة والصافي)، والإجماليات، وطريقة الدفع في أول سطر دفع. كود عرض الأسعار مهم في طريق العودة: الطلب الذي يرسله Omniful لاحقًا بهذا الكود كاسم مستعار يُربط بعرض الأسعار.
• مردودات المبيعات — صنف كل سطر وكميته وسعره وخصمه وصافيه، مع ملاحظات السطر كسبب للإرجاع.
• أمر الشراء — المورد، والمخزن كـ Hub، والأسطر بسعر الوحدة، والملاحظات، والعملة.
• طلب التحويل المخزني (كأمر تحويل) — الأسطر، والمخزن كـ Hub المصدر، وإلى مخزن كـ Hub الوجهة.
• طلب التحويل المخزني / صرف التحويل المخزني (كأمر شراء) — الأسطر والمورد من المدخل 2، ويُستلم في إلى مخزن (الطلب) أو إرسال الي مخزن (صرف التحويل).

تُرسل الكميات دائمًا بالوحدة الأساسية للصنف، وبأعداد صحيحة.

مزامنة البيانات الواردة (Omniful → Nama ERP)

نقطة نهاية Webhook

قم بإعداد Omniful لإرسال webhooks إلى نقطة نهاية webhook الخاصة بنما للأحداث التالية:

الأحداث المدعومة

1. أحداث الطلبات (Order Events)

   • sto.request-approve.event ← ينشئ طلب تحويل مخزني عند اعتماد طلب STO في Omniful (مرة واحدة لكل طلب؛ والحدث المكرّر لا يُنشئ شيئًا)
   • order.* مع type: "sto" ← ينشئ طلبات تحويل مخزني أو صرف تحويل مخزني
   • order.* (غير STO) ← ينشئ أوامر بيع

2. أحداث الشراء (Purchase Events)

   • purchase.* ← ينشئ أوامر شراء

3. أحداث GRN

   • grn.* ← ينشئ توريدات مخزنية أو استلام تحويل مخزني

منطق إنشاء المستندات

أوامر البيع

• تُنشأ عند استقبال أحداث order (من النوع غير STO) بأي حالة يقبلها جدول حالات الطلب المقبولة لكل قناة بيع — ومع جدول فارغ، كل الحالات
• الحدث اللاحق للطلب نفسه في Omniful يُحدّث أمر البيع الذي يحمل معرّف طلبه في Omniful بدل إنشاء أمر ثانٍ
• يُكتب اسم قناة البيع في Omniful في حقل الوصف 6
• تربط معلومات العميل وعناوين الفوترة/الشحن وأصناف الطلب
• تربط بعروض الأسعار الموجودة إذا تم توفير order_alias

عمليات تحويل المخزون

• طلب تحويل مخزني: يُنشأ لطلبات STO بحالة "new_order"
• صرف تحويل مخزني: يُنشأ لطلبات STO بحالة ≠ "new_order"، مع مراعاة جدول الحالات المقبولة
• استلام تحويل مخزني: يُنشأ من أحداث GRN عند وجود صرف تحويل مخزني مطابق

أوامر الشراء

• تُنشأ من أحداث purchase
• تتضمن معلومات المورد وتفاصيل المستودع وأصناف الشراء

التوريدات المخزنية

• تُنشأ من أحداث GRN عند عدم وجود صرف تحويل مخزني مطابق
• تربط بأوامر الشراء الموجودة عبر مرجع entity_id

معالجة محتوى Webhook

يقوم معالج webhook بما يلي:

1. التحقق من صحة المفتاح السري لـ webhook مقابل الإعداد
2. تحليل محتوى JSON لاستخراج نوع الحدث والبيانات
3. توجيه الحدث إلى طريقة إنشاء المستند المناسبة
4. ربط بيانات Omniful بكيانات نما
5. حفظ المستندات وفقاً لإعداد Document Generation Info
6. تحديث حقول المرجع بمعرفات Omniful للمزامنة المستقبلية

ولرؤية ما أرسله Omniful بالضبط، اضبط log-omniful-requests=true في nama.properties: عندها يُكتب محتوى كل webhook في سجل الخادم.

قراءة الطلبات من Omniful عند الطلب

الـ webhook هو الطريق المعتاد لوصول الطلبات. وثلاثة إجراءات تسحب الطلبات من Omniful بدلًا منه — للطلبات التي فاتت الـ webhook (مثلًا أثناء توقف النظام)، أو لفترة سابقة، أو لتحديث طلب واحد. الثلاثة تحفظ الطلب تمامًا كما يحفظه webhook الطلبات: تُطبَّق حالات الطلب المقبولة في الإعداد، وأسطر توليد المستندات (الدفتر والتوجيه)، والعميل، والمخزن، والأسطر، والعناوين، وأمر البيع الذي يحمل نفس معرّف الطلب في Omniful يُحدَّث بدل أن يتكرر. كل طلب يُحفظ وحده، فلا يُلغي طلبٌ معطوب بقيةَ الطلبات.

تتبع هذه الإجراءات قاعدة الاسم الكامل نفسها التي تتبعها إجراءات الإرسال، والمدخل 1 هنا أيضًا كود (أو معرّف) Omniful Configuration. يتوقف التشغيل إذا لم يُعثر على الإعداد أو كان حقل مرجع أومنيفل في الطلبات فيه فارغًا.

الإجراء	استخدمه لـ	شغّله من
EAReadOmnifulOrders	سحب كل الطلبات في حالة ونطاق تاريخ	مهمة مجدولة — وفق جدول كشبكة أمان، أو عبر تشغيل الان
EAReadOmnifulOrdersByIds	سحب طلبات بعينها بأرقامها في قناة البيع	مهمة مجدولة عبر تشغيل الان
EAReReadOmnifulOrder	تحديث الطلب الذي وراء السجل الذي يعمل عليه المسار	مسار كيان على أمر البيع

مدخلات EAReadOmnifulOrders:

#	المدخل	المعنى
2	Order Status	حالة طلب في Omniful، تُمرَّر كما هي. الفراغ يقرأ كل الحالات.
3	Created From (yyyy-MM-dd)	الطلبات المنشأة في هذا التاريخ أو بعده فقط، مثل 2026-10-01.
4	Created To (yyyy-MM-dd)	الطلبات المنشأة حتى هذا التاريخ فقط.
5	Allow Update (true/false)	true يعيد قراءة الطلبات الموجودة في نما ويحدّثها. الفراغ أو false يقرأ الجديدة فقط.

يطلب من Omniful مئة طلب في كل مرة، صفحةً بعد صفحة، حتى تعود صفحة بأقل من ذلك.

مدخلات EAReadOmnifulOrdersByIds:

#	المدخل	المعنى
2	Sales Channel Order IDs (CSV)	أرقام الطلبات كما تعرفها قناة البيع، مفصولة بفواصل، مثل 100045, 100046. إلزامي — الفراغ يفشل بالرسالة "No order IDs provided".
3	Allow Update (true/false)	كما سبق.

رقم الطلب الذي لا يعرفه Omniful يُحسب فاشلًا. وينتهي الإجراءان بالتحذير "Saved N order(s), M failed. Failed order aliases: ..." الذي يسمّي الطلبات التي تعذّرت قراءتها.

EAReReadOmnifulOrder يأخذ معرّف الطلب في Omniful من السجل الذي يعمل عليه. المدخل 2 هو معرّف الحقل الذي يحمله — في أمر البيع هو الحقل نفسه المحدد في حقل مرجع أومنيفل في الطلبات. المدخل الفارغ أو الحقل الفارغ يُفشل التشغيل ("No order ID field provided" / "No order ID provided"). لا يوجد فحص «موجود في نما مسبقًا»: يُقرأ الطلب من جديد دائمًا.

رسائل هذه الإجراءات وعناوين مدخلاتها ليس لها نص عربي، فتظهر بالإنجليزية على الشاشات العربية أيضًا.

ربط البيانات (Data Mapping)

ربط بيانات العميل

حقل نما	حقل Omniful
Name1	first_name
Name2	last_name
Contact Info → Email	email
Contact Info → Mobile	mobile
Gender	gender
Birth Date	date_of_birth
Contact Info → Address	address object
Passport Details	documents array

ربط بيانات الأصناف

حقل نما	حقل Omniful
Size/Color Code	sku_code
Item Name	name
Code + Color	description
Prevent Usage	status ("live"/"un_sync")
Base UOM	uom
Net Purchase Value	cost
Current Price	selling_price, retail_price

ربط بيانات الطلبات

حقل نما	حقل Omniful
ID	order_id
Code	order_alias
Warehouse Code	hub_code
Customer ID	customer.id
Billing Address	billing_address
Shipping Address	shipping_address
Order Items	order_items array
Payment Method	payment_method

معالجة الأخطاء (Error Handling)

أخطاء إنشاء المستندات

عند مواجهة أخطاء أثناء معالجة webhook:

1. الحفظ كمسودة: إذا كان خيار "Save Doc With Errors As Draft" مفعّلاً في الإعداد، يُحفظ المستند كمسودة
2. رمي الاستثناء: إذا كان حفظ المسودة معطّلاً، تطرح العملية استثناءً وتُعيد استجابة خطأ

متطلبات التحقق

قبل المعالجة، يتحقق النظام من:

• وجود إعداد Omniful وضبطه بشكل صحيح
• تعريف سطور Document Generation Info
• إعداد حقول المرجع المطلوبة
• تطابق المفتاح السري لـ webhook مع الإعداد

عملاء API

يستخدم التكامل نوعين من عملاء API:

OmnifulSalesChannelAPIClient

• يُستخدم للعمليات المتعلقة بالعملاء والطلبات
• يتعامل مع نقاط نهاية API لقناة البيع
• يدير إنشاء العملاء وتحديثهم

OmnifulTenantAPIClient

• يُستخدم لإدارة المستودعات وعمليات المخزون
• يتعامل مع نقاط نهاية API على مستوى Tenant
• يدير الأصناف والمستودعات وعمليات سلسلة التوريد