المفاهيم الأساسية

التطبيقات

التطبيق هو السجل الذي تنشئه في منصة المطورين. يحمل بيانات اعتمادك وروابط إعادة التوجيه والصلاحيات التي يحق لك طلبها وإعدادات webhook وخطة دنيا. لكل تطبيق حالة واحدة:

الحالة	من يستطيع تثبيته	ما يحدث للتثبيتات الموجودة
draft	المطور وحده، على المتاجر التي يملكها حسابه	تعمل الرموز على متاجر المطور
in_review	المطور وحده، على المتاجر التي يملكها حسابه	تعمل الرموز على متاجر المطور. والتطبيق المقبول الذي يعود إلى المراجعة بعد تعديل يُبقي كل تثبيت قائم يعمل.
approved	أي صاحب متجر	تعمل الرموز
rejected	لا أحد	كل طلب يُرد عليه بـ 403 مع app_suspended
suspended	لا أحد	كل طلب يُرد عليه بـ 403 مع app_suspended

تراجع DZBuild التطبيق بعد أن ترسله من المنصة. تسرد إرشادات المراجعة ما تتحقق منه المراجعة.

وضع التجربة

التطبيق الذي حالته مسودة أو قيد المراجعة يعمل في وضع التجربة. لا تقبله شاشة الموافقة إلا للمطور الذي يملكه، وعلى المتاجر التي يملكها حسابه فقط. هكذا تبني المسار كاملاً وتجرّبه قبل المراجعة، ببيانات حقيقية من متجرك.

تطبّق الواجهة البرمجية القاعدة نفسها في كل طلب. إذا لم يُقبل التطبيق بعد وكان التثبيت لشخص غير المطور، يكون الرد 403 مع app_not_approved والرسالة This app is in test mode and only runs on its developer's stores.

المتاجر

المتجر هو محل واحد على DZBuild، له منتجاته وطلباته وخطته. يمكن لحساب تاجر واحد أن يملك عدة متاجر.

• صاحب المتجر وحده يستطيع تثبيت تطبيق. لا تعرض شاشة الموافقة إلا المتاجر التي يملكها الحساب المتصل، لذا لا يستطيع عضو الفريق اختيار متجر يعمل فيه.
• موافقة واحدة يمكن أن تشمل 10 متاجر كحد أقصى. كل متجر يحصل على تثبيت خاص به ورمز خاص به.
• الرمز يقرأ ويعدّل المتجر الذي صدر له فقط. يسرد رد الرمز كل متجر ثُبّت عليه التطبيق في stores، ويكرّر المتجر الأول في المستوى الأعلى.

التثبيتات

التثبيت يربط تطبيقاً واحداً بمتجر واحد. لا يوجد أكثر من تثبيت واحد لكل تطبيق ومتجر.

يبدأ التاجر التثبيت من صفحة الإضافات في لوحة التحكم. يفتح زر تثبيت رابط موقعك، أو رابط الفتح إن لم يُضبط موقع، في علامة تبويب جديدة. لا ترسل DZBuild التاجر إلى عنوان التفويض نيابة عنك، لذا يجب أن تبدأ تلك الصفحة مسار OAuth.

• يُنشأ التثبيت عندما يستبدل خادمك الرمز في نقطة token، لا عندما يضغط التاجر على الموافقة.
• إذا ثبّت التاجر تطبيقك من جديد على المتجر نفسه، يحتفظ التثبيت بقيمة install_id. تصدر DZBuild رمزاً جديداً، وتلغي القديم، وتحفظ الصلاحيات من آخر موافقة.
• التاجر وحده يستطيع إزالة التطبيق، من صفحة تطبيقك في لوحة تحكمه. لا توجد نقطة إلغاء خاصة بالتطبيقات.

عندما يزيل التاجر تطبيقك، تقوم DZBuild بأربعة أمور دفعة واحدة: تعلّم التثبيت كمُزال، وتلغي الرمز، وتسقط إشعارات webhook التي كانت تنتظر الإرسال إلى رابطك، وتضع في الطابور حدثاً واحداً app.uninstalled إذا كان رابطك متحققاً منه ومفعّلاً. بعدها يُرد على الرمز القديم بـ 401.

الخطط و min_plan

كل متجر على DZBuild مشترك في إحدى أربع خطط، من الأدنى إلى الأعلى: free وpro وunlimited وenterprise. يمكن لأي خطة تثبيت تطبيق. شرط خطة Enterprise المفروض على مفاتيح API الخاصة بالتاجر لا ينطبق على رموز التثبيت.

يمكنك رفع هذا الحد بالإعداد min_plan في المنصة. قيمته الافتراضية free، وهي تسمح لكل المتاجر.

• في شاشة الموافقة، يظهر المتجر الأدنى من min_plan على أنه غير مؤهل ولا يمكن اختياره.
• في كل طلب إلى الواجهة البرمجية، يُرد على المتجر الأدنى من min_plan بـ 403 مع app_plan_required ورسالة تذكر اسم الخطة، مثل This app requires the Pro plan.
• الخطة المدفوعة المنتهية تُحسب free في الفحصين.

حدّ المعدّل لكل تثبيت

لكل تثبيت حصته الخاصة: 120 طلباً في الدقيقة. النافذة دقيقة ثابتة حسب الساعة، فيُصفَّر العدّاد مع بداية كل دقيقة.

تُفحص حصة التثبيت أولاً. بعدها يُحسب الطلب أيضاً من الحصة المشتركة للمتجر في الدقيقة، التي تستعملها مفاتيح التاجر الخاصة والتطبيقات الأخرى. التطبيق الذي يُكثر من الطلبات يبلغ حدّه الخاص قبل أن يستنفد حصة المتجر.

عند تجاوز الحد، تردّ الواجهة البرمجية بـ 429 مع الترويسة Retry-After وهذا المحتوى:

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute API limit exceeded for this app install",
    "retry_after": 42
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

إذا نفدت حصة المتجر أولاً، تكون الرسالة Per-minute API limit exceeded for this store. تشرح صفحة حدود معدّل الطلبات كيف تتمهّل قبل إعادة المحاولة.

رموز التثبيت

رمز التثبيت هو رمز Bearer الذي يستلمه خادمك من نقطة token. هو مفتاح API من النوع نفسه الذي ينشئه التاجر، لكنه معلَّم على أنه تابع لتثبيتك.

ما هو رمز التثبيت:

• رمز Bearer يبدأ بـ dzpk_live_، يُرسل في الترويسة Authorization: Bearer ....
• رمز واحد لكل تثبيت، أي رمز واحد لكل متجر.
• محدود بالصلاحيات التي وافق عليها التاجر، وتفحصه قواعد الصلاحيات نفسها التي تفحص كل مفتاح آخر.
• يعرضه GET /v1/whoami بالقيمة rate_limit_tier: enterprise مهما كانت الخطة، والحصة الحقيقية هي حدّ التثبيت الموضّح أعلاه.
• صالح دون تاريخ انتهاء. لا تعيد نقطة token أي expires_in ولا رمز تحديث.
• يُلغى عندما يزيل التاجر تطبيقك، ويُستبدل عندما يثبّته من جديد.

ما ليس رمز التثبيت:

• ليس مفتاح تاجر. لا يظهر في صفحة مفاتيح API الخاصة بالتاجر ولا يُحسب من الحد الأقصى لمفاتيحه.
• لا يستطيع إدارة المفاتيح ولا إشعارات webhook ولا سجل التعديلات. الطلبات إلى /v1/keys و/v1/webhooks و/v1/changes يُرد عليها بـ 403 مع رمز الخطأ forbidden والرسالة Apps cannot use this endpoint.
• ليس مرتبطاً بجلسة شخص. يبقى يعمل عندما يسجّل التاجر خروجه.
• لا يغطي عدة متاجر. استعمل الرمز الذي صدر لكل متجر.

كل رفض خاص بالتطبيقات يُرد عليه بـ 403 مع غلاف الخطأ:

رمز الخطأ	الرسالة	السبب
app_uninstalled	This app is no longer installed on this store	التثبيت لم يعد مفعّلاً
app_suspended	This app has been suspended by DZBuild	التطبيق موقوف أو مرفوض
app_not_approved	This app is in test mode and only runs on its developer's stores	لم يُقبل التطبيق بعد وصاحب المتجر ليس المطور
app_plan_required	This app requires the Pro plan (يتغيّر اسم الخطة)	خطة المتجر أدنى من min_plan