ربط WooCommerce بمفاتيح REST والويب هوك التلقائي

الغرض#

تربط هذه الطريقة متجر WooCommerce بالمنصة دون أي إضافة: تنشئ مفاتيح REST في متجرك وتلصقها في بطاقة WooCommerce، فتسجّل المنصة الويب هوك تلقائياً. بعدها يتحوّل إلى طرد كل طلب جديد مؤهل (انظر الجدول أدناه) ما دام الربط فعّالاً وخيار «إنشاء الطرد تلقائياً لكل طلب» مفعّلاً (وهو الافتراضي)، وتعود حالة الشحنة إلى الطلب في متجرك.

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

• تاجر منصة تتضمن باقته «ربط المتاجر» ولديه متسع ضمن «عدد المتاجر المربوطة». والتاجر الذي أنشأته شركة توصيل لا يفتح الصفحة.
• متجر على HTTPS وبعنوان عام (يُرفض أي عنوان داخلي)، والروابط الدائمة في ووردبريس ليست «عادي/Plain».
• حساب بصلاحية مدير في ووردبريس لإنشاء المفاتيح.
• شركة توصيل متاحة لحسابك ومكان استلام فعّال، وهما إلزاميان.

خطوات الربط#

1. أنشئ مفتاح REST في ووردبريس

   في لوحة ووردبريس: WooCommerce ← الإعدادات ← متقدم ← REST API ← إضافة مفتاح. اكتب الوصف Delivery Syria، واختر في حقل «المستخدم» حساباً بصلاحية مدير (Administrator)، واختر الصلاحيات قراءة/كتابة (Read/Write)، ثم توليد مفتاح API.

2. انسخ المفتاحين

   انسخ Consumer key (يبدأ بـ ck_)، ثم Consumer secret (يبدأ بـ cs_).

3. املأ بطاقة WooCommerce

   في «ربط المتاجر» الصق رابط المتجر (مثل https://mystore.com) والمفتاحين، واختر «شركة الشحن لطلبات هالمتجر» و«مكان الاستلام لطلبات هالمتجر»، ثم اضغط «ربط ووكمرس». تفحص المنصة المفاتيح بقراءة طلب واحد، وتحفظ الربط، وتضيف الويب هوك order.created و order.updated.

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

   عند النجاح يظهر «تم ربط المتجر …» مع «تم تسجيل الـ Webhooks بالمتجر (طلب جديد + تحديث طلب).». وإن فشل تسجيل الويب هوك فالربط يبقى ويظهر تحذير «تم ربط المتجر، بس: …» وسبب الفشل تحت المتجر.

5. جرّب طلباً

   أنشئ طلباً تجريبياً في متجرك. وإن لم يصل خلال دقائق فاضغط «فحص الاتصال» ثم «سحب آخر الطلبات».

123

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

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

يظهر المتجر تحت «متاجرك المربوطة» بوسم WooCommerce واسم المتجر. وتُعامَل الطلبات هكذا:

يؤخذ الاسم والعنوان من بيانات الشحن (وإلا من بيانات الفوترة)، وتُقرأ المحافظة من حقلي المدينة والمنطقة، وإن لم تُعرف فاخترها يدوياً من سجل الطلبات. ووزن الطرد هو «الوزن الافتراضي» (1 كغ ما لم تغيّره) لأن WooCommerce لا يرسل الوزن. ويحمل الطرد رقم فاتورة بصيغة WOOC<connection_id>-<order_number>، أي WOOC ثم رقم الربط ثم شرطة (-) ثم رقم الطلب.

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

الويب هوك والتحقق من التوقيع#

عنوان الاستقبال /api/stores/woocommerce/<token> خاص بكل ربط (<token> سلسلة عشوائية خاصة به). توقّع WooCommerce الطلب في الترويسة X-WC-Webhook-Signature (Base64 لـ HMAC-SHA256 لجسم الطلب بسر الربط)، وتتحقق المنصة منه: يُعاد الخطأ 404 (Unknown store) إن كان الرمز المميّز (token) في الرابط غير معروف، والخطأ 401 (Invalid signature) إن كان التوقيع غير صحيح. وإن احتجت إضافة الويب هوك يدوياً ففي بطاقة المتجر «بيانات الـ Webhook (للإضافة اليدوية)»: رابط التسليم والسر، والحدثان order.created و order.updated. وزر «إعادة تسجيل الـ Webhooks» يحذف ما سُجّل لنفس الرابط ويعيد إنشاءه.

الفصل#

«إيقاف» يوقف الإنشاء التلقائي للطرود، و«حذف» يحذف الربط وتبقى الطرود. ولا تحذف المنصة الويب هوك من متجرك، فاحذفه من إعدادات المتجر، وألغِ مفتاح REST إن لم تعد تحتاجه.

أخطاء شائعة#

الأمان#

• لا تُتّبع التحويلات، ولا يُقبل إلا عنوان عام، وتُرسل المفاتيح مع الطلب فيلزم HTTPS.
• مفاتيح REST وسرّ الويب هوك مخزّنة مشفّرة، ولكل ربط رمز مميّز عشوائي وسرّ خاص.

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

• الربط الجديد محدود بـ 20 طلباً في الدقيقة، والاستقبال بـ 240 طلباً في الدقيقة.
• «سحب آخر الطلبات» يجلب آخر 20 طلباً.
• تعيد مهمة خلفية كل 5 دقائق معالجة الطلبات المتأخرة التي لا يتجاوز عمرها 7 أيام.
• بعض الرسائل بالعربية فقط حتى في الواجهة الإنجليزية.