مرجع الواجهة البرمجية

يستدعي تطبيقك نفس واجهة REST التي يستعملها التجار، على العنوان https://api.dzbuild.app/v1. يصفها مرجعان، وتشرح هذه الصفحة ما يتغيّر عندما تستدعيها برمز تثبيت.

مرجعان

توثيق الواجهة البرمجية على dzbuild.com يشرح الموارد الرئيسية بمعاملاتها وردودها وأمثلتها، بثلاث لغات:

• الإنجليزية: dzbuild.com/api-docs
• العربية: dzbuild.com/ar/api-docs
• الفرنسية: dzbuild.com/fr/api-docs

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

وصف OpenAPI للتطبيقات ملف JSON واحد بصيغة OpenAPI 3.1. يسرد 92 عملية يستطيع رمز التثبيت استدعاءها، مع صلاحياتها ومعاملاتها وشكل ردودها. استورده في Postman أو Insomnia، أو ولّد منه الأنواع (types).

تنزيل dzbuild-apps-v1.json

curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json

يصرّح الملف بـ https://api.dzbuild.app خادمًا له. ويسرد مخطط الأمان dzOAuth فيه كل صلاحية مع وصف بالإنجليزية.

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

يمنحك تبادل الرمز رمز وصول واحدًا لكل متجر وافق عليه التاجر (راجع OAuth). يبدأ كل رمز بـ dzpk_live_. أرسله في ترويسة Authorization بمخطط Bearer:

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

الرمز هو الذي يحدّد المتجر. لا يوجد معامل للمتجر في الطلبات، فللعمل على متجر آخر للتاجر نفسه استعمل رمز ذلك المتجر من قائمة stores في رد التبادل. احفظ الرموز على خادمك. لا تنتهي صلاحيتها من تلقاء نفسها. يتوقف الرمز عن العمل عندما يزيل التاجر تطبيقك، أو عندما يعيد تثبيته على المتجر نفسه، فيُستبدل الرمز.

الحالة	الرسالة	السبب
401	Missing Authorization header	لا توجد ترويسة Authorization.
401	Unsupported Authorization scheme	الترويسة لا تبدأ بـ Bearer.
401	Invalid or revoked API key	الرمز خاطئ، أو أُلغي بسبب إزالة التطبيق.

يُفحص كل رمز تثبيت أيضًا مقابل حالة تطبيقك وحالة المتجر. الطلب المرفوض يُجاب بـ 403 مع أحد رموز الخطأ هذه:

رمز الخطأ	المعنى
app_uninstalled	لم يعد التطبيق مثبّتًا في هذا المتجر.
app_suspended	أوقفت DZBuild التطبيق.
app_not_approved	التطبيق في وضع التجربة ولا يعمل إلا في متاجر مطوّره.
app_plan_required	خطة المتجر أدنى من الخطة الدنيا التي حدّدتها للتطبيق.

الردود

يضع الرد الناجح النتيجة في data. ويضع الخطأ code وmessage داخل error. يحمل كلاهما meta.request_id، فاذكره عند التواصل مع DZBuild بشأن طلب ما.

{
  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

تُجيب نقاط الوصول التي تعيد قوائم بهذا الشكل:

{
  "data": { "items": [...], "next_cursor": "...", "has_more": true },
  "meta": { "request_id": "...", "api_version": "v1" }
}

أرسل next_cursor من جديد في المعامل cursor لتحصل على الصفحة التالية، وتوقّف عندما تكون قيمة has_more هي false. ويقبل GET /v1/orders أيضًا since (الطلبات المنشأة في ذلك الوقت أو بعده) وstatus وcustomer_phone.

whoami

لا تحتاج GET /v1/whoami أي صلاحية. تخبرك بالمتجر الذي ينتمي إليه الرمز وبما يستطيع فعله. وتضيف لرمز التثبيت كائن app:

{
  "data": {
    "key_id": "dzpk_live_3c9e1a7f5b2d80",
    "store_id": 1234,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["orders:read", "whatsapp:read", "whatsapp:send"],
    "app": {
      "app_id": 12,
      "client_id": "dzapp_4e1b9c07d2a86f35e0b1",
      "install_id": 57
    }
  },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

الحقل	المعنى
store_id	المتجر الذي يعمل عليه هذا الرمز.
scopes	الصلاحيات التي منحها التاجر.
rate_limit_tier	دائمًا enterprise لرموز التثبيت، مهما كانت خطة المتجر.
app.app_id	معرّف تطبيقك.
app.client_id	معرّف عميل OAuth لتطبيقك.
app.install_id	التثبيت في هذا المتجر. تستعمل حمولات webhook مثل app.uninstalled نفس المعرّف.

نقاط الوصول المغلقة أمام التطبيقات

تجيب نقاط الوصول هذه بـ 403 على رمز التثبيت، مهما كانت صلاحياته:

نقاط الوصول	الرد	السبب
/v1/keys و/v1/keys/{key_id}	Apps cannot use this endpoint	مفاتيح API ملك للتاجر.
/v1/webhooks وكل ما يتفرّع منها	Apps cannot use this endpoint	يُضبط webhook تطبيقك مرة واحدة في منصة المطورين لكل المتاجر (راجع Webhooks).
/v1/changes وكل ما يتفرّع منها، بما فيها التراجع	Apps cannot use this endpoint	سجل التعديلات والتراجع يبقيان للتاجر.

تحتاج POST /v1/landing-pages/generate إلى صلاحية ai:generate، ولا تستطيع التطبيقات طلبها لأنها تستهلك رصيد الذكاء الاصطناعي للتاجر. تُجاب بـ 403 مع Missing scope: ai:generate.