يقوم مظهر المتجر على ثلاثة اختيارات، وهي التبويبات الثلاثة نفسها في صفحة القوالب بلوحة التحكم (/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: تحمل الاستجابة change_id الخاص به، وتكون قيمته null في الحالة النادرة التي يُحفظ فيها التبديل دون سجلّ تراجع، ويعرض 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
      }
    ],
    "fast_checkout": [
      {
        "key":           "classic",
        "title":         "Classique",
        "plan_required": "free",
        "active":        true,
        "can_use":       true,
        "current":       true
      },
      {
        "key":           "stepper",
        "title":         "Stepper",
        "plan_required": "enterprise",
        "active":        true,
        "can_use":       false,
        "current":       false
      }
    ],
    "variant_styles": [
      {
        "key":           "default",
        "title":         "Par défaut",
        "plan_required": "free",
        "active":        true,
        "can_use":       true,
        "current":       true
      },
      {
        "key":           "lux",
        "title":         "Luxe",
        "plan_required": "enterprise",
        "active":        true,
        "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` للقالب المستعمل.
`fast_checkout[].key`	string	القيمة التي ترسلها في `theme` إلى `POST /v1/store/fast-checkout-theme`.
`fast_checkout[].title`	string	اسم قالب النموذج بلغة المتجر.
`fast_checkout[].plan_required`	string	أدنى خطة تستطيع استعمال قالب النموذج.
`fast_checkout[].active`	bool	`false` لقالب النموذج الذي لم يعد قابلًا للاختيار.
`fast_checkout[].can_use`	bool	`true` عندما يكون قالب النموذج مفعّلًا وتبلغ خطة المتجر `plan_required`.
`fast_checkout[].current`	bool	`true` لقالب النموذج المستعمل. كل متجر يبدأ على `classic`.
`variant_styles[].key`	string	القيمة التي ترسلها في `style` إلى `POST /v1/store/variant-style`. العنصر الأول دائمًا هو `default`، وهو أداة الاختيار العادية دون أي نمط مضاف، تستطيع كل الخطط استعماله ويكون `current` ما دام المتجر يستعمله.
`variant_styles[].title`	string	اسم النمط بلغة المتجر.
`variant_styles[].plan_required`	string	أدنى خطة تستطيع استعمال النمط.
`variant_styles[].active`	bool	`false` للنمط الذي لم يعد قابلًا للاختيار.
`variant_styles[].can_use`	bool	`true` عندما يكون النمط مفعّلًا وتبلغ خطة المتجر `plan_required`.
`variant_styles[].current`	bool	`true` للنمط المستعمل. والنمط المحفوظ الذي لم يعد مفعّلًا يُحسب `default`.

الأخطاء

نفس أخطاء 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,
    "change_id":  813
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

عبر api.dzbuild.app، يُرجع طلب GET /v1/store/design المُرسَل مباشرة بعد التبديل القالبَ الجديد. و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	نعم	`key` من قائمة `fast_checkout` في `GET /v1/themes`. حروف لاتينية وأرقام و`_` و`-`، حتى 50 حرفًا.

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

يعرض GET /v1/themes هذه القوالب في fast_checkout، مع الخطة التي يحتاجها كل قالب وهل يستطيع المتجر استعماله وأيّها المستعمل، ويُرجع GET /v1/store أيضًا القالب المستعمل في fast_checkout_theme. كل متجر يبدأ على classic. يصف دليل التاجر القوالب كل واحد منها.

الطلب

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",
    "change_id": 814
  },
  "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	نعم	`key` من قائمة `variant_styles` في `GET /v1/themes`، حتى 50 حرفًا.

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

يعرض GET /v1/themes الأنماط في variant_styles، مع الخطة التي يحتاجها كل نمط وهل يستطيع المتجر استعماله وأيّها المستعمل، ويُرجع GET /v1/store أيضًا النمط المستعمل في variant_card_style. كل متجر يبدأ على default، وهو أداة الاختيار العادية دون أي نمط مضاف، وهو العنصر الأول في القائمة، ويستطيع أي متجر الرجوع إليه. المفتاح غير المعروف أو غير المفعّل يُرجع 404 style_not_found؛ ولا ترجع الواجهة البرمجية إلى default من تلقاء نفسها.

الطلب

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",
    "change_id": 815
  },
  "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` مع جسم آخر.

المقالات ذات الصلة