البدء
البدء السريع
أنشئ تطبيق ساس، واربط متجر اختبار، واستدعِ API واشترك في الأحداث.
ابنِ أول تكامل مع ساس في سبع خطوات. تحتاج حساب مطور مقبولًا وتطبيق backend يحفظ الأسرار والرموز بعيدًا عن المتصفح.
1. أنشئ تطبيق المطور
افتح لوحة المطور ← التطبيقات ← إنشاء تطبيق. أدخل الاسم بالعربية والإنجليزية، والمعرّف الثابت، والتصنيف ونموذج التسعير.
النتيجة المتوقعة: يظهر التطبيق في تطبيقاتك بحالة draft. معرّف التطبيق هو client_id في OAuth. احفظ Client Secret الذي يظهر مرة واحدة في خادمك.
2. أعد OAuth وعنوان الرجوع
افتح التطبيق، وأنشئ الإصدار 1.0.0، وسجّل عنوان HTTPS الدقيق الذي يعالجه backend، مثل https://app.example.com/oauth/callback. يُقبل HTTP على loopback للتطوير المحلي فقط.
يبدأ backend التفويض من:
GET https://getsas.xyz/api/oauth/authorizeاستخدم response_type=code وstate جديدًا وPKCE S256. راجع OAuth 2.0.
3. اختر أقل نطاقات لازمة
في معالج الإصدار اختر ما يستخدمه التطبيق فقط. مزامنة المنتجات للقراءة تحتاج catalog:read، وقراءة الطلبات تحتاج orders:read، وإدارة اشتراكات Webhook تحتاج webhooks:manage.
النتيجة المتوقعة: تظهر النطاقات نفسها في شاشة موافقة التاجر. النطاق المفقود يعيد 403 ولا يمنح وصولًا جزئيًا بصمت.
4. ثبّت التطبيق على متجر اختبار مصرح
أرسل إصدار الاختبار وانشره في بيئة محلية/اختبار مصرح بها. افتح رابط التثبيت، وسجّل الدخول كتاجر الاختبار، واختر المتجر الاصطناعي ووافق على النطاقات.
النتيجة المتوقعة: يعيد ساس authorization code مرة واحدة إلى callback الدقيق مع state الأصلي. بدّله من backend. لا يوجد حاليًا Sandbox عام مستضاف؛ لا تستخدم بيانات عملاء حقيقية بدلًا منه.
5. نفّذ أول طلب API
أرسل access token من backend. ابدأ بالمنتجات:
curl --request GET \
'https://getsas.xyz/api/v1/catalog/products?limit=10' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'النتيجة المتوقعة: 200 OK مع data وبيانات الترقيم. يعني 401 أن الرمز مفقود أو منتهي أو ملغى. ويعني 403 أن التثبيت لا يملك النطاق المطلوب.
6. اشترك في Webhooks
استدعِ POST /api/v1/webhooks بنطاق webhooks:manage، وحدث مصرح في الإصدار المراجع، وعنوان HTTPS عام. احفظ signing secret فورًا؛ يظهر مرة واحدة.
تحقق من X-Saas-Signature باستخدام النص الخام نفسه، وارفض التوقيت القديم، وأزل تكرار X-Saas-Event-Id. راجع Webhooks.
7. أرسل للمراجعة وانتقل للإنتاج
أكمل بيانات Marketplace والصور وروابط الدعم والخصوصية. من التطبيقات اختر إرسال للمراجعة. عالج ملاحظات المراجعة، وانشر الإصدار المقبول، ثم دع كل تاجر Production يكمل موافقة OAuth.
قبل الإنتاج اختبر مطابقة callback، وstate وPKCE، ورفض النطاق الناقص، وتدوير refresh token، وتوقيعات Webhook، وعدم التكرار، وإلغاء التثبيت وسحب الصلاحية.