Lorixen.
AR

Webhooks في زد: إرسال الطلبات الجديدة إلى نظامك الداخلي

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

متى تحتاج Webhook ومتى يكفي تطبيق جاهز

متجر قطع غيار سيارات على زد يملك نظام مخزون داخلياً في المستودع، فيه مواقع الرفوف وكميات كل قطعة. حين يُطلب منتج من المتجر، يريد أن يُخصم من المخزون الداخلي فوراً، وأن تظهر للعامل في المستودع ورقة تجهيز برقم الرف. لا يوجد تطبيق جاهز يعرف نظامه الخاص، فهنا يأتي دور Webhook.

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

الحالة الأنسب
برنامج محاسبة شائع له تطبيق في زد التطبيق الجاهز
نظام مخزون أو ERP مبني خصيصاً لك Webhook مع واجهة زد
جدول بسيط للمتابعة أداة أتمتة مثل Make أو n8n
مزامنة الأسعار والكميات من نظامك إلى زد واجهة زد البرمجية في الاتجاه المعاكس

الأحداث المتاحة

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

نصيحتنا: اشترك في أقل عدد من الأحداث. كل حدث إضافي يعني حملاً على خادمك ونقطة إضافية قد تفشل.

عنوان الاستقبال

العنوان الذي يستقبل الإشعارات يجب أن يكون:

  • على HTTPS بشهادة صالحة.
  • مخصصاً لهذا الغرض فقط، مثل /hooks/zid/orders، لا صفحة عامة في موقعك.
  • غير قابل للتخمين قدر الإمكان، مع إضافة جزء عشوائي إلى المسار إن لم تتوفر آلية توقيع.
  • مسجلاً في سجلات الخادم بحيث ترى كل طلب يصل إليه.

خلال التطوير، يمكن استخدام أداة تفتح نفقاً مؤقتاً إلى جهازك، لكن لا تبقها في الإنتاج.

التحقق من المصدر

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

الطريقة الأولى: آلية التحقق من زد

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

الطريقة الثانية: إعادة الجلب

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

الاستجابة السريعة والمعالجة لاحقاً

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

  1. استقبل الإشعار.
  2. احفظه كما هو في جدول "أحداث واردة" مع وقت الوصول.
  3. أرجع رد نجاح (رمز 200) فوراً.
  4. عامل في الخلفية يقرأ الأحداث المحفوظة واحداً واحداً، ويعيد جلب الطلب، ويحدّث المخزون، وينشئ ورقة التجهيز.

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

التعامل مع التكرار

الإرسال المكرر طبيعي في أي نظام Webhooks: إعادة محاولة بعد مهلة، أو حدث "تحديث" يصل بعد "إنشاء" بثوانٍ. القاعدة: كل معالجة يجب أن تكون آمنة إن تكررت.

  • احفظ معرّف كل حدث إن كان موجوداً، وتجاهل أي حدث سبق معالجته.
  • إن لم يتوفر معرّف للحدث، استخدم رقم الطلب مع الحالة الجديدة كمفتاح.
  • لا تخصم المخزون "عند وصول الحدث"، بل "إن لم يُخصم لهذا الطلب من قبل". احفظ علامة الخصم في سجل الطلب.
  • عند إلغاء الطلب، أعد الكمية مرة واحدة فقط، بالمنطق نفسه.

سجل الأخطاء

اجعل لكل حدث حالة: جديد، قيد المعالجة، تم، فشل. لما يفشل:

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

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

مفاتيح الواجهة وصلاحياتها

إعادة جلب الطلب تحتاج مفتاح وصول إلى واجهة زد. عامل هذا المفتاح كما تعامل كلمة مرور الحساب البنكي:

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

قائمة فحص قبل ربط المتجر الفعلي

قبل أن توجه أحداث متجرك الحقيقي إلى نظامك، مرّ على هذه البنود مع المطور واحداً واحداً:

  • [ ] عنوان الاستقبال يعمل عبر HTTPS بشهادة صالحة.
  • [ ] التحقق من مصدر الطلب مفعّل، وأي طلب يفشل فيه يُرفض ويُسجَّل.
  • [ ] الرد على زد يخرج خلال ثوانٍ قليلة، والمعالجة الثقيلة في طابور منفصل.
  • [ ] رقم الطلب مع نوع الحدث يمنع إدخال الحدث نفسه مرتين.
  • [ ] سجل الأخطاء يحفظ جسم الطلب كاملاً لمدة تكفي للمراجعة.
  • [ ] تنبيه يصلك إذا مرت ساعات عمل دون أي حدث، فالصمت الطويل غالباً عطل لا هدوء.
  • [ ] طلب تجريبي واحد على الأقل مرّ من الإنشاء حتى الإلغاء وظهر في النظام بكل حالاته.
  • [ ] المفاتيح محفوظة في متغيرات بيئة الخادم، لا داخل الكود ولا في المستودع.

أسئلة شائعة

هل أحتاج خادماً خاصاً لاستقبال Webhooks؟

تحتاج مكاناً يعمل دائماً ويستقبل طلبات HTTPS. قد يكون خادم نظامك الحالي، أو دالة سحابية صغيرة تحفظ الأحداث وتمررها.

ماذا لو توقف خادمي يوماً كاملاً؟

قد يعيد زد المحاولة لفترة محدودة، لكن لا تعتمد على ذلك. بعد العودة، اجلب طلبات الفترة المفقودة من الواجهة البرمجية وطابقها.

هل يمكن أن يغير نظامي حالة الطلب في زد؟

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

لربط طلبات زد بمخزونك أو نظامك المحاسبي بطريقة لا تفقد طلباً ولا تكرره، صف لنا نظامك الحالي ونرسم معك مسار البيانات.

المصادر

WhatsAppاحجز مكالمة