تخطَّ إلى المحتوى
مطوّرو دكانالتوثيق
Englishتسجيل الدخول

مرجع النطاقات

كل نطاق، وما يفتحه من نقاط نهاية ومواضيع Webhooks، والجملة التي يراها التاجر.

آخر تحديث 10 أيلول 2026قراءة 3 د
في هذه الصفحة

هذه الصفحة لمن يقرّر ما يطلبه تطبيقه. في نهايتها تعرف كل نطاق، وما يفتحه بالضبط، وكيف يراه التاجر، والقواعد الخاصة بنطاق بيانات العملاء.

القواعد#

  • تطلب النطاقات على مستوى إصدار التطبيق في البوابة، ويمنحها التاجر لكل متجر على حدة في شاشة الموافقة. لا تتوسّع النطاقات بصمت أبداً؛ توسيعها يعني إصداراً جديداً وموافقة جديدة.
  • النطاقات الفعلية = الممنوحة ∩ صلاحيات العضو المانح الحالية. نقطة نهاية بلا نطاق فعلي تعيد 403 برمز forbidden.
  • الاشتراك في موضوع Webhook يتطلب نطاق القراءة الذي يحكم حمولته، ويتوقف التسليم فوراً إن فُقد النطاق.
  • المراجعون يتحقّقون من أن الإدراج يبرّر كل نطاق. اطلب أقل ما يلزم.

الجدول#

النطاق ما يفتحه مواضيع Webhooks الجملة التي يراها التاجر
products:read GET /products، GET /products/{id} product.created، product.updated، product.deleted قراءة المنتجات وخياراتها
inventory:read GET /inventory/movements؛ ويكشف stock_after في استجابة الحركة المكتوبة inventory.movement_created قراءة مستويات المخزون وحركاته
inventory:write POST /inventory/movements؛ وخيار restock في POST /orders/{id}/refunds — تعديل مستويات المخزون
orders:read GET /orders، GET /orders/{id} (بلا بيانات العملاء) order.created، order.status_changed، order.paid، fulfillment.requested، fulfillment.created، fulfillment.updated، refund.created قراءة الطلبات وبنودها وحالة التجهيز
orders:write PATCH /orders/{id}/status؛ وPATCH /orders/{id} (الملاحظة والوسوم وخصائص التطبيق) — تحديث حالة الطلب وملاحظته ووسومه
orders:create POST /orders (طلبات بأسعار يحددها التطبيق، بما فيها البنود المخصصة) — إنشاء طلبات بأسعار يحددها التطبيق
fulfillments:write POST /orders/{id}/fulfillments، PATCH /orders/{id}/fulfillments/{fulfillmentId} (بما فيها اقتراح تحصيل COD) — إنشاء عمليات التجهيز وتحديثها مع معلومات التتبع
refunds:write POST /orders/{id}/refunds — إصدار عمليات استرجاع نيابةً عن التاجر
discounts:read GET /discounts — قراءة الخصومات والعروض
clients:read الحقلان customer وshipping_address في GET /orders/{id} لا يظهر في أي Webhook قراءة أسماء العملاء وبيانات التواصل (تتطلب اتفاقية معالجة البيانات)
clients:write إنشاء سجلات العملاء وتحديثها؛ تصل نقاط نهاية العملاء في مراجعة لاحقة، والنطاق في المعجم منذ الآن لا يظهر في أي Webhook إنشاء سجلات العملاء وتحديثها: الأسماء وأرقام الهواتف والعناوين (تتطلب اتفاقية معالجة البيانات)

app.uninstalled لا يتطلب أي نطاق ويصل دائماً. جدول المواضيع والحمولات في مرجع الأحداث.

ملاحظات تبعية#

  • inventory:write مطلوب لإرجاع البضاعة إلى المخزون مع الاسترداد (restock)؛ بدونه يُقبل الاسترداد المالي فقط.
  • fulfillments:write مالي بطبيعته: يمكنه اقتراح تحصيل نقدي يؤكّده التاجر. يُعامل في المراجعة كنطاق حسّاس، مثل refunds:write.
  • الحركة المكتوبة عبر inventory:write تعيد stock_after فقط عندما يحمل التثبيت inventory:read أيضاً.
  • orders:create لا يتضمّن قراءة الطلبات: جسم 201 هو القراءة الوحيدة التي يمنحها. اطلب orders:read كذلك إن كنت ستعرض الطلبات أو تجلبها لاحقاً، وorders:write إن كنت ستحدّث الملاحظة أو الوسوم بعد الإنشاء. يرى التاجر تحته العبارة «تظهر هذه الطلبات في لوحة التحكم موسومة باسم التطبيق، ويُخصم المخزون كأي طلب آخر.» التفاصيل في الطلبات التي تنشئها التطبيقات.
  • يُعامل orders:create في المراجعة كنطاق حسّاس، مثل refunds:write: فهو ينشئ طلبات ويخصم المخزون، فعلى الإدراج أن يبيّن السبب.

بيانات العملاء (clients:read وclients:write)#

أسماء العملاء وأرقام هواتفهم وبريدهم وعناوين التوصيل خلف نطاقين مخصّصين: clients:read يقرأها وclients:write ينشئ سجلات العملاء ويحدّثها. يختلفان في أربعة أمور:

  1. اتفاقية معالجة البيانات أولاً. يجب أن يقبل مالك فريقك النسخة الحالية من الاتفاقية (2026-08-19) قبل أن يقبل الخادم إصداراً يطلب أيّاً من النطاقين؛ راجع معالجة البيانات. تغيّر النسخة يُسقط النطاقين حتى يُعاد القبول. يشمل قبول اتفاقية معالجة البيانات إنشاء سجلات العملاء وتحديثها نيابة عن التاجر.
  2. قسم منفصل في شاشة الموافقة، غير محدد افتراضياً، للنطاقين معاً.
  3. لا يظهر أبداً في حمولات Webhooks. اجلب تفاصيل الطلب عبر الواجهة البرمجية؛ كل وصول يُسجَّل في سجل نشاط التاجر.
  4. حذف عند الإلغاء. تلتزم بحذف بيانات العملاء التي عالجتها عند إلغاء التثبيت.

بدون clients:read تُحذف الحقول ببساطة من استجابات الطلبات؛ لا يظهر null بل لا يظهر الحقل. الاستثناء الوحيد هو POST /orders: يعيد جسم 201 بيانات العميل التي أرسلها تطبيقك، لأنها بحوزتك أصلاً.