الويب هوك الواردة والاستدعاءات: المتاجر وستور سيريا والشركاء

الغرض#

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

من يحتاجها وما المتطلبات#

• المطوّرون الذين يبنون إضافات للمتاجر أو أنظمة شركاء أو أدوات اختبار. معظم التجار لا يستدعون هذه العناوين أبداً: ربط المتجر من «ربط المتاجر» في لوحة التاجر يضبط كل شيء (ووكومرس وشوبيفاي يسجّلان الويب هوك بنفسيهما، وسلة وزد تعملان عبر تطبيقات المنصة).
• كل العناوين تحت /api على دومين المنصة، وتقبل JSON ولا تحتاج إلى جلسة متصفح.
• لا تُعرض الأسرار (الرموز والمفاتيح وأسرار التوقيع) في هذه الصفحة. الأمثلة تستخدم قيماً بديلة مثل YOUR_WEBHOOK_TOKEN وYOUR_SECRET؛ فأبقِ القيم الحقيقية على خادمك.

نظرة سريعة#

قواعد تنطبق عليها جميعاً#

• لا CSRF ولا جلسة. هذه المسارات ضمن مجموعة الـ API؛ يكفي المرسل العنوان وطريقة التحقق المذكورة أعلاه.
• ردّ سريع ثم عمل لاحق. تردّ نقاط نهاية المتاجر فوراً ({"ok":true}، أو {"message":"ok"} في سلة) وتنشئ الشحنة بعد إرسال الرد (عندما يكون الربط نشطاً وإنشاء الشحنات تلقائياً مفعّلاً). وتعيد مهام مجدولة محاولة معالجة كل ما بقي معلّقاً: طلبات المتاجر وطلبات سلة كل 5 دقائق، وأحداث زد كل دقيقة.
• رموز الحالة التي يراها المرسل. 200 مقبول (حتى للأحداث التي تُتجاهل)، 401 فشل التحقق، 404 رمز غير معروف، 400 حمولة غير مقروءة، 500 خطأ في المعالجة، وهو ما يدفع المرسل إلى إعادة المحاولة.
• سقف الطلبات. يخضع كل مسار تحت /api أولاً للمحدِّد العام: 60 طلباً في الدقيقة لكل عنوان IP. أما حدود المسارات الأعلى المكتوبة في الشيفرة (240 و600 وغيرهما) فلا ترفع هذا السقف، لذلك يتلقى المرسل الذي يسلّم أكثر من 60 حدثاً في الدقيقة من عنوان IP واحد الرمز 429. راجع مقال حدود الطلبات.
• التسليم المتكرر. يُعرَّف طلب المتجر بالربط ورقم الطلب في المتجر، فإذا وصل الحدث نفسه مرتين يُحدَّث الطلب المحفوظ ولا تُنشأ شحنة ثانية. ورقم الفاتورة invoice_no للشحنة هو أول أربعة أحرف من اسم المنصة بحروف كبيرة، ثم رقم الربط، ثم شرطة، ثم رقم الطلب في المتجر (مثل WOOC12-1001)؛ وشحنات زد تبدأ بـ ZID- يليها رقم الطلب في زد.
• تحقّق من التوقيع على جسم الطلب الخام. تُحسب التواقيع على البايتات كما وصلت تماماً. لا تعِد ترميز الـ JSON قبل فحصه أو تمريره.

منصات المتاجر#

ووكومرس#

عندما يربط التاجر متجره تنشئ المنصة الويب هوك داخل المتجر (الموضوعان order.created وorder.updated) بسرّ عشوائي يُحفظ لهذا الربط. عنوان التسليم هو /api/stores/woocommerce/ يتبعه رمز من 40 حرفاً. ويجب أن يحمل الطلب الترويسة X-WC-Webhook-Signature: ترميز base64 لقيمة HMAC-SHA256 لجسم الطلب بهذا السر. التوقيع الخاطئ أو الناقص يعيد 401 مع {"message":"Invalid signature"}، والرمز غير المعروف يعيد 404 مع {"message":"Unknown store"}.

حالات الطلب: الطلبات الملغاة والمستردّة والفاشلة والمحذوفة تُعتبر ملغاة؛ والطلبات المكتملة تُتخطّى (سبق شحنها)؛ وطلبات الدفع عند الاستلام (payment_method يساوي cod) والطلبات المدفوعة تتحول إلى شحنات، ومبلغ التحصيل هو إجمالي الطلب في حالة cod فقط؛ وبقية الطلبات غير المدفوعة تنتظر تحديثاً لاحقاً.

شوبيفاي#

يستخدم التطبيق المخصص العنوان /api/stores/shopify/{token}. يسجّل الربط الموضوعين orders/create وorders/updated، ويُوقَّع كل طلب في X-Shopify-Hmac-Sha256 (قيمة HMAC-SHA256 لجسم الطلب بترميز base64) بسر التطبيق الذي أدخله التاجر. أما التطبيق العام فله عنوان واحد هو /api/stores/shopify/app ويُوقَّع بسر تطبيق المنصة. يؤخذ المتجر من X-Shopify-Shop-Domain؛ فالمتجر غير المعروف يُتجاهل مع {"ok":true}، والموضوع app/uninstalled يوقف الربط مؤقتاً. وتصل مواضيع الخصوصية الإلزامية إلى /api/stores/shopify/compliance: الموضوع customers/redact يمسح الحمولة المحفوظة واسم الزبون للطلبات المذكورة في الطلب، وshop/redact يفعل ذلك لكل طلبات المتجر ويوقف الربط مؤقتاً ويزيل بيانات اعتماده (وتبقى الشحنات سجلاً للشحن)، أما بقية المواضيع فتُسجَّل فقط. وتردّ أسعار الشحن عند الدفع (/api/stores/shopify/rates) بسعر باسم Delivery Syria فقط إذا كانت دولة الوجهة SY والمحافظة معروفة والربط فعّالاً وله شركة توصيل.

حالات الطلب: الطلبات الملغاة أو التي أُبطلت دفعتها (voided) أو المستردّة تُعتبر ملغاة؛ والطلبات المنفَّذة كلياً أو جزئياً تُتخطّى؛ والطلبات المدفوعة أو المصرَّح بها (authorized) أو المدفوعة جزئياً أو بالدفع عند الاستلام تتحول إلى شحنات؛ والباقي ينتظر الدفع.

سلة#

العنوان POST /api/salla/events هو العنوان الوحيد لتطبيق المنصة في سلة. ويجري التحقق من الطلب بالترويسة X-Salla-Signature (قيمة HMAC-SHA256 لجسم الطلب الخام بترميز سداسي عشري)، أو، عند غيابها، بترويسة Authorization مساوية للسر (مع Bearer أو بدونها). وإذا لم يكن على الخادم سر مضبوط فكل طلب يُرفض بـ 401 مع {"message":"unauthorized"}. وجسم الطلب الذي ليس JSON يعيد 400 مع {"message":"invalid payload"}؛ والنجاح 200 مع {"message":"ok"}؛ وخطأ المعالجة 500، ويبقى حدث الطلب عندها غير معالَج إلى أن تعيد المهمة المجدولة محاولته.

يُسجَّل كل حدث بعد حذف الرموز منه. الحدث app.store.authorize يحفظ رموز المتجر (مشفّرة) ويحدّث ربط المتجر؛ وapp.uninstalled يمسح الرموز ويوقف الربط مؤقتاً؛ والأحداث order.created وorder.updated وorder.status.updated وorder.payment.updated وorder.cancelled تدخل مسار الطلبات؛ وبقية الأحداث تُسجَّل فقط. تُنشأ الشحنة عندما تكون حالة الطلب في سلة under_review أو in_progress ويكون الطلب بالدفع عند الاستلام أو مدفوعاً؛ أما payment_pending والمسودات فتنتظر، والملغاة تُسجَّل ملغاة، وأي حالة أخرى تُتخطّى. وافتراضياً تُؤخذ فقط الطلبات التي تُشحن عبر تطبيق المنصة نفسه؛ ويستطيع مشغّل المنصة إيقاف هذا القيد.

أما POST /api/salla/link فتستدعيه دالة التطبيق في سلة أثناء التفعيل، وليس التاجر. يحتاج الترويسة X-DS-Link-Secret وجسم طلب بصيغة JSON فيه merchant_id (أرقام فقط) وcode، وهو كود الربط الذي يأخذه التاجر من المنصة (صالح 10 دقائق). 401 تعني سراً خاطئاً؛ و422 أن الربط رُفض: رقم متجر غير صالح، أو كود غير صالح أو منتهي، أو تاجر لا يستطيع الربط (الحساب ليس تاجراً نشطاً وموثّقاً، أو لا يوجد مكان استلام نشط، أو الباقة لا تتضمن ربط المتاجر، أو بلغت الباقة حدّ المتاجر)، وتذكر رسالة الرد السبب؛ و200 ربطاً ناجحاً؛ وأي خطأ غير متوقع يعيد 500.

زد#

العنوان POST /api/zid/events (يُقبل مقطع إضافي واحد في المسار) يجب أن يحمل سرّ زد المضبوط: إما أن تساوي الترويسة X-Hook-Secret السر، أو أن يساوي اسم المستخدم وكلمة المرور في HTTP Basic الزوج المضبوط. الفشل يعيد 401 مع {"ok":false}. وعندما يربط التاجر المتجر تشترك المنصة فيه بالأحداث order.create وorder.status.update وorder.payment_status.update.

تخزّن نقطة النهاية الحدث وتردّ بـ {"ok":true}. ثم تحوّل مهمة مجدولة أحداثَ الطلبات إلى شحنات، فتعمل مباشرة بعد الرد وتتكرر كل دقيقة: يجب أن يكون الطلب بالدفع عند الاستلام أو مدفوعاً، وأن يكون المتجر مربوطاً بتاجر اختار شركة توصيل ومكان استلام، وأن يحتوي اسم طريقة الشحن افتراضياً على "delivery syria" (ويستطيع مشغّل المنصة إيقاف هذا القيد). والطلب الإلكتروني غير المدفوع ينتظر حدث الدفع.

ستور سيريا والمنصات التي تعمل بالمفتاح (قديمة)#

هذه هي واجهة «معرّف الأمان» الأقدم التي تستخدمها إضافة ستور سيريا وإضافة ووكومرس القديمة والمنصات المخصصة. بقيت من أجل هذه الجهات؛ فاستخدم واجهة التاجر (Merchant API) في التكاملات الجديدة.

• المفتاح. ينشئه تاجر المنصة في «الويب هوك والـ API» ضمن «مفاتيح الويب هوك» (ستور سيريا، إضافة ووكومرس، سلة، API) أو «منصات مخصصة» (حتى 5، لكل منها قيمة X-Platform خاصة بصيغة custom:<name>). يبدأ المفتاح بـ sk_. وعندما تُطبَّق الباقات يحتاج توليد مفتاح ستور سيريا أو إضافة ووكومرس أو سلة أو الـ API أو تجديده إلى ميزة stores في الباقة (وapi لمفتاح الـ API).
• مكان المفتاح. الطلبات POST /api/parcel/create-with-security وGET /api/parcel/list-with-security وGET /api/parcel/tracking-logs/{tracking} تأخذ Authorization: Bearer YOUR_KEY وX-Platform مساوية لنوع المفتاح، ولا تُستخدم ترويسة apiKey الخاصة بواجهة الجوال. الترويسات الناقصة تعطي 401، والمفتاح غير المعروف يعطي 403 مع Invalid credentials. أما POST /api/merchant/verify وPOST /api/secret/cheack فيأخذان المفتاح في جسم الطلب كما في الجدول.

وطلبات المحافظات المساعدة مثل GET /api/parcel/governorates موصوفة في مقال نقاط النهاية العامة المساعدة. أما تحديثات الحالة التي ترسلها المنصة إلى ستور سيريا فخارج نطاق هذه الصفحة.

شركات الشحن وبوابات الدفع#

• LFL Express، POST /api/webhooks/lfl: الترويسة X-Signature (قيمة HMAC-SHA256 لجسم الطلب بترميز سداسي عشري، مع sha256= أو بدونها) بالسر المحفوظ للشركة، واسم الحدث في X-Event أو في الحقل event ضمن جسم الطلب؛ والأحداث shipment.status_updated وshipments.created وshipments.failed. غياب السر المحفوظ يعطي 500 مع webhook not configured، والتوقيع الخاطئ 401 مع invalid signature، والـ JSON التالف 400. والتسليم المتكرر (نفس delivery_id، أو جسم طلب مطابق عندما لا يُرسل delivery_id) يُجاب بـ duplicate, already received. ويخزّن تحديث الحالة حالة الشركة على الشحنة وينقل حالة المنصة عبر جدول حالات الشركة؛ ويُتجاهل الحدث الأقدم من الحالة المخزّنة، وتحتفظ الشحنة التي صارت «تم التسليم» أو «فشل التوصيل — راجع للشركة» بحالتها في المنصة.
• شركات الشحن الأخرى، POST /api/carriers/webhook/{token} (و/{account} لحساب التاجر الخاص عند الشركة): الرمز يحدّد الشركة. يختار مشغّل المنصة طريقة التحقق من استدعاءات كل شركة؛ أما حساب التاجر الخاص فيتطلب دائماً توقيع HMAC بالسر الذي حفظه التاجر. الرمز أو الحساب غير المعروف يعطي 404، والتحقق الفاشل 401 مع invalid signature (أو مع webhook secret not configured إذا لم يكن هناك سر محفوظ)، والحدث المكرر duplicate، والشحنة غير المعروفة parcel not found مع 200.
• شام كاش، POST /api/payments/shamcash/webhook (أو /{gateway}): جسم الـ JSON هو {"encData": "..."}، رسالة مشفّرة تفكّها المنصة بالمفتاح السري للبوابة. الرسالة التي يتعذّر فكها أو انتهت صلاحيتها تعطي 400، والبوابة غير المعروفة 404. الحالة 4 تؤكد الدفعة، و3 تجعلها منتهية، و2 أو 5 تجعلانها فاشلة؛ والمرجع غير المعروف يُجاب بـ 200.
• Paymera، /api/payments/paymera/callback?ref=...: تتجاهل المنصة محتوى الطلب وتسأل Paymera عن حالة الدفع الحقيقية، فتأتي الحالة دائماً من Paymera نفسها. GET يعيد الزبون إلى الصفحة المناسبة، وPOST يردّ بـ {"ok":true}. وتسأل مهمة مجدولة (كل 10 دقائق) البوابة عن الدفعات التي بقيت معلّقة أكثر من 12 دقيقة.

أخطاء شائعة#

• استخدام مفتاح API الخاص بالتاجر على ويب هوك متجر. عناوين المتاجر لها رمزها وتوقيعها، ولا تقبل مفاتيح المنصة sk_ إلا طلبات ستور سيريا.
• إعادة ترميز جسم الطلب قبل فحص التوقيع. احسب الـ HMAC على البايتات الخام.
• طلب المتجر لا يتحول إلى شحنة. تحقق من أن ربط المتجر نشط (يُوقَف مؤقتاً بعد إلغاء التثبيت أو عند فقدان الصلاحية) ومن تفعيل إنشاء شحنة تلقائياً لكل طلب للمتجر، ومن اختيار شركة توصيل ومكان استلام للمتجر (يُسجَّل الطلب فاشلاً بملاحظة تبدأ بـ «إعداد المتجر ناقص:»)، ومن أن الطلب مدفوع أو بالدفع عند الاستلام وغير منفَّذ مسبقاً، وفي سلة وزد من أن الزبون اختار شحن المنصة.
• إرسال عدد كبير من الأحداث دفعة واحدة يعيد 429. يُسمح لعنوان IP واحد بـ 60 طلباً في الدقيقة إلى /api.
• ويب هوك ووكومرس يدوي بدون سر الربط. لا تستطيع المنصة التحقق منه فتردّ بـ 401.

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

• صفحتا ربط المتاجر والويب هوك والـ API مخصصتان لتجار المنصة (يُحوَّل التاجر الذي أنشأته شركة توصيل إلى لوحة التحكم)، وعندما تكون باقات التجار مطبّقة يحتاج ربط ووكومرس أو شوبيفاي أو سلة إلى باقة تتضمن ربط المتاجر.
• تحتاج سلة وزد إلى بيانات تطبيقيهما وأسرارهما مضبوطة على الخادم؛ وبدونها يفشل التحقق.
• تعتمد زد على سرّ مشترك: أبقِه خاصاً كأنه كلمة مرور، وغيّره إذا تسرّب.
• ملاحظة: واجهة ستور سيريا قديمة؛ فاستخدم واجهة التاجر (Merchant API) في التكاملات الجديدة.