التكامل مع شوبيفاي (Shopify)

تشرح هذه الصفحة طريقة ربط متجر شوبيفاي بنظام نما ERP: كيف يُضبط الاتصال، وكيف تتحول طلبات شوبيفاي إلى مستندات مبيعات في نما، وكيف تُرسَل الأصناف والأسعار وكميات المخزون من نما إلى شوبيفاي.

كيف يعمل التكامل

يُعرَّف متجر شوبيفاي في نما بسجل واحد على شاشة Magento Site. هذا هو اسم الشاشة لكل المنصات وليس لماجنتو وحدها، فمتجر شوبيفاي ما هو إلا سجل Magento Site قيمة Site Type فيه هي Shopify Site. وتحتاج الشاشة إلى ترخيص magento.

يسير العمل في اتجاهين:

• الطلبات تدخل إلى نما. يسأل نما شوبيفاي عن الطلبات الجديدة، إما عند الضغط على قراءة المبيعات أو بجدولة آلية، ويحوّل كل طلب إلى مستند مبيعات بالدفاتر والتوجيهات والعملاء وسطور طرق الدفع المضبوطة على الموقع.
• الأصناف والأسعار والكميات تخرج إلى شوبيفاي. عند حفظ صنف أو تغيّر سعر أو حركة في المخزون، يرسل نما التغيير إلى شوبيفاي.

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

الاتصال بشوبيفاي

يتعامل نما مع شوبيفاي عبر واجهة GraphQL الإدارية لشوبيفاي، ولاستخدامها ضع علامة على Use GraphQL Api في الموقع. المواقع التي أُنشئت قبل وجود هذا الخيار كانت تستخدم طريقة اتصال أقدم، أما أي موقع شوبيفاي جديد فيجب أن يكون Use GraphQL Api مفعّلًا فيه دائمًا.

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

1. افتح تكامل التجارة الإلكترونية ← الملفات ← Magento Site وأنشئ سجلًا جديدًا.
2. اختر في Site Type القيمة Shopify Site.
3. ضع علامة على Use GraphQL Api.
4. اكتب في رابط عنوان المتجر ومعه https://، مثل https://my-store.myshopify.com. نما لا يضيف شيئًا قبل العنوان، فالعنوان المكتوب بلا https:// لا يتصل.
5. أدخل بيانات الاعتماد بإحدى الطريقتين:
   • برمز وصول جاهز. إن أعطاك المتجر رمز وصول (Admin API access token) فالصقه في Ecommerce Generated Application Access Token. متى امتلأ هذا الحقل استخدم نما الرمز كما هو وتجاهل اسم المستخدم وكلمة المرور.
   • بمعرّف التطبيق وسرّه. اترك Ecommerce Generated Application Access Token فارغًا، واكتب معرّف التطبيق (Client ID) في إسم المستخدم (Consumer Key) وسرّه (Client Secret) في كلمة المرور (Consumer Secret). عندها يطلب نما رمز الوصول من شوبيفاي بنفسه ويحتفظ به، ثم يطلب رمزًا جديدًا قبل انتهاء صلاحية القديم بقليل، فلا يحتاج أحد إلى تجديد شيء يدويًا.
6. اضبط إعدادات الطلبات (الدفاتر، والتوجيهات، والعملاء، وسطور طرق الدفع، والحالات) كما يشرحها دليل تكامل التجارة الإلكترونية.
7. اربط مخازنك بمواقع شوبيفاي (انظر قسم «كميات المخزون» أدناه).
8. احفظ.

قراءة الطلبات من شوبيفاي

عند تشغيل قراءة المبيعات يطلب نما من شوبيفاي الطلبات الأحدث من آخر طلب قرأه، والتي أُنشئت بعد تاريخ البداية. تاريخ البداية هو التاريخ الذي تعطيه لزر قراءة المبيعات من تاريخ، وإلا فهو النقطة التي وصلت إليها القراءة السابقة. ويُكتب هذا التاريخ في البحث بصيغة الحقل Date Pattern في الموقع. في أول قراءة استخدم قراءة المبيعات من تاريخ، لأن نما بلا تاريخ بداية يبدأ من أقدم طلب في المتجر ويجلب تاريخه كله.

تُرسَل الحالات المكتوبة في نقل فقط الأوامر التي حالتها احدي التالي إلى شوبيفاي واحدة تلو الأخرى، لذا يجب أن تكون من حالات الطلب في شوبيفاي نفسه، مثل open أو closed أو cancelled. يقرأ نما كل طلبات الحالة الأولى ثم ينتقل إلى التالية. أما الطلبات التي حالتها ضمن قراءة الأوامر كمرتجع إذا كانت إحدى الحالات الأتية فتُقرأ بعد ذلك وتدخل مردودات مبيعات. وفي كل دفعة يجلب نما عدد الطلبات المحدد في Max Orders Per Read.

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

طرق الدفع

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

ما لا يعود إلى شوبيفاي

يقرأ نما الطلبات من شوبيفاي لكنه لا يعدّلها هناك. فعند حفظ مستند المبيعات في نما تبقى حالة الطلب في شوبيفاي كما هي، وإعدادات تحديث حالة الطلب في المتجر لا تغيّر طلبات شوبيفاي. أنجز الطلب أو أغلقه أو ألغِه من داخل شوبيفاي نفسه.

إرسال الأصناف والأسعار والكميات

يجب أن يسمح الخادم بالإرسال

لا يُرسَل شيء من نما إلى أي متجر (لا أصناف ولا أسعار ولا كميات) ما لم يحتوِ ملف nama.properties على الخادم على السطر send-ecommerce-data=true.

يبحث نما عن المنتج في شوبيفاي برمز SKU. هذا الرمز هو الموجود للصنف في ملف ربط الأصناف بموقع ماجنتو، أو كود الصنف إن لم يكن له سطر في ملف الربط. اجعل رموز SKU في شوبيفاي مطابقة تمامًا لما في نما، وإلا لن يجد نما المنتج ليحدّثه.

الأصناف

عند حفظ صنف، وكان الموقع مضبوطًا على إرسال الأصناف (إرسال الأصناف إلي ماجنتو والإعدادات المرتبطة به المشروحة في الدليل العام)، يبحث نما عن رمز SKU في شوبيفاي: إن لم يجد المنتج أنشأه، وإن وجده حدّثه. ويرسل نما رمز SKU والاسم العربي للصنف وسعره الحالي.

الأسعار

تُرسَل الأسعار من مستند تحديث أسعار ماجنتو. السعر الأساسي يصبح سعر المنتج في شوبيفاي. أما سعر العرض (التخفيض) فيُرسَل على طريقة شوبيفاي: يصبح سعر العرض هو سعر البيع، ويصبح السعر العادي هو compare-at price، فيعرض شوبيفاي السعر القديم مشطوبًا بجانب السعر الجديد.

كميات المخزون

يحفظ شوبيفاي المخزون لكل موقع (متجر أو مستودع أو مركز تجهيز)، ولذلك يرسل نما الكميات لكل موقع كذلك. من هنا كان جدول ربط معرفات المخازن الإلكترونية بنما إلزاميًا مع شوبيفاي: بدونه تتوقف تحديثات الكميات برسالة خطأ.

أضف سطرًا لكل مخزن في نما تريد أن يصل رصيده إلى شوبيفاي:

العمود	ماذا تكتب فيه
المخزن	المخزن في نما.
معرف مخزن الموقع	معرّف الموقع (Location) في شوبيفاي، إما رقمًا مثل 71234567890 أو بالصيغة الكاملة gid://shopify/Location/71234567890. الرقم هو الجزء الأخير من عنوان صفحة الموقع في لوحة إدارة شوبيفاي.

تذهب كمية كل مخزن إلى الموقع المربوط به، والمخزن الذي ليس له سطر لا تُرسَل كميته. ولأن شوبيفاي يعدّ المخزون بوحدات صحيحة فإن الكميات تُرسَل أعدادًا صحيحة ويُحذف الكسر: الكمية 12.75 تُرسَل 12.

تُرسَل الكميات آليًا كلما تحرك المخزون. ولإعادة إرسال كميات كل الأصناف، كأن يكون ذلك بعد ربط المخازن أول مرة، اضغط تحديث كميات جميع الأصناف.

تعديل الاستعلامات التي يرسلها نما

كل عملية يجريها نما مع شوبيفاي (سرد الطلبات، وقراءة طلب واحد، والبحث عن منتج، وإنشاء منتج أو تحديثه، وتحديث السعر أو سعر العرض أو الكمية) تستخدم استعلام GraphQL مدمجًا. ويتيح جدول Graph QL Lines استبدال أي منها، كأن تحتاج إلى قراءة حقل إضافي من الطلب تعتمد عليه استعلامات طرق الدفع.

اترك الجدول فارغًا لتُستخدم الاستعلامات المدمجة. ولتغيير أحدها أضف سطرًا واختر نوع العملية، فيملأ نما الحقلين Graph Query وVariables Fields Map As JSON (Root Entity order/item) بالنسخة المدمجة، ثم تعدّلها كما تريد. لا يُستبدل إلا ما له سطر في الجدول، وتبقى بقية العمليات على استعلاماتها المدمجة. وهذا عمل متقدم يتولاه عادةً دعم نما.

حين يكون شوبيفاي مشغولًا

يحدّ شوبيفاي من عدد الطلبات التي يستقبلها المتجر في وقت قصير. فإذا ردّ بأن نما يرسل بسرعة زائدة، ينتظر نما ثم يعيد المحاولة، ويطيل الانتظار قليلًا في كل مرة، حتى 10 محاولات. ولا تفشل العملية إلا بعد الرفض العاشر.

رسائل قد تظهر لك

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

الرسالة	السبب	ماذا تفعل
Failed to fetch Shopify access token: {0} - {1}	رفض شوبيفاي معرّف التطبيق وسرّه. {0} و{1} هما خطأ شوبيفاي ووصفه.	راجع معرّف التطبيق في إسم المستخدم (Consumer Key)، وسرّه في كلمة المرور (Consumer Secret)، ورابط المتجر.
Failed to fetch Shopify access token: {0}	لم يتمكن نما من الحصول على رمز وصول من شوبيفاي، كأن يكون عنوان المتجر خاطئًا أو لا يمكن الوصول إليه.	تأكد أن رابط هو عنوان المتجر ومعه https://.
Failed to fetch Shopify access token: empty response	لم يُرجع شوبيفاي شيئًا عندما طلب نما رمز الوصول.	راجع رابط المتجر وأعد المحاولة.
You are using shopify graph ql, you need to link nama warehouses with ecommerce stores by the grid {0}	جرت محاولة تحديث كمية وجدول ربط معرفات المخازن الإلكترونية بنما فارغ.	املأ الجدول بمخازنك ومعرّفات مواقعها في شوبيفاي.
Wrong Location id format متبوعة بالقيمة	قيمة في معرف مخزن الموقع ليست رقمًا وليست بصيغة gid://shopify/Location/.	صحّح معرّف الموقع في الجدول.
Error while finding item with sku {0} in ecommerce site {1}, API Exception : {2}	تعذّر على نما البحث عن المنتج بهذا الرمز في شوبيفاي، و{2} هو الخطأ الأصلي.	اقرأ الخطأ في {2}، وراجع الاتصال ورمز SKU.
Failed to execute Shopify GraphQL query because of API throttling after 10 retries	ظل شوبيفاي يرفض الطلبات لكثرة ما وصله منها في وقت قصير.	أعد المحاولة لاحقًا. يمكن إعادة الطلب الفاشل من قائمته في تبويب الإحصائيات.