البدء

تأخذك هذه الصفحة من منصة مطورين فارغة إلى أول طلب موثَّق إلى الواجهة البرمجية. ستسجّل تطبيقاً، وتثبّته على متجر تملكه، وتستبدل الرمز المؤقت برمز التثبيت، ثم تستدعي GET /v1/whoami.

قبل أن تبدأ

• حساب على DZBuild يملك متجراً واحداً على الأقل. تثبيت التجربة لا يعمل إلا على متجر يملكه حسابك، لا على متجر أنت عضو في فريقه.
• رابط إعادة توجيه (redirect URI) بـ https يتحكم فيه تطبيقك. ترفض منصة المطورين http. أسرع خيار هو Worker على workers.dev من /apps/new تسجّله مرة واحدة؛ ويصلح أيضًا نفق https إلى جهازك، لكن عنوانه يتغيّر في كل تشغيل ومنصة المطورين لا تقبل أكثر من 5 روابط إعادة توجيه.
• الأداتان curl وopenssl على جهازك.

ابدأ من التطبيق النموذجي

أسرع بداية هي /apps/new: اختر واحدًا من ثلاثة قوالب Cloudflare جاهزة، وانشره على عنوان workers.dev مجاني، واحصل على القيم الدقيقة التي تُدخلها في منصة المطورين.

• cloudflare-basic: مسار التثبيت، ورمز واحد لكل متجر، ورابط الفتح. الأساس لتطبيقك الخاص.
• cloudflare-catalog: صفحة منتجات للتاجر وتصدير الكتالوج بصيغة CSV.
• cloudflare-orders: تنبيهات الطلبات الجديدة على Telegram باستعلام GET /v1/orders مرة كل دقيقة؛ وإشعارات webhook للطلبات متى امتلكت نطاقًا.

أنشئ القالب الأساسي بأمر واحد، أو انشره من المتصفح بالزر أدناه. تنسخه Cloudflare إلى حسابك على GitHub وتنشره؛ ويسرد ملف README الخاص بالقالب الخطوات التالية.

npm create cloudflare@latest my-app -- --template DZBuild-com/dzbuild-app-starter/cloudflare-basic --no-agents --no-git --no-deploy --no-open

إن كنت تستضيف التطبيق على خادمك بدل ذلك، فمثال Node.js في المستودع نفسه يتبع المسار نفسه دون أي اعتماديات ومع اختبارات تعمل دون اتصال. املأ متغيرات البيئة في .env.example من منصة المطورين.

1. سجّل التطبيق

افتح منصة المطورين في https://dzbuild.com/dashboard/developer واختر تطبيق جديد (/dashboard/developer/apps/new). املأ النموذج:

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

احفظ التطبيق. تعرض المنصة بعدها ثلاثة بيانات اعتماد:

البيان	الصيغة	أين يُحفظ
client_id	dzapp_ يليه 20 حرفاً ست عشرياً	علني. يوضع في رابط التفويض.
سرّ العميل	dzas_ يليه 48 حرفاً ست عشرياً	يظهر مرة واحدة. احفظه على خادمك. أنشئ سرّاً جديداً من المنصة إن ضاع منك.
مفتاح التوقيع	64 حرفاً ست عشرياً	يمكن عرضه في المنصة. يوقّع إشعارات webhook ورموز الفتح.

التطبيق الجديد مسودة. المسودة لا تعمل إلا على المتاجر التي يملكها حسابك، وهذا ما تحتاجه للتجربة.

2. اختر الصلاحيات

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

3. اضبط روابط إعادة التوجيه

تقارن DZBuild قيمة redirect_uri التي ترسلها بالروابط المسجّلة كسلاسل نصية مطابقة حرفياً. شرطة مائلة في الآخر، أو اختلاف في حالة الأحرف، أو معامل استعلام زائد، كلها تجعل الرابط مختلفاً. الرابط الذي يحتوي على جزء (#) يُرفض عند حفظ التطبيق.

إذا لم يطابق redirect_uri، تعرض DZBuild صفحة خطأ ولا تعيد التوجيه إطلاقاً.

4. ثبّت التطبيق على متجرك

أنشئ مُحقِّق PKCE (verifier) وتحدّيه بطريقة S256. يبقى المُحقِّق على خادمك.

CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

وجّه متصفحك إلى رابط التفويض. رمّز كل قيمة، والمسافات بين الصلاحيات تصبح %20.

GET https://dzbuild.com/oauth/apps/authorize?response_type=code&client_id=dzapp_0123456789abcdef0123&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=store%3Aread%20orders%3Aread&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

سجّل الدخول إلى DZBuild إن طُلب منك. تعرض شاشة الموافقة متاجرك وتميّز التي لا يمكنها تثبيت التطبيق. اختر متجراً ووافق. تعيد DZBuild التوجيه إلى رابطك:

HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=CODE&state=STATE

تأكد أن state هي القيمة التي أرسلتها. الرمز صالح 10 دقائق ويُستعمل مرة واحدة.

استبدل الرمز برمز التثبيت. أرسل النموذج من خادمك، لا من المتصفح أبداً.

curl -s https://dzbuild.com/oauth/apps/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  --data-urlencode redirect_uri=https://app.example.com/callback \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id="$DZ_CLIENT_ID" \
  -d client_secret="$DZ_CLIENT_SECRET"

الرد الناجح يكون هكذا:

{
  "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928",
  "token_type": "Bearer",
  "scope": "store:read orders:read",
  "store_id": 141,
  "install_id": 7,
  "stores": [
    {
      "store_id": 141,
      "store_name": "My test store",
      "install_id": 7,
      "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928"
    }
  ]
}

احفظ كل access_token مع store_id وinstall_id الخاصين به. لا يوجد expires_in ولا رمز تحديث: يعمل الرمز إلى أن يزيل التاجر تطبيقك. تسرد صفحة OAuth كل خطأ قد يعيده هذا الطلب.

5. نفّذ أول طلب

استدعِ GET /v1/whoami برمز التثبيت. لا يحتاج أي صلاحية، لذا يعمل مع كل تثبيت.

curl -s https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer $DZ_TOKEN"

{
  "data": {
    "key_id": "dzpk_live_0a1b2c3d4e5f67",
    "store_id": 141,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["store:read", "orders:read"],
    "app": {
      "app_id": 3,
      "client_id": "dzapp_0123456789abcdef0123",
      "install_id": 7
    }
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

6. اقرأ كائن التطبيق

لا يظهر الكائن app إلا عندما ينتمي الرمز إلى تثبيت تطبيق. يخبر خادمك بالتطبيق والتثبيت اللذين نفّذا الطلب.

الحقل	المعنى
app_id	المعرّف الرقمي لتطبيقك على DZBuild.
client_id	المعرّف العلني لتطبيقك. قارنه بمعرّفك لترفض رموزاً صدرت لتطبيق آخر.
install_id	التثبيت الذي ينتمي إليه هذا الرمز. يبقى كما هو إذا أزال التاجر تطبيقك ثم ثبّته من جديد على المتجر نفسه.

قيمة rate_limit_tier هي enterprise لكل رمز تثبيت، مهما كانت خطة المتجر. حصتك الحقيقية هي الحدّ الخاص بكل تثبيت، الموضّح في المفاهيم الأساسية.

الخطوات التالية

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