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

GET /v1/store

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

المصادقة: مفتاح منصة بصلاحية 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

{
  "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`	استُنفدت حصة الطلبات الشهرية للمتجر — راجع حدود المعدل
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`. راجع حدود المعدل

PATCH /v1/store

تُحدّث هذه النقطة ملف إعدادات المتجر، بنفس حقول صفحة إعدادات المتجر في لوحة التحكم ما عدا رقم 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.

الطلب

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

{
  "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 المُرسَل مباشرة بعد الكتابة يُرجع القيم الجديدة.

الأخطاء

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

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

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

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

الطلب

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

الاستجابة 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" }
}

مرجع الحقول

الحقل	النوع	ملاحظات
`theme`	string	مفتاح القالب الذي يستعمله المتجر. انظر القوالب.
`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

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

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

الطلب

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

الاستجابة 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" }
}

الأخطاء

يُرجع 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

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

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

الجسم

أرسل أي حقل يعرضه 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 سارية، لذا لا يُقفل عليه أي حقل. وتنطبق الأقفال على رموز التطبيقات المثبّتة، التي تعمل مع كل الخطط.

الطلب

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

{
  "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 المُرسَل مباشرة بعد الكتابة يُرجع القيم الجديدة.

الأخطاء

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 لا تكتب شيئًا.

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