القوالب
يقوم مظهر المتجر على ثلاثة اختيارات، وهي التبويبات الثلاثة نفسها في صفحة القوالب بلوحة التحكم (/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 مع جسم آخر. |