# المتجر

"المتجر" هو الحاوية الأعلى مستوى للمنتجات والطلبات والعملاء. كل مفتاح مرتبط بـ **متجر واحد فقط**. لا توجد طريقة لاستعلام متاجر تجار آخرين.

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

تُرجع ملف المتجر الذي ينتمي إليه المفتاح المنادي.

**المصادقة:** مفتاح منصة بصلاحية `store:read`. مفاتيح التاجر تحملها افتراضيًا؛ والمفتاح الذي لا يحملها يتلقى `403 forbidden` (`Missing scope: store:read`).

تُخدَم حديثًا في كل نداء: يظهر تعديل لوحة التحكم في طلب `GET` التالي عبر `api.dzbuild.app` وعبر العنوان البديل `dzbuild.com/api/v1/store`.

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

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

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

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

```
{

  "data": {

    "id":         12345,

    "name":       "My Store",

    "slug":       "my-store",

    "language":   "ar",

    "description": "Short tagline",

    "logo":       "/uploads/logos/12345/logo.webp",

    "favicon":    null,

    "banner":     null,

    "theme": {

      "primary_color":    "#f59e0b",

      "secondary_color":  "#fbbf24",

      "background_color": "#ffffff",

      "font_family":      "Cairo"

    },

    "store_theme":          "starter",

    "fast_checkout_theme":  "classic",

    "variant_card_style":   "default",

    "subdomain":            "my-store.dzbuild.app",

    "custom_domain":        null,

    "custom_domain_verified": false,

    "public_url":            "https://my-store.dzbuild.app",

    "hide_branding":         false,

    "created_at":            "2026-01-01 12:00:00"

  },

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

}
```

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

| الحقل                    | النوع        | ملاحظات                                                                                                                                                     |
| ------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | int          | معرّف داخلي ثابت. يطابق `store_id` في كل المواضع الأخرى.                                                                                                    |
| `name`                   | string       | الاسم المعروض. يظهر في شريط واجهة المتجر والإيميلات.                                                                                                        |
| `slug`                   | string       | معرّف صالح للروابط. يُستخدم في `<slug>.dzbuild.app` وغيرها.                                                                                                 |
| `language`               | enum         | `ar` أو `fr`. تحدد اتجاه الواجهة RTL/LTR.                                                                                                                   |
| `description`            | string\|null | عبارة قصيرة.                                                                                                                                                |
| `logo`                   | string\|null | مسار على `cdn.dzbuild.app` إن كان معيّنًا. ضع CDN الأساسي قبله إن أردت عرضه.                                                                                |
| `favicon`                | string\|null | نفس المنطق.                                                                                                                                                 |
| `banner`                 | string\|null | نفس المنطق.                                                                                                                                                 |
| `theme.primary_color`    | hex string   | لون الأزرار والإبرازات الأساسي.                                                                                                                             |
| `theme.secondary_color`  | hex string   | إبرازات ثانوية.                                                                                                                                             |
| `theme.background_color` | hex string   | خلفية الصفحة.                                                                                                                                               |
| `theme.font_family`      | string       | الخط (الافتراضي `Cairo`).                                                                                                                                   |
| `store_theme`            | string       | مفتاح قالب واجهة المتجر المستعمل، وهو نفسه `current` في `GET /v1/themes`. للقراءة فقط هنا: يُبدَّل عبر `POST /v1/store/theme`.                              |
| `fast_checkout_theme`    | string       | مفتاح قالب نموذج الطلب السريع، وهو `classic` ما لم يختر التاجر غيره. يُبدَّل عبر `POST /v1/store/fast-checkout-theme`.                                      |
| `variant_card_style`     | string       | مفتاح نمط اختيار المتغيرات، وهو `default` إذا لم يُضبط أي نمط. يُبدَّل عبر `POST /v1/store/variant-style`.                                                  |
| `subdomain`              | string\|null | النطاق الفرعي الصادر عن DZBuild. حاضر عادةً؛ ويكون `null` إذا لم يُضبط للمتجر نطاق فرعي بعد.                                                                |
| `custom_domain`          | string\|null | نطاق التاجر الخاص. يُعيَّن فقط إن أُضيف من لوحة التحكم.                                                                                                     |
| `custom_domain_verified` | bool         | `true` بمجرد تأكيد إعدادات DNS للنطاق. قد تكون شهادة الأمان والفحص الأخير لا يزالان جاريين عندها؛ ولا ينتقل `public_url` إلى النطاق إلا عندما يعمل بالكامل. |
| `public_url`             | string\|null | حيث يصل العملاء فعلًا: نطاق التاجر الخاص عندما يعمل بالكامل ويكون مضبوطًا كالعنوان الرئيسي للمتجر، وإلا فالنطاق الفرعي؛ ويكون `null` إن لم يوجد أيٌّ منهما. |
| `hide_branding`          | bool         | إخفاء "Powered by DZBuild" في الواجهة. لخطة غير محدود.                                                                                                      |
| `created_at`             | timestamp    | وقت إنشاء المتجر بتوقيت الجزائر (UTC+01:00).                                                                                                                |

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

| HTTP | الكود            | السبب                                                                                                                                                                                                            |
| ---- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `unauthorized`   | مفتاح خاطئ أو مفقود                                                                                                                                                                                              |
| 402  | `quota_exceeded` | استُنفدت حصة الطلبات الشهرية للمتجر — راجع [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md)                                                                                                      |
| 403  | `forbidden`      | `Missing scope: store:read`؛ أو مفتاح تاجر متجره ليس على خطة Enterprise سارية ("API access requires an active Enterprise plan")؛ أو وضع البايلوت: المفتاح غير مُسجَّل ("API is in pilot mode; key not enrolled") |
| 404  | `not_found`      | حُذف المتجر أثناء استخدامك للمفتاح (نادر جدًا)                                                                                                                                                                   |
| 429  | `rate_limited`   | تجاوز الحد الدقيقي لهذا المتجر، وهو مشترك بين كل مفاتيحه؛ احترم `Retry-After`. راجع [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md)                                                             |

## `PATCH /v1/store`[​](#patch-v1store "رابط مباشر إلى patch-v1store")

تُحدّث هذه النقطة ملف إعدادات المتجر، بنفس حقول صفحة إعدادات المتجر في لوحة التحكم ما عدا رقم WhatsApp. لا يتغيّر إلا ما ترسله من حقول.

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

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

| الحقل                      | النوع        | ملاحظات                                                                             |
| -------------------------- | ------------ | ----------------------------------------------------------------------------------- |
| `store_name`               | string       | حتى 100 حرف. لا يمكن أن يكون فارغًا.                                                |
| `description`              | string       | حتى 5000 حرف.                                                                       |
| `wilaya_id`                | int\|null    | رقم ولاية من `GET /v1/wilayas` (يتطلب `shipping:read`). القيمة `0` أو `null` تمسحه. |
| `commune`                  | string       | حتى 100 حرف.                                                                        |
| `address`                  | string       | حتى 500 حرف.                                                                        |
| `store_phone`              | string       | حتى 20 حرفًا.                                                                       |
| `store_email`              | string\|null | عنوان بريد إلكتروني صالح. القيمة `""` أو `null` تمسحه.                              |
| `google_site_verification` | string\|null | رمز التحقق من Google Search Console، حتى 100 حرف. القيمة `""` أو `null` تمسحه.      |
| `bing_site_verification`   | string\|null | رمز التحقق من Bing Webmaster، حتى 100 حرف. القيمة `""` أو `null` تمسحه.             |

تُحذف وسوم HTML من القيم النصية، ويُقصّ النص الأطول عند الحد. لا تشمل هذه النقطة `slug` ولا النطاق المخصص ولا الألوان؛ الألوان وباقي قيم التصميم تُعدَّل عبر `PATCH /v1/store/design`.

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

```
curl -X PATCH https://api.dzbuild.app/v1/store \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: store-profile-1" \

  -d '{"store_phone": "0550000000", "description": "Short tagline"}'
```

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

```
{

  "data": {

    "updated": ["description", "store_phone"],

    "values":  {"description": "Short tagline", "store_phone": "0550000000"}

  },

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

}
```

يُسجَّل التغيير ويمكن التراجع عنه عبر `POST /v1/changes/{change_id}/undo`؛ تجد رقمه عبر `GET /v1/changes?entity=store.settings`. وطلب `GET /v1/store` المُرسَل مباشرة بعد الكتابة يُرجع القيم الجديدة.

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

| HTTP | الكود                   | السبب                                                                           |
| ---- | ----------------------- | ------------------------------------------------------------------------------- |
| 400  | `bad_request`           | الجسم ليس JSON صالحًا، أو `Idempotency-Key` غائب أو غير صالح.                   |
| 403  | `forbidden`             | `Missing scope: store:write`، أو مفتاح تاجر متجره ليس على خطة Enterprise سارية. |
| 404  | `store_not_found`       | حُذف المتجر.                                                                    |
| 422  | `no_writable_fields`    | الجسم لا يحتوي أيًّا من الحقول أعلاه.                                           |
| 422  | `invalid_value`         | حقلٌ قيمته كائن أو قائمة، أو `store_name` فارغ.                                 |
| 422  | `invalid_wilaya`        | `wilaya_id` ليس ولاية معروفة.                                                   |
| 422  | `invalid_email`         | `store_email` ليس عنوان بريد إلكتروني صالحًا.                                   |
| 422  | `idempotency_key_reuse` | استُعمل نفس `Idempotency-Key` مع جسم آخر.                                       |

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

تُرجع تصميم المتجر: حقول صفحة التخصيص في لوحة التحكم (`/dashboard/customize`) الخاصة بالقالب الحالي للمتجر، مجمَّعة في الأقسام نفسها، مع القيمة الحالية لكل حقل. بعض القوالب تُخفي بعض هذه الحقول في تلك الصفحة، أما الواجهة البرمجية فتعرضها كلها.

**المصادقة:** مفتاح منصة بصلاحية `store:read`.

تُخدَم حديثًا عبر `api.dzbuild.app`، مثل `GET /v1/store`. وتحمل استجابة `PATCH /v1/store/design` أيضًا القيم المكتوبة في `values`.

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

```
curl https://api.dzbuild.app/v1/store/design \

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

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

يظهر قسمان، مع بعض حقولهما.

```
{

  "data": {

    "theme": "starter",

    "plan":  "enterprise",

    "sections": [

      {

        "key":  "theme",

        "name": {"ar": "الألوان والخط", "fr": "Couleurs et Police"},

        "plan_required": "free",

        "page": "home",

        "fields": [

          {"key": "primary_color", "type": "color", "plan_required": "free", "writable": true, "locked": false, "value": "#f59e0b"},

          {"key": "background_color", "type": "color", "plan_required": "pro", "writable": true, "locked": false, "value": "#ffffff"},

          {"key": "font_family", "type": "select", "plan_required": "free", "writable": true, "locked": false, "value": "Cairo"}

        ]

      },

      {

        "key":  "productCard",

        "name": {"ar": "بطاقة المنتج", "fr": "Carte produit"},

        "plan_required": "free",

        "page": "home",

        "fields": [

          {"key": "card_hide_price", "type": "switch", "plan_required": "free", "writable": true, "locked": false, "value": false},

          {"key": "card_border_radius", "type": "select", "plan_required": "free", "writable": true, "locked": false, "allowed_values": ["0px", "8px", "16px", "24px"], "value": "16px"}

        ]

      }

    ]

  },

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

}
```

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

| الحقل                      | النوع  | ملاحظات                                                                                                                                                    |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme`                    | string | مفتاح القالب الذي يستعمله المتجر. انظر [القوالب](https://dzbuild.com/ar/ar/api-docs/resources/themes.md).                                                  |
| `plan`                     | string | الخطة التي تُحسب عليها الأقفال: `free` أو `pro` أو `unlimited` أو `enterprise`. والخطة المدفوعة التي انتهت صلاحيتها تُحسب `free`.                          |
| `sections[].key`           | string | معرّف القسم، مثل `header` أو `theme` أو `productCard` أو `checkoutPage`.                                                                                   |
| `sections[].name`          | object | عنوان القسم كما تعرضه لوحة التحكم، بـ `ar` و`fr`.                                                                                                          |
| `sections[].plan_required` | string | الخطة التي تعرضها لوحة التحكم على القسم.                                                                                                                   |
| `sections[].page`          | string | `home` عندما تعرض صفحة التخصيص القسم تحت معاينة الصفحة الرئيسية، و`all` عندما تعرضه في كل المعاينات.                                                       |
| `sections[].fields`        | array  | حقول القسم. قد تكون فارغة: بعض الأقسام، مثل `helpWidget` وكتل الصفحة الرئيسية لقالب Digital، لا تُحفظ عبر حقول التصميم.                                    |
| `fields[].key`             | string | الاسم الذي ترسله في `PATCH /v1/store/design`.                                                                                                              |
| `fields[].type`            | string | عنصر التحكم في لوحة التحكم: `text` أو `textarea` أو `color` أو `select` أو `switch`.                                                                       |
| `fields[].plan_required`   | string | الخطة التي تعرضها لوحة التحكم على الحقل.                                                                                                                   |
| `fields[].writable`        | bool   | `false` عندما لا تقبل الواجهة البرمجية الحقل. `custom_js` منها: يُضبط من لوحة التحكم فقط.                                                                  |
| `fields[].locked`          | bool   | `true` عندما لا تسمح خطة المتجر بكتابة الحقل عبر الواجهة البرمجية. اعتمد على هذه القيمة، لا على `plan_required`، لتعرف هل ستُطبَّق الكتابة.                |
| `fields[].allowed_values`  | array  | في الحقول ذات الخيارات المحددة فقط: القيم التي يقبلها الحقل.                                                                                               |
| `fields[].value`           | any    | القيمة الحالية. حقول `switch` تعود `true` أو `false`، و`products_per_page` رقمًا، والباقي كما هو محفوظ. وتكون `null` عندما لا توجد للمتجر قيمة لهذا الحقل. |

## `GET /v1/store/design/fields`[​](#get-v1storedesignfields "رابط مباشر إلى get-v1storedesignfields")

القائمة نفسها دون المفتاح `value`. استدعها قبل الكتابة لترى الحقول التي يعرضها قالب المتجر، والاسم الذي ترسله لكل حقل، والحقول التي تقفلها الخطة.

**المصادقة:** مفتاح منصة بصلاحية `store:read`. تُخدَم حديثًا عبر `api.dzbuild.app`، مثل `GET /v1/store`.

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

```
curl https://api.dzbuild.app/v1/store/design/fields \

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

### الاستجابة 200[​](#الاستجابة-200-3 "رابط مباشر إلى الاستجابة 200")

يظهر القسمان الأخيران.

```
{

  "data": {

    "theme": "starter",

    "plan":  "enterprise",

    "sections": [

      {

        "key":  "customCss",

        "name": {"ar": "CSS مخصّص", "fr": "CSS personnalisé"},

        "plan_required": "enterprise",

        "page": "all",

        "fields": [

          {"key": "custom_css", "type": "textarea", "plan_required": "enterprise", "writable": true, "locked": false}

        ]

      },

      {

        "key":  "customJs",

        "name": {"ar": "JavaScript مخصّص", "fr": "JavaScript personnalisé"},

        "plan_required": "enterprise",

        "page": "all",

        "fields": [

          {"key": "custom_js", "type": "textarea", "plan_required": "enterprise", "writable": false, "locked": false}

        ]

      }

    ]

  },

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

}
```

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

يُرجع `GET /v1/store/design` و`GET /v1/store/design/fields` نفس أخطاء `GET /v1/store`: `401 unauthorized` و`402 quota_exceeded` و`403 forbidden` (`Missing scope: store:read` أو الخطة أو البايلوت) و`404 not_found` و`429 rate_limited`.

## `PATCH /v1/store/design`[​](#patch-v1storedesign "رابط مباشر إلى patch-v1storedesign")

تُعدّل حقول التصميم: الألوان، والرأسية، والـ hero، وبطاقات المنتجات، وصفحة المنتج، ونصوص صفحة الطلب، والتذييل، وروابط التواصل الاجتماعي، والـ SEO وغيرها. لا يتغيّر إلا ما ترسله من حقول. الألوان و`hide_branding` تُضبط هنا، لا عبر `PATCH /v1/store`.

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

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

أرسل أي حقل يعرضه `GET /v1/store/design/fields` مع `writable: true`. وتُقبل أيضًا حقول التصميم التي لا يعرضها القالب الحالي: تُحفظ، ويستعملها القالب الذي يعرضها. والمفاتيح التي لا تعرفها الواجهة البرمجية تُتجاهل. تُنظَّف كل قيمة حسب نوعها:

| النوع        | أمثلة                                                               | ما يُحفظ                                                                                                                                                                            |
| ------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| تشغيل وإيقاف | `show_hero`، `navbar_sticky`، `card_hide_price`                     | أرسل `true` أو `false`. وتُظهر الاستجابة `1` أو `0`.                                                                                                                                |
| لون          | `primary_color`، `navbar_color`، `footer_color`                     | قيمة `#RRGGBB`. القيمة `null` تمسحه. وأي قيمة أخرى تُستبدل باللون الافتراضي للحقل، مثل `#f59e0b` لـ `primary_color`.                                                                |
| لون بديل     | `announcement_bg_color`، `product_buy_now_color`، `fc_button_color` | قيمة `#RRGGBB`. وأي شيء آخر يمسح اللون البديل.                                                                                                                                      |
| نص           | `hero_title`، `footer_about`، `seo_description`                     | تُحذف وسوم HTML ويُقصّ النص عند طول الحقل، مثل 255 حرفًا لـ `hero_title` و2000 لـ `footer_about`.                                                                                   |
| رابط         | `hero_button_link`، `facebook`، `custom_link_url`                   | رابط `https://` أو `http://` أو `mailto:` أو `tel:`، أو `/path`، أو `#anchor`، أو اسم حساب مجرّد، يُقصّ عند 255 حرفًا (20 لـ `whatsapp`). وأي بروتوكول آخر يُرجع `422 invalid_url`. |
| خيار محدد    | `card_border_radius`، `checkout_layout`، `store_language`           | إحدى قيم `allowed_values` للحقل. وأي قيمة أخرى تُحفظ كقيمة الحقل الافتراضية.                                                                                                        |
| رقم          | `products_per_page`                                                 | يبقى بين 4 و48.                                                                                                                                                                     |

لبعض الحقول قواعدها الخاصة:

* `font_family`: حروف لاتينية وأرقام ومسافات وشرطات. وأي شيء آخر يُحفظ `Cairo`. تقترح لوحة التحكم `Cairo` و`Tajawal` و`Almarai`.
* `button_style`: تقترح لوحة التحكم `rounded` و`square` و`pill`.
* `navbar_style` يقبل `default` أو `centered` أو `minimal` أو `transparent`؛ و`navbar_menu_style` يقبل `default` أو `pills` أو `underline` أو `buttons`؛ و`navbar_logo_size` يقبل `small` أو `medium` أو `large`؛ و`cart_icon_style` يقبل `default` أو `filled` أو `outline` أو `minimal`. هذه الحقول الأربعة لا تحمل `allowed_values`، وأي قيمة أخرى ترفض الكتابة كلها بـ `422 invalid_value`.
* `facebook_pixel_id`: من 15 إلى 17 رقمًا، أو فارغ لمسحه.
* `custom_css`: لخطة Enterprise فقط. يُنظَّف قبل حفظه.

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

| الحقل                 | القيم                           | ما يغيّره                                                                                                                                                                  |
| --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `buybar_show_mobile`  | `true` (الافتراضي) أو `false`   | القيمة `false` تُخفي شريط الشراء المثبّت أسفل صفحات المنتجات على الهاتف. ويبقى الشريط ظاهراً إذا كان نموذج الطلب السريع مُطفأً، فيبقى زرّ الشراء ظاهراً على الهاتف دائماً. |
| `buybar_show_qty`     | `true` (الافتراضي) أو `false`   | القيمة `false` تحذف زرّي الكمية من شريط الشراء، على الهاتف والحاسوب.                                                                                                       |
| `fc_show_qty`         | `true` (الافتراضي) أو `false`   | القيمة `false` تحذف الكمية من نموذج الطلب السريع. فيطلب الزبون قطعة واحدة، إلا إذا اختار عرضاً أو كمية في شريط الشراء، أو كان للمنتج حدّ أدنى للكمية.                      |
| `product_button_size` | `normal` (الافتراضي) أو `large` | القيمة `large` تجعل أزرار شريط الشراء وزرّ الطلب في نموذج الطلب السريع بارتفاع 56 بكسل، ونصّها بحجم 17 بكسل. وأي قيمة أخرى تُحفظ `normal`.                                 |

لا يملك قالب Digital نموذج طلب سريع: هناك لا يغيّر `fc_show_qty` شيئاً، و`buybar_show_mobile: false` يُخفي شريط الهاتف بينما تبقى أزرار الشراء في الصفحة.

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

الحقل الذي تقفله خطة المتجر لا يُكتب. يظهر في `skipped` مع السبب، ويُرجع النداء `200` رغم ذلك إذا كُتب حقل آخر. وإذا تُجووزت كل الحقول التي أرسلتها، يُرجع النداء `422 no_writable_fields`.

| السبب في `skipped`             | متى                                                                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `requires a paid plan`         | حقل محجوز لخطة `pro` وما فوقها، مثل `background_color` أو `navbar_color` أو `hide_branding` أو حقول شريط الإعلان، أُرسل لمتجر على `free`.       |
| `requires the enterprise plan` | `custom_css` على أي خطة غير `enterprise`.                                                                                                       |
| `requires the unlimited plan`  | `hide_branding: true` لمتجر على `pro`. ويستطيع متجر `pro` إرسال `hide_branding: false`، فتعود عبارة `Powered by DZBuild` إلى الظهور في التذييل. |

مفتاح التاجر تابع لمتجر على خطة Enterprise سارية، لذا لا يُقفل عليه أي حقل. وتنطبق الأقفال على رموز التطبيقات المثبّتة، التي تعمل مع كل الخطط.

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

```
curl -X PATCH https://api.dzbuild.app/v1/store/design \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: store-design-1" \

  -d '{"primary_color": "#0f766e", "show_hero": true, "hero_title": "New collection"}'
```

### الاستجابة 200[​](#الاستجابة-200-4 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "updated": ["primary_color", "show_hero", "hero_title"],

    "skipped": [],

    "values":  {"primary_color": "#0f766e", "show_hero": 1, "hero_title": "New collection"},

    "change_id": 812

  },

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

}
```

يذكر `updated` الحقول التي كُتبت، ويذكر `values` القيمة المحفوظة لكل منها بعد التنظيف. يكون `skipped` قائمة فارغة إذا لم يُتجاوز شيء، وإلا فكائنًا مثل `{"hide_branding": "requires the unlimited plan"}`.

يُسجَّل التغيير ويمكن التراجع عنه عبر `POST /v1/changes/{change_id}/undo` بقيمة `change_id` الموجودة في الاستجابة؛ وتكون `null` في الحالة النادرة التي تُحفظ فيها الكتابة دون سجلّ تراجع، ويعرض `GET /v1/changes?entity=store.design` التغييرات السابقة. ولا يستطيع رمز التطبيق المثبّت قراءة التغييرات ولا التراجع عنها (`403 forbidden`، `Apps cannot use this endpoint`). وطلب `GET /v1/store/design` المُرسَل مباشرة بعد الكتابة يُرجع القيم الجديدة.

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

| HTTP | الكود                   | السبب                                                                           |
| ---- | ----------------------- | ------------------------------------------------------------------------------- |
| 400  | `bad_request`           | الجسم ليس JSON صالحًا، أو `Idempotency-Key` غائب أو غير صالح.                   |
| 403  | `forbidden`             | `Missing scope: store:write`، أو مفتاح تاجر متجره ليس على خطة Enterprise سارية. |
| 404  | `store_not_found`       | حُذف المتجر.                                                                    |
| 413  | `payload_too_large`     | حجم الجسم أكبر من 1 MB.                                                         |
| 422  | `no_writable_fields`    | الجسم لا يحتوي أي حقل تصميم، أو تُجووزت كل حقوله بسبب الخطة.                    |
| 422  | `invalid_value`         | حقلٌ قيمته كائن أو قائمة، أو رُفضت قيمة، مثل `navbar_style` خارج قائمته.        |
| 422  | `invalid_url`           | حقل رابط يستعمل بروتوكولًا غير `https` و`http` و`mailto` و`tel`.                |
| 422  | `invalid_pixel_id`      | `facebook_pixel_id` ليس من 15 إلى 17 رقمًا.                                     |
| 422  | `idempotency_key_reuse` | استُعمل نفس `Idempotency-Key` مع جسم آخر.                                       |

الاستجابة `422` لا تكتب شيئًا.