تأمين تطبيقك على زد: توثيق الـ Webhooks وحماية الـ Tokens وأقل الصلاحيات وTLS

أين يظهر الأمان في المراجعة؟

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

يركّز هذا الدليل على ما تتحكم فيه أنت في شيفرتك وبنيتك التحتية: الـ Webhooks الواردة، والـ Tokens المحفوظة، والصلاحيات المطلوبة، وإعدادات TLS لروابطك، وخطوة الـ callback. أما تدفق OAuth نفسه والاشتراك في الـ Webhooks فتجدهما في دليلَي OAuth والـ Webhooks.

تحقّق من كل webhook عبر Basic Auth

عند إنشاء webhook عبر POST /v1/managers/webhooks يمكنك تمرير username وpassword. تجمعهما زد بصيغة username:password، وتُرمّز الناتج بـ Base64، وترسله مع كل إرسال في Header Authorization: Basic. وبحسب سجل تحديثات الشركاء، يجب تقديم هذه البيانات عند إنشاء أي webhook أو تحديثه، إذ أصبح Basic Authentication إلزاميًا لكل الـ Webhooks منذ 30 سبتمبر 2026.

POST /v1/managers/webhooks
Authorization: Bearer <Authorization token>
X-Manager-Token: <access_token>

{
  "event": "order.create",
  "target_url": "https://hooks.example.com/zid/orders",
  "original_id": "<your identifier>",
  "username": "zid-hook",
  "password": "<long random value>"
}

في الـ Server الخاص بك، ارفض أي طلب لا تطابق Header القيمة المتوقعة قبل أن تقرأ الجسم أو تنفّذ أي إجراء:

import crypto from 'node:crypto';

function isFromZid(req, expectedUser, expectedPass) {
  const header = req.headers['authorization'] || '';
  const expected = 'Basic ' +
    Buffer.from(`${expectedUser}:${expectedPass}`).toString('base64');
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

• من الممارسات الجيدة توليد كلمة مرور عشوائية طويلة لكل متجر وحفظها مع بقية أسرار ذلك المتجر، حتى لا تكشف قيمة مسرّبة واحدة كل التجار.
• قارن القيمتين بمقارنة ثابتة الزمن كما في المثال، وأرجع 401 دون معالجة إذا فشل التحقق.
• طبّق على هذا الرابط معايير HTTPS وTLS نفسها المطلوبة لبقية روابط تطبيقك (انظر أدناه).

Headers أحداث التطبيق وwebhooks الشحن

أحداث اشتراك التطبيق، مثل app.market.application.install وapp.market.application.uninstall، لا تُنشأ عبر الـ API، بل تضبطها من قسم Webhooks في صفحة تطبيقك بلوحة الشركاء. ويتيح لك توثيق App Management هناك إضافة Headers إضافية للتوثيق أو لأي متطلبات أخرى. وتطبيقات الشحن تعمل بالطريقة نفسها: تنشئ زد الـ Webhooks، وتُدخل أنت رابط الاستقبال والـ Header.

استفد من هذا الخيار. ضع قيمة سرية في Header مخصصة، وارفض أي طلب يصل إلى رابط أحداث التطبيق دون أن يحملها. اسم الـ Header في المثال توضيحي:

POST /zid/app-events HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
X-Example-Secret: <long random value>

اجتز فحوص TLS في زد

تتحقق لوحة الشركاء من كل رابط webhook أو endpoint قبل قبوله. وإذا لم تستطع إنشاء اتصال آمن وسريع بالـ Server الخاص بك، تظهر لك رسالة Invalid TLS URL. ويذكر مركز المساعدة خمسة أسباب:

• إصدار TLS قديم: المدعوم فقط TLS 1.2 وTLS 1.3، ويُرفض TLS 1.0 و1.1.
• شهادة غير صالحة: منتهية، أو موقّعة ذاتيًا، أو تنقصها الشهادات الوسيطة، أو لا تطابق الـ Scope. استخدم شهادة من جهة إصدار معتمدة.
• مصافحة بطيئة: يجب أن يستجيب الـ Server الخاص بك للاتصال ويُكمل مصافحة TLS خلال 5 ثوانٍ.
• Server لا يمكن الوصول إليه: بسبب DNS، أو قواعد الجدار الناري، أو قوائم التحكم بالوصول، أو قواعد الحماية من DDoS وWAF التي تحجب الطلبات الواردة.
• رابط HTTP عادي: يجب أن يبدأ الرابط بـ https://.

اختبر الرابط قبل حفظه:

curl -Iv https://your-server.com/endpoint

في المخرجات، ابحث عن SSL connection using TLSv1.2 أو TLSv1.3، وتأكد من عدم وجود سطر SSL certificate problem، ومن أن الاتصال يكتمل في وقت أقل بكثير من 5 ثوانٍ. وتشترط سياسة OAuth أيضًا استخدام HTTPS لروابط الإطلاق والـ callback والإعداد والـ API في بيئة الإنتاج.

احمِ الـ Tokens وجدّدها في وقتها

تمنحك استجابة الـ Token قيمة Authorization (للوصول إلى الـ API) وقيمة access_token التي ترسلها في Header X-Manager-Token (للوصول إلى متجر بعينه). ويقول التوثيق إن هذه البيانات يجب أن تُحفظ في مخزن آمن، وإن إساءة استخدام الـ Token قد تؤدي إلى حظر تطبيقك. وتضيف السياسة قواعد محددة:

• احفظ الـ Tokens على الـ Server، وقيّد من يستطيع قراءتها وما يستطيع ذلك.
• لا تكشف أبدًا الـ access token أو الـ refresh token أو الـ client secret في محتوى الصفحة أو الروابط أو التخزين في المتصفح أو أدوات التحليلات أو الـ Logs.
• أبقِ الـ client secret خارج المتصفحات وتطبيقات الجوال والمستودعات العامة والشيفرة التي تعمل في جهة العميل.
• اعزل كل متجر مفوَّض عن كل متجر آخر وعن كل حساب شريك آخر.
• ادعم تجديد الـ Token وإعادة التفويض وإعادة التثبيت دون إنشاء اتصالات مكررة أو متداخلة بين المتاجر.
• بعد إلغاء التثبيت أو سحب التفويض، أوقف المعالجة وأزل صلاحيات الوصول المعنية.

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

اطلب الصلاحيات التي تستخدمها فقط

تشترط السياسة أن تطلب فقط الصلاحيات (Scopes) اللازمة للوظائف الموثّقة في تطبيقك. وتختارها من صفحة تطبيقك في لوحة الشركاء، ويراجعها الفريق عند إرسال التطبيق للنشر.

يوضح Account API الجديد أهمية ذلك. فهو يحل محل GET v1/managers/profile التي أُوقفت في 30 سبتمبر 2026، بنقاط لكل منها صلاحيتها:

• third_account_identity_read: معلومات الهوية الأساسية للحساب.
• third_account_profile_read: بيانات الملف الموسّعة، ومنها تاريخ الميلاد والمسمى الوظيفي والمعلومات الجغرافية.
• third_store_details_read: تفاصيل المتجر وهويته البصرية وإعدادات اللغة والعملة وحساباته الاجتماعية وتشغيله ومعلوماته التجارية.

إذا كان كل ما تحتاجه معرفة هوية الحساب، فاطلب صلاحية الهوية واترك الملف الموسّع. والقاعدة نفسها تنطبق على بقية الـ API: كل صفحة endpoint تذكر صلاحيتها، مثل third_webhook_write لإنشاء الـ Webhooks، فاربط كل صلاحية تطلبها بميزة تستخدمها فعلًا.

نظافة الـ callback في OAuth

الـ callback هو المكان الذي قد يحاول فيه مهاجم حقن رمز أو ربط متجر خاطئ. لذلك تطلب السياسة منك:

• توليد قيمة state عشوائية تُستخدم مرة واحدة وتنتهي سريعًا، وربطها بالـ Session التي بدأت الطلب، والتحقق منها قبل قبول الـ callback.
• استخدام PKCE حيث يدعمه إعداد العميل الذي اخترته، وحيثما تشترطه زد.
• استبدال الرمز فورًا على الـ Server الخاص بك ثم إزالته قبل الانتقال لأي صفحة تالية. لا تسجّله ولا تعرضه ولا تمرّره إلى روابط أخرى.
• التعامل بأمان مع المحاولات المرفوضة أو الملغاة أو المنتهية أو غير الصالحة أو المكررة، دون إنشاء اتصالات خاطئة أو مكررة.
• عدم ربط متجر بحساب خارجي قائم لمجرد تطابق البريد الإلكتروني.
• في التطبيقات المضمّنة، التحقق من آلية التوثيق المضمّنة التي توفرها زد قبل عرض أي محتوى محمي. ف ID المتجر في رابط الفتح لا يثبت هوية التاجر.

إذا فشل التفعيل، يشير مركز المساعدة إلى سببين شائعين: رسالة OAuth Authorization Server Error تعني غالبًا أن رابط التوجيه (redirection) أو رابط الـ callback غير صحيح، ورسالة Internal server error - OAuth هي استجابة الـ Server الخاص بك أنت لطلب زد في خطوة التوجيه، فراجع Logs الـ Server الخاص بك.