تاجر
ابدأ مجاناً

المطوّرون

بناء تطبيق على تاجر: OAuth والصلاحيات والـ Webhooks

يحصل كل تطبيق على client_id وclient_secret، ويثبّته التاجر بموافقته على صلاحيات محددة، ثم يستدعي Admin API بتوكن خاص بالمتجر ويستقبل أحداثه موقّعة.

  1. 1.1. بيانات التطبيق

    عند إنشاء التطبيق يُعرض client_secret مرة واحدة فقط ويُحفظ لدينا مجزّأً (SHA-256)، فلا يمكن استرجاعه لاحقًا. إذا فقدته اطلب تدوير السر، فيبطل السر القديم فورًا.

  2. 2.2. طلب الموافقة (authorization code)

    وجّه التاجر إلى صفحة الموافقة في لوحته ‎/merchant/apps/{slug}/authorize?redirect_uri=…&scopes=read_products,read_orders&state=… ‏(يجب أن يكون redirect_uri ضمن روابط التطبيق المسجلة). بعد الموافقة يُعاد التاجر إلى redirectUri ومعه code (صالح 5 دقائق ولمرة واحدة) وstate نفسه؛ تحقق من state قبل المتابعة.

  3. 3.3. تبادل الكود بتوكن

    من خادمك فقط: POST /api/v1/apps/token بالحقول slug وcode وredirectUri وclientId وclientSecret. الرد يحتوي accessToken (صالح ساعة واحدة) وrefreshToken (صالح 30 يومًا). التوكن خاص بمتجر واحد وبالصلاحيات التي وافق عليها التاجر فقط.

  4. 4.4. التجديد والإلغاء

    POST /api/v1/apps/token/refresh بالحقول slug وrefreshToken وclientId وclientSecret يعيد زوجًا جديدًا، ويبطل refreshToken القديم (استخدام واحد). إلغاء التثبيت يلغي كل توكنات التطبيق في ذلك المتجر.

  5. 5.5. Admin API والصلاحيات

    أرسل Authorization: Bearer {accessToken} إلى /api/v1/apps/api: ‏GET /products و/products/{id} تحتاج read_products، ‏GET /orders و/orders/{id} تحتاج read_orders، ‏GET /customers و/customers/{id} تحتاج read_customers، و/webhooks تحتاج manage_webhooks. الطلب خارج الصلاحيات يُرفض بـ 403، والتوكن المنتهي أو الملغى بـ 401. الحد 180 طلبًا في الدقيقة لكل تثبيت، وتصلك الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset، وبعد تجاوزه 429.

  6. 6.6. اشتراكات Webhooks

    POST /api/v1/apps/api/webhooks بالحقلين eventName وtargetUrl (https فقط) يعيد secret للتوقيع مرة واحدة. الأحداث: order.created وorder.paid وorder.confirmed وorder.shipped وorder.delivered وorder.cancelled (تحتاج read_orders)، وproduct.created وproduct.updated وproduct.deleted (تحتاج read_products)، وcustomer.created (تحتاج read_customers)، وapp/uninstalled (لكل تطبيق). GET يعرض اشتراكاتك وDELETE /webhooks/{id} يحذف أحدها. عند إلغاء التثبيت تصلك app/uninstalled ثم تتوقف اشتراكاتك.

  7. 7.7. التحقق من التوقيع وإعادة المحاولة

    كل طلب يحمل x-webhook-event وx-webhook-timestamp وx-webhook-signature وx-webhook-id وx-webhook-attempt. التوقيع = HMAC-SHA256 بالـ secret على النص «timestamp.body» بصيغة hex؛ احسبه على الجسم الخام قبل أي parsing وقارنه بمقارنة ثابتة الزمن. أي رد غير 2xx من نوع 5xx أو 408 أو 429 أو خطأ شبكة يُعاد حتى 8 محاولات بتأخير مضاعف يبدأ من دقيقة. التسليم «مرة على الأقل»، فاستخدم x-webhook-id لتجاهل التكرار.

لأي استفسار حول هذه الصفحة تواصل معنا عبر صفحة التواصل.