ربط Shopify: تطبيق مخصص أو التطبيق العام

الغرض#

هناك طريقتان لربط Shopify. الطريقة اليدوية من صفحة «ربط المتاجر» متاحة وتعمل بتطبيق تنشئه أنت (Dev Dashboard أو Custom App قديم). أما التطبيق العام (التثبيت من Shopify أو زر «ربط بضغطة») فهو جزئي: لا يعمل إلا بعد أن يضبط مدير المنصة بيانات تطبيق Shopify على الخادم. في الحالتين تتحوّل الطلبات إلى طرود وتعود الحالة إلى Shopify.

من يستطيع استخدامها وما الذي تحتاجه#

• تاجر منصة تتضمن باقته «ربط المتاجر» ولديه متسع ضمن «عدد المتاجر المربوطة»، وشركة توصيل متاحة ومكان استلام فعّال، وهما إلزاميان. والتاجر الذي أنشأته شركة توصيل لا يفتح الصفحة.
• حساب صاحب المتجر في Shopify، فيجب أن يُنشأ تطبيق Dev Dashboard في المؤسسة نفسها التي فيها المتجر.
• الصلاحيات التي تعرضها الصفحة: read_orders و write_orders و read_merchant_managed_fulfillment_orders و write_merchant_managed_fulfillment_orders و write_shipping.

خطوات الربط اليدوي#

1. أنشئ التطبيق في Dev Dashboard

   من dev.shopify.com وبحساب صاحب المتجر: اختر Apps ثم Create app، والاسم Delivery Syria.

2. اختر الصلاحيات وأصدر النسخة

   في Versions اختر الصلاحيات المذكورة أعلاه ثم Release.

3. ثبّت التطبيق على متجرك

   اضغط Install app على متجرك ووافق على الصلاحيات.

4. الصق Client ID ثم Client secret

   من Settings انسخ Client ID ثم Client secret. في «ربط المتاجر» وتبويب «تطبيق Dev Dashboard (جديد)» الصقهما مع اسم المتجر بصيغة mystore.myshopify.com، واختر شركة الشحن ومكان الاستلام، ثم اضغط «ربط شوبيفاي».

5. تحقق من النتيجة

   تفحص المنصة الاتصال وقراءة الطلبات، وتحفظ الربط، وتسجّل الويب هوك orders/create و orders/updated. عند النجاح تظهر «تم تسجيل الـ Webhooks بشوبيفاي (طلب جديد + تحديث طلب).». وإن فشل التسجيل بقي الربط مع تحذير، ويُعاد التسجيل بزر «إعادة تسجيل الـ Webhooks» بعد معالجة السبب.

123

1. شاهد طلبات هذا المتجر
2. شركة التوصيل لطلبات المتجر
3. مكان الاستلام الافتراضي

طرق أخرى للربط#

• Custom App قديم (shpat): إن كان لديك تطبيق منشأ من لوحة المتجر قبل 2026 فاستعمل تبويب «Custom App قديم (shpat)» والصق Admin API access token (يبدأ بـ shpat_) وAPI secret key، بالصلاحيات نفسها.
• «ربط بضغطة»: يظهر نموذجه في أعلى بطاقة Shopify فقط إذا ضُبط التطبيق العام على الخادم. اكتب اسم المتجر واختر الشركة ومكان الاستلام، فتنتقل إلى Shopify للموافقة ثم تعود فيكتمل الربط وأنت مسجّل الدخول، ويظهر المتجر بوسم «— تطبيق».
• التثبيت من Shopify: بعد الموافقة تصل إلى صفحة تسجّل فيها دخولك بحساب التاجر (البريد الإلكتروني أو رقم الجوال) وتختار الشركة ومكان الاستلام وتؤكد، والرابط صالح 30 دقيقة. وتُسجَّل الويب هوك على /api/stores/shopify/app مع app/uninstalled، وحذف التطبيق من المتجر يوقف الربط.

النتيجة المتوقعة#

الوزن من أوزان الأصناف وإلا فالوزن الافتراضي. وعند إنشاء الطرد تُنشأ Fulfillment برقم التتبع واسم الشركة Delivery Syria ورابط تتبع، ويتلقى الزبون إشعاراً من Shopify. وإن لم يوجد Fulfillment Order مفتوح ظهرت رسالة «ما في Fulfillment Order مفتوح للطلب بشوبيفاي…». وتُرسل بعد ذلك الأحداث: تعيين المندوب أو إعادة جدولة التوصيل out_for_delivery، والتسليم الكامل أو الجزئي delivered، وفشل التوصيل failure، والوصول إلى المستودع confirmed.

التحقق من التوقيع: ترسل Shopify الترويسة X-Shopify-Hmac-Sha256 (Base64 لـ HMAC-SHA256 لجسم الطلب) بسرّ التطبيق، أي Client secret أو API secret key. والطلب الخاطئ يُرفض بـ HTTP 401 (Invalid signature).

سعر الشحن في صفحة الدفع#

مع التطبيق العام تسجّل المنصة طريقة شحن «Delivery Syria» وتطلب Shopify سعرها من العنوان /api/stores/shopify/rates وقت الدفع. تُعرض الطريقة (DS_STANDARD) بسعر محسوب كما في إنشاء الطرد فقط إذا تحققت الشروط التالية: الوجهة سوريا، والمحافظة معروفة، والربط فعّال وفيه شركة توصيل، والسعر أكبر من صفر، ولعملة المتجر سعر صرف. وإن لم تدعم خطة Shopify الأسعار المحسوبة لم تُسجَّل الطريقة وبقيت الطلبات تصل عادياً.

طلبات الخصوصية#

يقبل العنوان /api/stores/shopify/compliance الطلبات الموقّعة توقيعاً صحيحاً: customers/redact يمسح بيانات الطلبات المذكورة واسم الزبون، وshop/redact يوقف الربط ويحذف بيانات الاعتماد ويمسح بيانات الطلبات المخزّنة. وتبقى الطرود سجلاً للشحن، أما customers/data_request فيُسجَّل فقط.

أخطاء شائعة#

الحدود والصلاحيات#

• الربط بالنموذج اليدوي (تبويب Dev Dashboard أو التبويب القديم) محدود بـ 20 طلباً في الدقيقة؛ وفي صفحة التطبيق العام تسجيل الدخول محدود بـ 5 في الدقيقة والتأكيد بـ 10؛ واستقبال الويب هوك محدود بـ 240 في الدقيقة. وتُفحص توقيعات ويب هوك الطلبات وحذف التطبيق والخصوصية، أما استدعاء احتساب سعر الشحن عند الدفع فيُرفض إن كان توقيعه غير صحيح، ولا تكون الترويسة إلزامية فيه.
• بيانات الاعتماد والسرّ مخزّنة مشفّرة، وفي تطبيق Dev Dashboard يُجدَّد التوكن (24 ساعة) تلقائياً.
• رابط التتبع المرسل إلى Shopify يفتح صفحة التتبع في موقع المنصة للطرد المعني، وليس صفحة الطرد العامة التي تتلقاها سلة.
• صفحات التطبيق العام وكثير من الرسائل بالعربية فقط، ومنها الرسالتان المعلَّمتان أعلاه: «شوبيفاي رفض تسجيل Webhooks الطلبات (403)…» و«تطبيق شوبيفاي مو مفعّل على السيرفر».