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

GET /v1/store

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

المصادقة: أي مفتاح منصة نشِط مرتبط بالمتجر. ملاحظة: في v1 صلاحية store:read غير مطبَّقة على هذه النقطة — نقاط القراءة محميّة فقط بمفتاح صالح وبربط المتجر. الصلاحيات المطبَّقة فعليًا في v1 هي products:write وorders:write وlanding_pages:write وwebhooks:read وwebhooks:write وusage:read.

مُخزَّنة مؤقتًا لمدة 30 ثانية (لكل مفتاح API + سلسلة الاستعلام) — قد يستغرق ظهور تعديل من لوحة التحكم حتى 30 ثانية عبر api.dzbuild.app. تحقّق من ترويسة الاستجابة X-Cache: HIT|MISS. أما العنوان البديل dzbuild.com/api/v1/store فلا يُخزَّن مؤقتًا.

الطلب

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

الاستجابة 200

{
  "data": {
    "id":         13,
    "name":       "DZBuild",
    "slug":       "dzbuild",
    "language":   "ar",
    "description": "DZBuild Offers Preview",
    "logo":       "/uploads/logos/13/8e19a05f0e4205bbcd861469ec0f9257.webp",
    "favicon":    null,
    "banner":     null,
    "theme": {
      "primary_color":    "#f59e0b",
      "secondary_color":  "#fbbf24",
      "background_color": "#ffffff",
      "font_family":      "Cairo"
    },
    "subdomain":            "dzbuild.minacef.app",
    "custom_domain":        null,
    "custom_domain_verified": false,
    "public_url":            "https://dzbuild.minacef.app",
    "hide_branding":         false,
    "created_at":            "2026-01-13 14:58:23"
  },
  "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`).
`subdomain`	string\|null	النطاق الفرعي الصادر عن DZBuild. حاضر عادةً؛ ويكون `null` إذا لم يُضبط للمتجر نطاق فرعي بعد.
`custom_domain`	string\|null	نطاق التاجر الخاص. يُعيَّن فقط إن أُضيف من لوحة التحكم.
`custom_domain_verified`	bool	true فقط عند اكتمال DNS و SSL.
`public_url`	string\|null	حيث يصل العملاء فعلًا. يفضّل `custom_domain` المُتحقَّق منه؛ ثم يعود إلى النطاق الفرعي؛ ويكون `null` إن لم يوجد أيٌّ منهما.
`hide_branding`	bool	إخفاء "Powered by DZBuild" في الواجهة. لخطة غير محدود.
`created_at`	timestamp	وقت إنشاء المتجر بتوقيت الجزائر (UTC+01:00).

الأخطاء

HTTP	الكود	السبب
401	`unauthorized`	مفتاح خاطئ أو مفقود
402	`quota_exceeded`	استُنفدت حصة الطلبات الشهرية للمتجر — راجع حدود المعدل
403	`forbidden`	وضع البايلوت: المفتاح غير مُسجَّل ("API is in pilot mode; key not enrolled")
404	`not_found`	حُذف المتجر أثناء استخدامك للمفتاح (نادر جدًا)
429	`rate_limited`	تجاوز الحد الدقيقي لهذا المفتاح؛ احترم `Retry-After` — راجع حدود المعدل

PATCH /v1/store (قادم في v1.1)

تحديث حقول ملف المتجر (الاسم، slug، ألوان الثيم، النطاق المخصص).

هذه النقطة محجوزة — السطح مقفل لكن التنفيذ ضمن إصدار v1.1. حتى ذلك الحين، التعديلات تتم من لوحة التحكم.

المفاتيح تحمل بالفعل صلاحية store:write، لكن لا توجد بعد أي نقطة كتابة تستهلكها. PATCH /v1/store تُرجع اليوم 405 method_not_allowed وليس 404 — وعبر api.dzbuild.app ستحصل أولًا على 400 bad_request إن أغفلت ترويسة Idempotency-Key.

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