الاتصال بزد عبر OAuth 2.0: الـ Tokens والـ Headers وسياسة التفعيل

كيف يعمل OAuth في زد

تعتمد زد على نوع التفويض authorization code في OAuth 2.0. يُوجَّه التاجر إلى Server التفويض في زد، فيوافق على الصلاحيات التي يطلبها تطبيقك، ثم يستبدل الـ Server الخاص بك الرمز الناتج بالـ Tokens. ولأن هذا الاستبدال يحتاج Client Secret، يجب أن يعمل تطبيقك على الـ Server (server-side).

ستتعامل مع عنوانين أساسيين:

• Server OAuth: https://oauth.zid.sa
• الـ API: https://api.zid.sa/v1، وv1 هو الإصدار الحالي، أما الإصدارات الأقدم فمتوقفة

التدفق خطوة بخطوة

1. التوجيه: أرسل متصفح التاجر إلى /oauth/authorize على Server OAuth، ومعه client_id وredirect_uri وresponse_type=code.
2. الموافقة: إن لم يكن التاجر مسجّل الدخول، تطلب منه زد تسجيل الدخول أولًا. بعدها يرى الصلاحيات التي يطلبها تطبيقك، فيوافق أو يرفض.
3. الـ Callback: ترسل زد Authorization Code صالحًا لمرة واحدة إلى الـ callback لديك.
4. تبادل الرمز: يرسل الـ Server الخاص بك الرمز مع بيانات اعتماد التطبيق بطلب POST إلى /oauth/token. تُرسل القيم في جسم الطلب، لا في URL Parameters.
5. الحفظ: احفظ الـ Tokens المُعادة في مكان آمن لتستخدمها في الطلبات القادمة.

curl -X POST https://oauth.zid.sa/oauth/token \
     -d "grant_type=authorization_code" \
     -d "client_id=48" \
     -d "client_secret=LsswUNyWTjyKT9AsXnpsv3FnG4glSNZQ5SM3YRnD" \
     -d "redirect_uri=http://client.test/oauth/callback" \
     -d "code=your_authorization_code_here"

إن أردت مرجعًا جاهزًا، فزد توفر تطبيقات بداية مبنية بـ Laravel وNode.js (Express).

أي Token في أي Header؟

تحتوي الاستجابة على access_token وAuthorization وrefresh_token وexpires_in. اثنان منها يُرسلان مع كل طلب:

• Authorization: يمنح تطبيقك الوصول إلى Zid API. أرسله في Header Authorization مسبوقًا بكلمة Bearer.
• access_token: يمنح الوصول إلى متجر بعينه. أرسله في Header X-Manager-Token.

Authorization: Bearer <Authorization token>
X-Manager-Token: <access_token>

كلا الـ Tokens حساس، فاحفظهما في مخزن آمن على الـ Server. ويحذّر التوثيق من أن إساءة استخدام الـ Token قد تؤدي إلى حظر تطبيقك.

انتهاء الصلاحية والتجديد وإلغاء التثبيت

تنتهي صلاحية الـ manager token بعد سنة، وكذلك الـ refresh token. ينصح التوثيق بالتجديد قبل انقضاء السنة بوقت كافٍ، في حدود الشهر العاشر. وللتجديد أرسل طلب POST إلى /oauth/token ومعه grant_type=refresh_token والـ refresh_token الخاص بالتاجر وclient_id وclient_secret وredirect_uri.

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

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

الأخطاء وحدود الطلبات

• 401 Unauthorized: التوثيق مفقود أو فشل، فراجع الـ Tokens.
• 403 Forbidden: فُهم الطلب لكنه رُفض، فراجع الصلاحيات.
• 429 Too Many Requests: خفّف الطلبات وأعد المحاولة بتأخير يتزايد تدريجيًا (exponential backoff).
• رسالة «The resource owner or authorization server denied the request»: يرجعها مركز المساعدة إلى نقص الصلاحيات أو إلى أن التطبيق غير منشور على ذلك المتجر. وتحقق أيضًا من تطابق رابط الـ redirect في خطوتي التوجيه والـ callback.

تسمح زد بـ 60 طلبًا في الدقيقة لكل تطبيق في كل متجر، وتطبّق خوارزمية Leaky Bucket. لا تستعلم مرارًا عن حالة الطلبات أو الدفع، واستخدم الـ Webhooks بدلًا من ذلك.

سياسة التفعيل وOAuth

تنطبق سياسة تفعيل التطبيقات وOAuth في زد (المحدّثة في 9 سبتمبر 2026) على كل التطبيقات الجديدة المرسلة إلى سوق التطبيقات. وهذه أبرز نقاطها:

• OAuth أولًا: يبدأ التطبيق القياسي OAuth فور ضغط التاجر على Activate. يدفع التاجر قيمة الباقة عبر زد قبل ذلك إن وُجدت، ولا يجوز أن يطلب التطبيق دفعة إضافية من جهة الشريك. ربط الحساب والإعداد يأتيان بعد OAuth.
• الإعداد الذي يديره الشريك (Partner-managed setup)، أي إكمال متطلبات قبل OAuth، يحتاج موافقة كتابية مسبقة من زد. كون التطبيق مجانيًا أو بلا باقات في زد لا يعني الحصول على هذه الموافقة.
• مسارات مرفوضة: شاشة تسجيل أو دخول قبل OAuth، أو إرسال التاجر إلى صفحة رئيسية عامة، أو مطالبته بلصق Tokens أو أسرار أو كلمات مرور، أو كتابة Store ID أو رابط المتجر.
• الأمان: تحقق من قيمة state عشوائية وصالحة لمرة واحدة وقصيرة العمر. استخدم PKCE حيث يكون مدعومًا. استبدل الرمز فورًا ولا تسجّله في الـ Logs. وأبقِ الـ Tokens بعيدة عن الروابط والتخزين في المتصفح وأدوات التحليل والـ Logs.
• دورة الحياة: تعامل بأمان مع الرفض والمحاولات المكرّرة، وتجنّب الاتصالات المكرّرة عند إعادة التثبيت، وأوقف المعالجة بعد إلغاء التثبيت.