ربط متجر زد عبر OAuth

الغرض#

يُربط متجر زد عبر تطبيق Delivery Syria بآلية OAuth: توافق على الوصول من لوحة زد، فيتحوّل بعدها إلى طرد كل طلب في زد تكون طريقة شحنه Delivery Syria وكان مؤهلاً (انظر الجدول أدناه)، وتعود حالة الشحنة إلى زد.

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

• حساب تاجر فعّال وموثّق وله ملف تاجر فعّال، مع تسجيل الدخول إليه. وبطاقة زد موجودة في «ربط المتاجر»، وهي مغلقة أمام التاجر الذي أنشأته شركة توصيل.
• مكان استلام فعّال واحد على الأقل، وإلا ترفض المنصة الربط.
• رصيد في المحفظة لتتحول الطلبات إلى طرود: يمكنك الربط بلا رصيد، لكن الطرد ينتظر شحن الرصيد ويكتمل تلقائياً بفحص الرصيد الذي يجري كل ساعة، وإن بقي الرصيد غير كافٍ بعد 24 ساعة أُلغي الطرد.
• طريقة شحن اسمها Delivery Syria في زد: يجب أن يحتوي اسم طريقة الشحن في الطلب على «Delivery Syria»، وإلا فشل الطلب، إلا إذا سمح مدير المنصة بكل الطلبات.
• بيانات تطبيق زد تُعدّ على المنصة بمعرفة مدير المنصة.

خطوات الربط#

1. افتح بطاقة زد

   في «ربط المتاجر» اضغط «ربط متجر زد» (أو «إعادة الربط بزد» إن كان المتجر مربوطاً). تُفتح صفحة بالإنجليزية فقط عنوانها «Connect your Zid store to Delivery Syria» تعرض الحساب الذي سيُربط المتجر به. وإن كان رصيدك صفراً تحذّرك بأن طلبات زد ستُحفظ لكنها لن تتحول إلى شحنات حتى تشحن المحفظة.

2. اضغط «Connect my store»

   تنقلك الصفحة إلى زد لتوافق على الوصول.

3. وافق في زد

   بعد الموافقة تحفظ المنصة التوكنات مشفّرة وتشترك في أحداث الطلبات order.create و order.status.update و order.payment_status.update. تظهر صفحة «Your store is connected» وتعيدك إلى لوحة زد بعد 5 ثوانٍ.

4. حدّد شركة التوصيل ومكان الاستلام

   في بطاقة زد اختر شركة الشحن ومكان الاستلام ثم «حفظ إعدادات زد». وإلى أن تفعل تفشل الطلبات برسالة تبدأ بـ «إعداد المتجر ناقص:»، وبعد الحفظ تُعاد معالجتها تلقائياً.

5. راجع الطلبات

   تعرض البطاقة «آخر طلبات زد» (آخر 8): رقم الطلب والزبون ونتيجته. وللطلب الذي أُنشئ طرده تظهر حالته في المنصة والحالة التي يجب أن تكون عليها في زد وحالته الحالية في زد، وزر «أرسل الحالة لزد الآن» يعرض ردّ زد.

123

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

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

تُعالج المنصة أحداث زد كل دقيقة وفور وصولها:

الوزن مجموع أوزان المنتجات وبحد أدنى 1 كغ. وتُستنتج المحافظة من المدينة والعنوان. وللطلب الفاشل في البطاقة حقل «تصحيح العنوان» وزر «أعد المحاولة»، وزر «أعد محاولة كل الطلبات الفاشلة». وإذا أُلغي الطلب في زد بعد إنشاء الطرد فلا يُلغى الطرد، وتظهر ملاحظة تطلب إلغاءه يدوياً.

تُرسل الحالة إلى زد بعد كل تغيّر: الوصول إلى المستودع أو النقل أو الفرع ready، وتعيين مندوب التوصيل أو إعادة جدولته indelivery، والتسليم الكامل أو الجزئي delivered. وترسل المنصة الحالة الجديدة مباشرة، فإن رفضت زد القفز بين الحالات أعادت المحاولة مرحلة بعد مرحلة: preparing ثم ready ثم indelivery ثم delivered، مع تخطي المراحل التي بلغها الطلب أصلاً. وغير ذلك، كالإرجاع، لا يُرسل. وتفحص مهمة كل 5 دقائق الطرود المرسلة في آخر 30 يوماً وتعيد إرسال ما اختلف.

صلاحية الربط وإعادة الربط#

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

أخطاء شائعة#

تظهر هذه الرسائل بلغة الواجهة المختارة: بالعربية في الواجهة العربية وبالإنجليزية في الواجهة الإنجليزية.

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

• أحداث زد تُقبل فقط مع سرّ مشترك، في الترويسة X-Hook-Secret أو بمصادقة HTTP Basic، وإلا HTTP 401. والتوكنات مخزّنة مشفّرة، وقيمة state مرتبطة بجلستك تحمي من الربط بحساب غيرك.
• لا يُحتسب متجر زد ضمن «عدد المتاجر المربوطة»، ولا يظهر في قائمة «متاجرك المربوطة».
• تعالج كل دفعة حتى 50 طلباً من الطلبات المعلّقة التي لم تبلغ محاولاتها 30 محاولة، وزر «أعد المحاولة» يعيد الطلب الفاشل إلى الانتظار ويصفّر العدّاد.
• بعض النصوص بالعربية فقط حتى في الواجهة الإنجليزية، وهي أسباب فشل الطلبات في بطاقة زد وأزرار «حفظ إعدادات زد» و«أرسل الحالة لزد الآن» و«جدّد الآن». أما صفحتا الربط والتأكيد فبالإنجليزية فقط.