Copy page

Webhooks شركات التوصيل

تدفع شركات التوصيل تحديثات التوصيل إلى CodFlow. يتحقق الخادم من التوقيع، ويخزّن الأحداث في صندوق وارد، ويجيب شركة التوصيل فورًا، ثم يعالج الأحداث بعد الاستجابة. ويقرأ تكاملك حالة الشحنة الناتجة عبر API.

لاستقبال أحداث متجرك أنت على خادمك، اقرأ Webhooks بدلًا من هذه الصفحة.

توجد Webhooks واردة لـ Yalidine وZR Express. أما NOEST وEcoTrack فلا ترسلان Webhooks؛ بل تُزامَن شحناتهما كل خمس دقائق عبر مهمة cron وعند الطلب عبر نقاط نهاية مزامنة الشحنات.

نقاط النهاية

المسارات هي عناوين URL التي تحتفظ بها شركات التوصيل. لا تضعها خلف مصادقة: فشركات التوصيل لا تستطيع إرسال مفتاح API الخاص بك. التوقيع هو المصادقة.

كيف يعمل الاستلام

تحصل شركة التوصيل على 200 بمجرد تخزين الأحداث. ولا تُفشل إخفاقات المعالجة الـ webhook؛ إذ يعيد الـ drain محاولتها وفق جدول صندوق الوارد. وتتطلب Yalidine استجابة خلال 10 ثوانٍ وتعيد محاولة التسليم الفاشل سبع مرات على مدى 40 ساعة، ولهذا يهم هذا الفصل.

إعداد Webhook

يبدأ المساران من صفحة بيانات اعتماد شركة التوصيل في لوحة التحكم.

Yalidine

1. افتح صفحة بيانات اعتماد الشركة وانسخ عنوان URL للاستقبال من بطاقة إعداد الـ webhook.
2. في Webhooks Dashboard الخاصة بـ Yalidine، أنشئ نقطة نهاية بهذا العنوان.
3. اشترك في أنواع الأحداث التي تحتاجها. تتحقق Yalidine من العنوان عبر تحدّي CRC.
4. انسخ سر التوقيع من Yalidine إلى البطاقة واحفظه. واحفظ القيمة نفسها في مدير الأسرار لديك.

ZR Express

1. افتح صفحة بيانات اعتماد الشركة واختر Register webhook.
2. يسجّل الخادم نقطة النهاية لدى ZR Express ويجلب سر التوقيع نيابة عنك.
3. تعرض البطاقة نقطة النهاية كمسجّلة. استخدم Unregister لإزالتها.

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

يحتاج webhook إلى سره. يُرفض التسليم الذي لا يتحقق منه سر أي شركة بالرمز 401 ولا يُخزَّن أبدًا: فما تبلّغ عنه شركة التوصيل يصبح حدثًا تجاريًا قد تُبلَّغ به أنظمة التجار والعملاء، لذا يجب إثبات أنه صادر عن شركة التوصيل. وإذا لم تُعطِ ZR Express سر التوقيع، يُلغى التسجيل ولا يُحفظ شيء؛ سجّل من جديد.

التحقق من التوقيع

Yalidine

توقّع Yalidine جسم الطلب الخام بـ HMAC-SHA256 باستخدام سر webhook الخاص بالشركة. يصل التوقيع في x-yalidine-signature (أو x_yalidine_signature). ويقبل الخادم التمثيلات السداسية العشرية (hex) بالأحرف الصغيرة والكبيرة وbase64، ويقارن في زمن ثابت.

تحدّي GET منفصل: عندما ترسل Yalidine معاملات الاستعلام subscribe وcrc_token، يعيد الخادم الرمز كنص عادي. يتيح ذلك لـ Yalidine التحقق من العنوان قبل بدء إرسال الأحداث.

ZR Express

تستخدم ZR Express نظام Svix. المحتوى الموقّع هو:

Code
{svix-id}.{svix-timestamp}.{rawBody}

يصل التوقيع في svix-signature، ويقبل الخادم أي عنصر v1,<base64> مفصول بمسافات. ويُرفض أي svix-id أو svix-timestamp أو svix-signature مفقود.

التكرار الآمن والترتيب

• تجمع Yalidine أحداثًا كثيرة في طلب واحد. ولكل حدث event_id خاص به، وهو مفتاح صندوق الوارد.
• ترسل ZR Express حدثًا واحدًا لكل طلب. وsvix-id هو مفتاح صندوق الوارد.
• يتجاهل صندوق الوارد التسليمات المكررة، لذا لا تستطيع إعادة محاولة شركة التوصيل تطبيق الحدث نفسه مرتين.
• قد تصل الأحداث بترتيب مختلف. يطبّق الخادم مراحل الشحن وفق طابع وقت الحدث، لا وفق ترتيب الوصول.

التطوير المحلي

تحتاج شركات التوصيل إلى عنوان HTTPS عام. اكشف Worker المحلي عبر نفق تثق به، ثم اضبط ذلك الأصل لدى شركة التوصيل. بالنسبة إلى Yalidine، أنشئ نقطة النهاية على <tunnel-origin>/webhooks/yalidine واحفظ سرها في بطاقة webhook الخاصة بالشركة. وبالنسبة إلى ZR Express، أرسل أصل النفق كـ X-Worker-URL عند التسجيل، حتى تشير نقطة النهاية المنشأة إلى النفق بدلًا من localhost.

يبقى المستقبل المحلي http://localhost:8787/webhooks/yalidine أو /webhooks/zr_express، لذا يمكنك إعادة إرسال حمولة موقّعة باستخدام curl أثناء التطوير:

Code
curl -X POST http://localhost:8787/webhooks/yalidine \
  -H "Content-Type: application/json" \
  -H "x-yalidine-signature: <hex hmac of the raw body>" \
  --data-binary @event.json

ذو صلة

• الشحنات في مرجع API
• الأخطاء لغلاف إخفاق التوصيل
• شركات التوصيل لإعداد المزوّد والمزامنة