القوالب

يقوم مظهر المتجر على ثلاثة اختيارات، وهي التبويبات الثلاثة نفسها في صفحة القوالب بلوحة التحكم (/dashboard/themes): قالب واجهة المتجر، وقالب نموذج الطلب السريع في صفحات المنتجات، ونمط اختيار المتغيرات. يعرض GET /v1/themes قوالب واجهة المتجر مع حكم خاص بالمتجر، ونداء POST واحد يبدّل كل اختيار من الاختيارات الثلاثة. أما الألوان والنصوص وباقي حقول التصميم فتُعدَّل عبر PATCH /v1/store/design (انظر المتجر). لمعرفة شكل كل قالب وما يتغيّر للزبائن، راجع دليل التاجر القوالب.

قبل أن تبدأ

• يحتاج GET /v1/themes إلى store:read. وتحتاج نداءات التبديل الثلاثة إلى store:write وإلى Idempotency-Key. مفاتيح التاجر تحمل الصلاحيتين.
• لكل قالب ونمط خطة دنيا. ترتيب الخطط هو free ثم pro ثم unlimited ثم enterprise، وكل خطة تفتح ما تفتحه الخطط التي تحتها. التبديل إلى قالب أو نمط أعلى من خطة المتجر يُرجع 403 plan_required. والخطة المدفوعة التي انتهت صلاحيتها تُحسب free.
• مفتاح التاجر تابع لمتجر على خطة Enterprise سارية، لذا كل القوالب والأنماط مفتوحة له. أما رموز التطبيقات المثبّتة فتعمل مع كل الخطط وتخضع لهذه الحدود.
• يُحفَظ التبديل بمجرد أن يُرجع النداء استجابته. لا توجد خطوة تأكيد.
• تُعاد الاستجابة الأولى لكل Idempotency-Key طوال 24 ساعة، بما فيها أخطاء 4xx. بعد تغيّر خطة المتجر، أرسل التبديل من جديد بمفتاح جديد. انظر Idempotency.
• كل تبديل يُسجَّل ويمكن التراجع عنه عبر POST /v1/changes/{change_id}/undo؛ تجد رقمه عبر GET /v1/changes?entity=store.theme. لا يستطيع رمز التطبيق المثبّت قراءة التغييرات ولا التراجع عنها: كلاهما يُرجع 403 forbidden (Apps cannot use this endpoint).

GET /v1/themes

يعرض قوالب واجهة المتجر مع الخطة التي يحتاجها كل قالب وهل يستطيع هذا المتجر استعماله، إضافةً إلى مفتاح القالب المستعمل. تأتي القائمة كاملة في استجابة واحدة دون تقسيم إلى صفحات. والقالب الذي لم يعد قابلًا للاختيار يبقى في القائمة مع active: false.

المصادقة: مفتاح منصة بصلاحية store:read. هذا النداء غير مُخزَّن مؤقتًا: كل استجابة تقرأ الحالة الحالية.

الطلب

curl https://api.dzbuild.app/v1/themes \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

تظهر ثلاثة عناصر فقط. تأتي العناوين بلغة المتجر، وهذا المتجر مضبوط على الفرنسية.

{
  "data": {
    "current": "starter",
    "items": [
      {
        "key":           "starter",
        "title":         "Starter",
        "plan_required": "free",
        "active":        true,
        "color_mode":    "light",
        "digital_only":  false,
        "can_use":       true,
        "current":       true
      },
      {
        "key":           "digital",
        "title":         "Digital",
        "plan_required": "free",
        "active":        true,
        "color_mode":    "dark",
        "digital_only":  true,
        "can_use":       true,
        "current":       false
      },
      {
        "key":           "ariana",
        "title":         "Ariana",
        "plan_required": "unlimited",
        "active":        false,
        "color_mode":    "dark",
        "digital_only":  false,
        "can_use":       false,
        "current":       false
      }
    ]
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

مرجع الحقول

الحقل	النوع	ملاحظات
current	string	مفتاح القالب الذي يستعمله المتجر.
items[].key	string	القيمة التي ترسلها في theme إلى POST /v1/store/theme.
items[].title	string	اسم القالب بلغة المتجر: بالعربية، أو بالفرنسية لمتجر لغته الفرنسية.
items[].plan_required	string	أدنى خطة تستطيع استعمال القالب.
items[].active	bool	false للقالب الذي لم يعد قابلًا للاختيار.
items[].color_mode	string	light أو dark.
items[].digital_only	bool	true للقالب المخصّص للمنتجات الرقمية وحدها. اختياره يغيّر نوع المتجر، كما هو موصوف تحت POST /v1/store/theme.
items[].can_use	bool	true عندما يكون القالب مفعّلًا وتبلغ خطة المتجر plan_required.
items[].current	bool	true للقالب المستعمل.

الأخطاء

نفس أخطاء GET /v1/store: 401 unauthorized و402 quota_exceeded و403 forbidden و404 not_found و429 rate_limited. انظر الأخطاء.

POST /v1/store/theme

يبدّل قالب واجهة المتجر. لا يتغيّر إلا القالب: تبقى الألوان والنصوص وباقي قيم التصميم كما هي، ويعرض القالب الجديد ما يستعمله منها. التبديل إلى digital هو الاستثناء الموصوف أدناه.

المصادقة: مفتاح منصة بصلاحية store:write. يتطلب Idempotency-Key.

الجسم

الحقل	النوع	إلزامي	ملاحظات
theme	string	نعم	قيمة key من GET /v1/themes. حروف لاتينية وأرقام و_ و-، حتى 50 حرفًا.

التبديل إلى digital

digital هو القالب الذي يحمل digital_only: true. التبديل إليه يحوّل المتجر إلى متجر منتجات رقمية، وتحمل الاستجابة is_digital: true. وتبديل متجر رقمي إلى أي قالب آخر يعيده متجر منتجات مادية. يشرح دليل التاجر القوالب ما يتغيّر للزبائن.

يستبدل التبديل إلى digital أيضًا الألوان التي ما زالت على القيم الفاتحة الأصلية، مثل خلفية #ffffff، بلوحة الألوان الداكنة لقالب Digital. أما الألوان التي اختارها التاجر فتبقى. والتراجع عن التبديل يعيد القالب السابق وتلك الألوان.

الطلب

curl -X POST https://api.dzbuild.app/v1/store/theme \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-theme-1" \
  -d '{"theme": "bloom"}'

الاستجابة 200

{
  "data": {
    "theme":      "bloom",
    "is_digital": false
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

عبر api.dzbuild.app، قد يُظهر طلب GET /v1/store/design المُرسَل مباشرة بعد التبديل القالبَ القديم لمدة تصل إلى 30 ثانية. أما GET /v1/themes فغير مُخزَّن مؤقتًا.

الأخطاء

HTTP	الكود	السبب
400	bad_request	الجسم ليس JSON صالحًا، أو Idempotency-Key غائب أو غير صالح.
403	forbidden	Missing scope: store:write، أو مفتاح تاجر متجره ليس على خطة Enterprise سارية.
403	plan_required	القالب يحتاج خطة أعلى. تذكر الرسالة تلك الخطة وخطة المتجر.
404	theme_not_found	لا يوجد قالب مفعّل بهذا المفتاح.
404	store_not_found	حُذف المتجر.
422	invalid_theme	theme غائب، أو أطول من 50 حرفًا، أو يحتوي حرفًا غير الحروف اللاتينية والأرقام و_ و-.
422	idempotency_key_reuse	استُعمل نفس Idempotency-Key مع جسم آخر.

POST /v1/store/fast-checkout-theme

يبدّل شكل نموذج الطلب السريع في صفحات المنتجات. تبقى نصوص النموذج وألوانه وخياراته، وهي من حقول PATCH /v1/store/design، كما هي.

المصادقة: مفتاح منصة بصلاحية store:write. يتطلب Idempotency-Key.

الجسم

الحقل	النوع	إلزامي	ملاحظات
theme	string	نعم	مفتاح من الجدول أدناه. حروف لاتينية وأرقام و_ و-، حتى 50 حرفًا.

قوالب الطلب السريع

لا يوجد نداء يعرض هذه القوالب، ولا قراءة تُرجع القالب المستعمل. كل متجر يبدأ على classic. يصف دليل التاجر القوالب كل واحد منها.

theme	الخطة
classic	free
commerce	pro
editorial	unlimited
compact	enterprise
stepper	enterprise

الطلب

curl -X POST https://api.dzbuild.app/v1/store/fast-checkout-theme \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-fc-theme-1" \
  -d '{"theme": "stepper"}'

الاستجابة 200

{
  "data": {
    "fast_checkout_theme": "stepper"
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

الأخطاء

HTTP	الكود	السبب
400	bad_request	الجسم ليس JSON صالحًا، أو Idempotency-Key غائب أو غير صالح.
403	forbidden	Missing scope: store:write، أو مفتاح تاجر متجره ليس على خطة Enterprise سارية.
403	plan_required	القالب يحتاج خطة أعلى من خطة المتجر.
404	theme_not_found	لا يوجد قالب طلب سريع مفعّل بهذا المفتاح.
404	store_not_found	حُذف المتجر.
422	invalid_theme	theme غائب، أو أطول من 50 حرفًا، أو يحتوي حرفًا غير الحروف اللاتينية والأرقام و_ و-.
422	idempotency_key_reuse	استُعمل نفس Idempotency-Key مع جسم آخر.

POST /v1/store/variant-style

يبدّل طريقة عرض خيارات المتغيرات، مثل المقاسات والألوان، في صفحات المنتجات.

المصادقة: مفتاح منصة بصلاحية store:write. يتطلب Idempotency-Key.

الجسم

الحقل	النوع	إلزامي	ملاحظات
style	string	نعم	مفتاح من الجدول أدناه، حتى 50 حرفًا.

أنماط المتغيرات

لا يوجد نداء يعرض الأنماط، ولا قراءة تُرجع النمط المستعمل. كل متجر يبدأ على default، وهو أداة الاختيار العادية دون أي نمط مضاف، ويستطيع أي متجر الرجوع إليه. المفتاح غير المعروف أو غير المفعّل يُرجع 404 style_not_found؛ ولا ترجع الواجهة البرمجية إلى default من تلقاء نفسها.

الخطة	style
كل الخطط	default
pro	minimal، clay، softplay، stacked
unlimited	editorial، material، offer
enterprise	brutal، glass، lux، mashrabiya، pixel

الطلب

curl -X POST https://api.dzbuild.app/v1/store/variant-style \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-variant-style-1" \
  -d '{"style": "minimal"}'

الاستجابة 200

{
  "data": {
    "variant_card_style": "minimal"
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

الأخطاء

HTTP	الكود	السبب
400	bad_request	الجسم ليس JSON صالحًا، أو Idempotency-Key غائب أو غير صالح.
403	forbidden	Missing scope: store:write، أو مفتاح تاجر متجره ليس على خطة Enterprise سارية.
403	plan_required	النمط يحتاج خطة أعلى من خطة المتجر.
404	style_not_found	لا يوجد نمط مفعّل بهذا المفتاح.
404	store_not_found	حُذف المتجر.
422	invalid_style	style غائب أو فارغ أو أطول من 50 حرفًا.
422	idempotency_key_reuse	استُعمل نفس Idempotency-Key مع جسم آخر.