التفويض

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

النموذج#

• تطبيقك عميل سرّي: يقدّم client_id وclient_secret عند تبديل الرمز ويستخدم PKCE (S256) في الوقت نفسه. الشرطان معاً، لا أحدهما.
• كل تثبيت يربط تطبيقاً بمتجر واحد ويصدر رموزه الخاصة. لا يوجد رمز يغطي أكثر من متجر.
• النطاقات الفعلية لأي طلب هي: النطاقات الممنوحة عند الموافقة ∩ صلاحيات العضو المانح الحالية. إن فقد العضو صلاحية، فقدها تطبيقك في الطلب التالي مباشرة.

رابط الموافقة#

GET https://dukkan.one/apps/oauth/authorize

يعيد الخادم خطأ HTTP مباشراً — لا إعادة توجيه — عندما لا يمكنه الوثوق برابط الإعادة: 400 لعميل مجهول أو redirect_uri غير مسجّل، و403 لتطبيق غير متاح للتثبيت. بعد ذلك تُعاد كل الأخطاء إلى redirect_uri بمعامل error (انظر الأخطاء).

شاشة الموافقة#

يرى التاجر كل نطاق جملة عربية واضحة (مثل «قراءة الطلبات وبنودها وحالة التجهيز»). تُميَّز النطاقات المالية بلون تحذيري، ويحمل orders:create العبارة «تظهر هذه الطلبات في لوحة التحكم موسومة باسم التطبيق، ويُخصم المخزون كأي طلب آخر.»، ويظهر clients:read وclients:write في قسم منفصل غير محدد افتراضياً لأنهما يكشفان بيانات العملاء. يمكن للتاجر قبول جزء من النطاقات، فاقرأ scope من استجابة الرمز ولا تفترض ما طلبته.

تبديل الكود برموز#

POST https://dukkan.one/apps/oauth/token

أرسل بيانات العميل في ترويسة Authorization: Basic (أو في الجسم كـ client_id وclient_secret) والجسم بصيغة application/x-www-form-urlencoded:

import { exchangeCode } from "@dukkan.one/app-sdk/oauth";

const tokens = await exchangeCode({
  credentials: { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET },
  code: AUTH_CODE,
  redirectUri: "https://app.example.com/callback",
  codeVerifier: PKCE_VERIFIER,
});

curl -X POST https://dukkan.one/apps/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=PKCE_VERIFIER

{
  "access_token": "dk_app_at_REDACTED_EXAMPLE_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dk_app_rt_REDACTED_EXAMPLE_TOKEN",
  "scope": "orders:read orders:write",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "store_slug": "sham-perfumes"
}

الكود صالح للاستخدام مرة واحدة. أي محاولة لإعادة استخدام كود مستهلَك تلغي كل رموز ذلك التثبيت (حماية من السرقة، وفق RFC 6749).

يعيد GET /installation الهوية نفسها لاحقاً، مع النطاقات الفعلية، والأس العشري لعملة المتجر ولغته ومنطقته الزمنية، واشتراك Webhooks الحالي؛ راجع مرجع التثبيت.

منحة التحديث#

curl -X POST https://dukkan.one/apps/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN

{
  "access_token": "dk_app_at_REDACTED_NEW_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dk_app_rt_REDACTED_NEW_TOKEN",
  "scope": "orders:read orders:write",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "store_slug": "sham-perfumes"
}

• تعيد كل عملية تحديث زوجاً جديداً؛ احفظ الرمزين معاً ذرياً وتخلّص من القديمين. تحمل استجابة التحديث أيضاً scope وinstall_id وstore_id وstore_slug.
• إعادة استخدام رمز تحديث سبق تدويره تُفسَّر سرقةً: تُلغى كامل سلسلة الرموز للتثبيت، ويعود الطلب invalid_grant. يجب حينها إعادة التاجر إلى رابط الموافقة.
• استثناء واحد يحمي التطبيقات متعددة النسخ: تقديم رمز دُوِّر قبل أقل من 30 ثانية بينما خلفه ما زال صالحاً يُعامل كسباق بين نسختين من تطبيقك. يعود الطلب invalid_grant دون إلغاء أي شيء؛ أعد قراءة مخزن الرموز واستخدم الزوج الذي حفظته النسخة الأخرى. ومع ذلك، سلسِل عمليات التحديث لكل تثبيت.
• لا تحدّث قبل انتهاء رمز الوصول بكثير؛ حدّث عند 401 أو قبل الانتهاء بدقائق.

بادئات الرموز#

كل الرموز تُخزَّن على الخادم كتجزئة SHA-256 فقط ولا يمكن استرجاعها.

الإلغاء#

• عندما يلغي التاجر التثبيت تُلغى رموزه فوراً، ويصلك حدث app.uninstalled — بلا نطاق مطلوب — حتى بعد الإلغاء. عالِجه بحذف بيانات ذلك المتجر.
• عند إيقاف تطبيقك (بقرارك أو بقرار دكان) تُلغى الرموز وتُعطَّل الاشتراكات؛ راجع دورة حياة التطبيق.
• استدعاء واجهة المنصّة برمز ملغى أو منتهٍ يعيد 401 بجسم error ورمز unauthorized.

الأخطاء#

خطأ رابط الموافقة يعود إلى redirect_uri كمعامل error (مع state)؛ خطأ نقطة الرمز يعود جسم JSON { "error": "…" }.

الحدود: 60 طلباً كل 10 دقائق لكل عنوان IP على النقطتين، و600 طلب كل 10 دقائق لكل عميل على نقطة الرمز. التجاوز يعيد 429.

قائمة الأمان#

• ولّد state عشوائياً لكل جلسة وتحقّق منه عند العودة.
• خزّن code_verifier في جلسة الخادم، لا في المتصفح.
• خزّن المفتاح السري ورموز التحديث مشفّرة على الخادم فقط؛ لا تُرسل أي رمز إلى العميل.
• جدول تدوير المفتاح السري بنافذة تداخل (24 ساعة افتراضياً) موصوف في دورة حياة التطبيق.
• عامل invalid_grant عند التحديث كإشارة لإعادة التفويض، لا لإعادة المحاولة.