# القوالب

يقوم مظهر المتجر على ثلاثة اختيارات، وهي التبويبات الثلاثة نفسها في صفحة القوالب بلوحة التحكم (`/dashboard/themes`): قالب واجهة المتجر، وقالب نموذج الطلب السريع في صفحات المنتجات، ونمط اختيار المتغيرات. يعرض `GET /v1/themes` قوالب واجهة المتجر مع حكم خاص بالمتجر، ونداء `POST` واحد يبدّل كل اختيار من الاختيارات الثلاثة. أما الألوان والنصوص وباقي حقول التصميم فتُعدَّل عبر `PATCH /v1/store/design` (انظر [المتجر](https://dzbuild.com/ar/ar/api-docs/resources/store.md)). لمعرفة شكل كل قالب وما يتغيّر للزبائن، راجع دليل التاجر [القوالب](https://dzbuild.com/ar/ar/docs/customizing/themes.md).

## قبل أن تبدأ[​](#قبل-أن-تبدأ "رابط مباشر إلى قبل أن تبدأ")

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

## `GET /v1/themes`[​](#get-v1themes "رابط مباشر إلى get-v1themes")

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

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

### الطلب[​](#الطلب "رابط مباشر إلى الطلب")

```
curl https://api.dzbuild.app/v1/themes \

  -H "Authorization: Bearer $DZ_KEY"
```

### الاستجابة 200[​](#الاستجابة-200 "رابط مباشر إلى الاستجابة 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`. انظر [الأخطاء](https://dzbuild.com/ar/ar/api-docs/errors.md).

## `POST /v1/store/theme`[​](#post-v1storetheme "رابط مباشر إلى post-v1storetheme")

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

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

### الجسم[​](#الجسم "رابط مباشر إلى الجسم")

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

### التبديل إلى `digital`[​](#التبديل-إلى-digital "رابط مباشر إلى التبديل-إلى-digital")

`digital` هو القالب الذي يحمل `digital_only: true`. التبديل إليه يحوّل المتجر إلى متجر منتجات رقمية، وتحمل الاستجابة `is_digital: true`. وتبديل متجر رقمي إلى أي قالب آخر يعيده متجر منتجات مادية. يشرح دليل التاجر [القوالب](https://dzbuild.com/ar/ar/docs/customizing/themes.md) ما يتغيّر للزبائن.

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

### الطلب[​](#الطلب-1 "رابط مباشر إلى الطلب")

```
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[​](#الاستجابة-200-1 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "theme":      "bloom",

    "is_digital": false

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

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

### الأخطاء[​](#الأخطاء-1 "رابط مباشر إلى الأخطاء")

| 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`[​](#post-v1storefast-checkout-theme "رابط مباشر إلى post-v1storefast-checkout-theme")

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

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

### الجسم[​](#الجسم-1 "رابط مباشر إلى الجسم")

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

### قوالب الطلب السريع[​](#قوالب-الطلب-السريع "رابط مباشر إلى قوالب الطلب السريع")

لا يوجد نداء يعرض هذه القوالب، ولا قراءة تُرجع القالب المستعمل. كل متجر يبدأ على `classic`. يصف دليل التاجر [القوالب](https://dzbuild.com/ar/ar/docs/customizing/themes.md) كل واحد منها.

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

### الطلب[​](#الطلب-2 "رابط مباشر إلى الطلب")

```
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[​](#الاستجابة-200-2 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "fast_checkout_theme": "stepper"

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

### الأخطاء[​](#الأخطاء-2 "رابط مباشر إلى الأخطاء")

| 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`[​](#post-v1storevariant-style "رابط مباشر إلى post-v1storevariant-style")

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

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

### الجسم[​](#الجسم-2 "رابط مباشر إلى الجسم")

| الحقل   | النوع  | إلزامي | ملاحظات                              |
| ------- | ------ | ------ | ------------------------------------ |
| `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` |

### الطلب[​](#الطلب-3 "رابط مباشر إلى الطلب")

```
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[​](#الاستجابة-200-3 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "variant_card_style": "minimal"

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

### الأخطاء[​](#الأخطاء-3 "رابط مباشر إلى الأخطاء")

| 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` مع جسم آخر.                                       |