# سجل التغييرات

الواجهة البرمجية في مرحلة تجريبية. يجب أن تتبع مفاتيح API الشخصية متجراً ذا خطة Enterprise سارية، وإلا فكل نداء يُرجع `403`؛ أما رموز التطبيقات المثبّتة فتعمل مع كل الخطط. و`https://api.dzbuild.app` هو المضيف الوحيد المدعوم.

## v1.12 - 2026-10-28 (تجريبي)[​](#v112---2026-10-28-تجريبي "رابط مباشر إلى v1.12 - 2026-10-28 (تجريبي)")

* ✨ **عائلات المتغيرات في DZBuild POS.** برمز الصندوق، تُرجع `GET /v1/products` و`GET /v1/products/{id}` الحقل `variants`: المجموعات ونمط المخزون وعنصراً لكل متغير مع `key` و`sku` و`barcode` والسعر والمخزون و`external_id` الخاص بالصندوق. وتأخذ `POST /v1/products/batch` كتلة `variants` وتُرجع `variants` مع `price_online` لكل متغير. ويمكن لعنصر الدفعة أن يذكر في `id` منتج المتجر الذي يرتبط به، فلا يُنشأ من جديد منتج استورده الصندوق. انظر [DZBuild POS](https://dzbuild.com/ar/ar/api-docs/pos.md).
* ✨ **مخزون كل متغير من الصندوق.** تأخذ `POST /v1/inventory/adjustments/batch` القيمة `target: "variant"` مع `variant_external_id`، مع أربعة أخطاء عنصر جديدة: `unknown_variant` و`variant_gone` و`variant_stock_mode` و`variant_mismatch`.
* ✨ **تحمل أحداث `inventory.level_changed` وسطور طلبات الصندوق `variant_key` و`variant_external_id`**، وقيمتهما `null` على مستوى المنتج.
* ⚠️ **لا تغيير للصندوق الذي لا يرسل كتلة `variants`**: تبقى متغيرات المنتج على المتجر كما هي، وما زال `target: "product"` على منتج له مخزون لكل متغير يُرجع `variant_product`.

## v1.10 - 2026-10-09 (تجريبي)[​](#v110---2026-10-09-تجريبي "رابط مباشر إلى v1.10 - 2026-10-09 (تجريبي)")

* ✨ **DZBuild POS.** يرتبط برنامج الصندوق المجاني على ويندوز بالمتجر عبر OAuth، مع الاكتشاف في `https://dzbuild.com/.well-known/oauth-authorization-server`، ويستدعي نقاطه الخاصة برمز الصندوق: `GET /v1/me` و`POST /v1/devices` ونبضات الاتصال و`GET /v1/locations` و`POST /v1/locations` و`POST /v1/products/batch` و`POST /v1/media/uploads` و`POST /v1/inventory/adjustments/batch` و`POST /v1/pos/sales` و`POST /v1/pos/sales/{sale_id}/refunds` و`POST /v1/pos/closures` و`POST /v1/orders/{id}/claim` و`GET /v1/events`. مسارات النسخ الاحتياطية الأربعة تُرجع `501 not_implemented`. مفاتيح API الشخصية ورموز التطبيقات تتلقى `403` على المسارات الخاصة بالصندوق. انظر [DZBuild POS](https://dzbuild.com/ar/ar/api-docs/pos.md).
* ✨ **يُرجع `GET /v1/store` الحقول `currency` (`DZD`) و`stock_deduction` (`on_create` أو `on_confirm`) و`plan` و`plan_limits`.** الخطة المدفوعة المنتهية تُقرأ `free`، و`plan_limits.active_products` يكون `null` عندما لا يكون للخطة حدّ.
* ⚠️ **لا تغيير في `POST /v1/products` عند حدّ الخطة**: ما زالت تُرجع `400 bad_request` بنفس الرسالة. الرمز الجديد `402 product_limit_reached` خاص بنداء الدفعة من الصندوق.

## v1.9 - 2026-10-08 (تجريبي)[​](#v19---2026-10-08-تجريبي "رابط مباشر إلى v1.9 - 2026-10-08 (تجريبي)")

* ✨ **حقول شريط الشراء.** يقبل `PATCH /v1/store/design` الحقول `buybar_show_mobile` و`buybar_show_qty` و`fc_show_qty` و`product_button_size` (`normal` أو `large`) في كل الخطط: تُظهر شريط الشراء على الهاتف والكمية في الشريط وفي نموذج الطلب السريع أو تُخفيها، وتضبط حجم أزرار الشراء. انظر [المتجر](https://dzbuild.com/ar/ar/api-docs/resources/store.md).
* ✨ **يُرجع `GET /v1/store` الحقول `store_theme` و`fast_checkout_theme` و`variant_card_style`**، أي المفاتيح الثلاثة المستعملة، للقراءة فقط.
* ✨ **يعرض `GET /v1/themes` قوالب الطلب السريع وأنماط المتغيرات** في `fast_checkout` و`variant_styles`، ولكل عنصر خطته وهل يستطيع المتجر استعماله وأيّها المستعمل. انظر [القوالب](https://dzbuild.com/ar/ar/api-docs/resources/themes.md).
* ✨ **كتابات التصميم والقوالب تُرجع `change_id`.** تحمل `PATCH /v1/store/design` و`POST /v1/store/theme` و`POST /v1/store/fast-checkout-theme` و`POST /v1/store/variant-style` الرقم الذي ترسله إلى `POST /v1/changes/{id}/undo`.

## v1.8.1 - 2026-10-02 (تجريبي)[​](#v181---2026-10-02-تجريبي "رابط مباشر إلى v1.8.1 - 2026-10-02 (تجريبي)")

* ⚠️ **حذف منتج تستعمله صفحة هبوط صار مرفوضاً** بـ `409 product_in_use_by_landing_page`. يذكر الخطأ الصفحات في `landing_pages[]` مع `id` و`title` و`slug`. احذف صفحة الهبوط أولاً، أو اربطها بمنتج آخر عبر `PATCH /v1/landing-pages/{id}`، ثم احذف المنتج. انظر [المنتجات](https://dzbuild.com/ar/ar/api-docs/resources/products.md).

## v1.8 - 2026-09-28 (تجريبي)[​](#v18---2026-09-28-تجريبي "رابط مباشر إلى v1.8 - 2026-09-28 (تجريبي)")

* ✨ **أقسام الصفحة الرئيسية.** تقرأ `GET /v1/store/home-layout` أقسام الصفحة الرئيسية للمتجر وأنواع الأقسام التي يقبلها قالبه. تضيف `POST /v1/store/home-layout/sections` قسماً، وتغيّر `PATCH` و`DELETE /v1/store/home-layout/sections/{id}` قسماً أو تحذفه، وتحدّد `POST /v1/store/home-layout/reorder` الترتيب، وتستبدل `PUT /v1/store/home-layout` القائمة كلها. يمكن إضافة عشرة أنواع من الأقسام في كل قالب، منها `category-products` و`banner` و`faq` و`video`. إعدادات الصور تأخذ صورة رُفعت من لوحة التحكم: لا يمكن رفعها عبر الواجهة البرمجية بعد. تستعمل هذه النقاط `store:read` و`store:write`، فالمفاتيح الحالية تعمل معها. انظر [أقسام الصفحة الرئيسية](https://dzbuild.com/ar/ar/api-docs/resources/home-layout.md).
* ✨ **كل كتابة على تخطيط الصفحة الرئيسية يمكن التراجع عنها، بما فيها إضافة قسم.** تحمل الاستجابة `change_id` لـ `POST /v1/changes/{id}/undo`، التي تُرجع `409 layout_changed` إذا تغيّرت الصفحة من جديد منذ ذلك.
* ⚠️ **لكتابات تخطيط الصفحة الرئيسية ميزانيتها الخاصة**: 30 في الدقيقة و5 في الوقت نفسه لكل متجر. انظر [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).

## v1.7 - 2026-09-26 (تجريبي)[​](#v17---2026-09-26-تجريبي "رابط مباشر إلى v1.7 - 2026-09-26 (تجريبي)")

* ✨ **تطبيقات الأطراف الأخرى.** يُثبَّت التطبيق على المتجر عبر OAuth ويستدعي الواجهة البرمجية برمز تثبيت، مع أي خطة. قد تتلقى نداءات التطبيق أربعة رموز `403` جديدة، هي `app_uninstalled` و`app_suspended` و`app_not_approved` و`app_plan_required`، ولكل تثبيت حدّ خاص قدره 120 طلباً في الدقيقة يُفحص قبل حدّ المتجر. انظر [الأخطاء](https://dzbuild.com/ar/ar/api-docs/errors.md).
* ⚠️ **تاريخ `expires_at` للمفتاح صار مُطبَّقاً**: بعد انقضائه يُرجع المفتاح `401`.
* ⚠️ **مفاتيح Copilot والموصلات لا تدير المفاتيح**: تتلقى `403` على `/v1/keys`.
* ✨ **المفاتيح الجديدة تحمل `analytics:read`**؛ أما المفاتيح الأقدم فتبقى على النطاقات التي أُنشئت بها.
* ⚠️ **webhooks الخاصة بـ API v1 صارت موقَّعة بسر كل webhook** (`X-DZ-Signature: t=<ts>,v1=<hmac>`)، والتسجيل يقبل `https://` فقط، و`408` و`429` يُعادان، وأي 4xx أو 3xx آخر ينتقل فوراً إلى قائمة الرسائل الميتة. الـ webhooks المسجّلة قبل ذلك تحتاج تسجيلاً جديداً. انظر [التحقق من التواقيع](https://dzbuild.com/ar/ar/api-docs/webhooks/verifying-signatures.md).
* ✨ **`PUT` يقبل `Idempotency-Key` اختيارياً**، ومعه تنطبق قواعد إعادة التشغيل نفسها.
* ⚠️ **إعادة التشغيل idempotent تعمل على المضيفين معاً**، وإعادة استعمال مفتاح بجسم مختلف تُرجع `422 idempotency_key_reuse`. انظر [التكرار الآمن](https://dzbuild.com/ar/ar/api-docs/idempotency.md).
* ⚠️ **لا يوجد طلب تمهيدي CORS**: طلب `OPTIONS` يتلقى `401` المعتاد، والواجهة البرمجية مخصّصة للنداءات من خادم إلى خادم فقط.
* ⚠️ **حالات الرفض تعبر الحافة كما هي**: رد `403` الخاص بالتطبيقات، أو `429`، من `api.dzbuild.app` يصل بحالته ومحتواه الحقيقيين بدل `401`.

## v1.6 - 2026-09-26 (تجريبي)[​](#v16---2026-09-26-تجريبي "رابط مباشر إلى v1.6 - 2026-09-26 (تجريبي)")

* ✨ **رسائل واتساب عبر الواجهة البرمجية.** `GET /v1/whatsapp/templates` يسرد قوالب رسائل الطلبات التي اعتمدتها المنصة مع حالة اعتمادها، و`GET /v1/whatsapp/balance` يقرأ رصيد واتساب الخاص بالمتجر، و`GET /v1/whatsapp/messages` يسرد الرسائل المرسلة للزبائن، و`POST /v1/orders/{id}/whatsapp` يرسل قالباً واحداً لزبون طلب معيّن ويخصمه من الرصيد. يجب أن تكون إضافة مرسل واتساب مفعّلة. النطاقان الجديدان هما `whatsapp:read` و`whatsapp:send`. انظر [رسائل واتساب](https://dzbuild.com/ar/ar/api-docs/resources/whatsapp.md).
* ⚠️ **النطاقات تُجمَّد لحظة إنشاء المفتاح**، فالمفتاح الذي أُنشئ قبل هذا الإصدار لا يملك النطاقين الجديدين: أنشئ مفتاحاً جديداً لاستعمالهما.
* ⚠️ **إعادة المحاولة بعد `402 no_credit` أو `422` تحتاج `Idempotency-Key` جديداً.** أول استجابة تُحفظ 24 ساعة وتُعاد للمفتاح نفسه والجسم نفسه، فشحن الرصيد أو تصحيح الطلب لا يغيّر شيئاً مع المفتاح القديم.
* ✨ **كل رسالة في `GET /v1/whatsapp/messages` تحمل الحقل `billing`**: `charged` عندما يفوتر WhatsApp الرسالة، و`free` عندما يعود رصيدها إلى المحفظة، و`null` ما دامت النتيجة غير معروفة بعد.

## v1.5 - 2026-09-23 (تجريبي)[​](#v15---2026-09-23-تجريبي "رابط مباشر إلى v1.5 - 2026-09-23 (تجريبي)")

* ⚠️ صارت إعادة محاولة تسليم الـ webhooks تتباعد (دقيقة، 5 دقائق، 30 دقيقة، ساعتان) وتتوقف بعد 5 محاولات فاشلة؛ وصار انتهاء المهلة وفشل DNS/TLS يُعاد بدل أن يُهجر.

## v1.4 — 2026-09-05 (تجريبي)[​](#v14--2026-09-05-تجريبي "رابط مباشر إلى v1.4 — 2026-09-05 (تجريبي)")

* ✨ **صار بالإمكان كتابة الطلبات.** `POST /v1/orders` ينشئ طلباً، و`PATCH /v1/orders/{id}` ينقل حالته، و`POST /v1/orders/{id}/cancel` يلغيه، و`POST /v1/orders/{id}/send-to-delivery` يسلّم طرداً واحداً لشركة التوصيل الخاصة بالمتجر. النطاقان الجديدان هما `orders:write` و`delivery:send`.
* ⚠️ **النطاقات تُجمَّد لحظة إنشاء المفتاح**، فالمفتاح القائم لا يكتسب النطاقين الجديدين: أنشئ مفتاحاً جديداً أو أعد ربط الموصل لاستعمالهما. والمفتاح المُنشأ من لوحة التحكم يحصل على `orders:write`. أما المفاتيح المُنشأة من لوحة التحكم أو عبر `POST /v1/keys` فلا تحصل أبداً على `delivery:send`، فلا تستطيع استدعاء `send-to-delivery`.
* ⚠️ **التسليم لشركة التوصيل يحتاج دائماً تأكيداً صادراً من الخادم.** النداء الأول يُرجع `409 confirmation_required` مع رمز يُستعمل مرة واحدة وملخّص يذكر الزبون والهاتف والوجهة والمبلغ وشركة التوصيل؛ وهذا الرمز وحده يُرسل الطرد. القيمة `confirm: true` في جسم الطلب غير مقبولة في هذه النقطة من أي مستدعٍ. والطلب المُرسَل سابقاً يُرفض بـ `409 already_sent`.
* ⚠️ **حساب مال الطلب صار من الخادم.** قيمتا `shipping_cost` و`payment_fee` القادمتان من المستدعي تُتجاهلان: سعر التوصيل يأتي من جدول أسعار المتجر نفسه حسب الولاية ونوع التوصيل، و`discount` مسقوف بمجموع الطلب زائد التوصيل. أسعار المنتجات كانت تعمل هكذا أصلاً.
* ✨ **`GET /v1/shipping/coverage`** يجيب هل تخدم شركة التوصيل المرتبطة بلديةً معيّنة، وهل لها مكتب في ولاية معيّنة، مع تاريخ تحديث بيانات الشركة نفسها.
* ✨ **`GET /v1/shipping/providers`** صار يذكر أيضاً شركة توصيل مضبوطة مباشرة على المتجر لا مضافة من قائمة المزوّدين، إضافة إلى `is_send_default` و`economic_available` و`synced_tier` و`stock_account` و`auto_validate` و`custom_name`. لا تُرجَع بيانات الاعتماد ولا العناوين أبداً.
* ✨ **`GET /v1/landing-pages/{id}/check`** يذكر ما سيصطدم به الزبون في الصفحة: استمارة طلب بلا منتج، أو غياب استمارة الطلب، أو أكثر من واحدة، أو قسم يشير إلى منتج من متجر آخر.
* ⚠️ **نشر صفحة هبوط معطوبة مرفوض.** نداء `PATCH /v1/landing-pages/{id}` بـ `status: active` يفشل بـ `landing_page_has_no_product` عندما تكون الصفحة ستأخذ الطلبات بصفر. وتعديل صفحة منشورة أصلاً ما زال يعمل حتى يمكن إصلاحها. وكتابة قسم يذكر `product_id` من متجر آخر تُرفض كخطأ تحقق.
* ⚠️ **`PATCH /v1/landing-page-sections/{id}` مع `replace: true`** صار يعيد وضع الإعدادات الافتراضية لنوع القسم تحت ما ترسله، فالمفتاح المحذوف يعود إلى قيمته الافتراضية بدل أن يختفي من الصفحة.
* ✨ **`GET /v1/connection`** يسرد المتاجر التي يغطيها ربط واحد وأيّها نشط، و`POST /v1/connection/active-store` ينقل المؤشّر. المؤشّر ليس صلاحية: المتجر الذي لم يوافق عليه التاجر لا مفتاح له ولا يمكن اختياره.

## v1.3 — 2026-08-13 (تجريبي)[​](#v13--2026-08-13-تجريبي "رابط مباشر إلى v1.3 — 2026-08-13 (تجريبي)")

* ✨ **إدارة ذاتية للمفاتيح** — أصبح بإمكان مالكي المتاجر على خطة Enterprise إنشاء مفاتيح API وإلغاؤها من لوحة التحكم عبر **الإعدادات ← واجهة API** (`/dashboard/api`). تُعرض الأسرار مرة واحدة عند الإنشاء.
* ⚠️ حد المعدل في الدقيقة يُطبَّق الآن **لكل متجر**، مشتركًا بين جميع مفاتيح المتجر (كان سابقًا لكل مفتاح). سقف Enterprise دون تغيير عند **600 طلب/دقيقة**.
* ⚠️ يمكن للمتجر الآن الاحتفاظ بـ **3 مفاتيح نشطة** كحد أقصى (بدلًا من 20)، عبر جميع طرق الإنشاء — لوحة التحكم و`POST /v1/keys` والمفاتيح الصادرة من الدعم. إلغاء مفتاح يحرّر مكانه.

## v1.2 — 2026-08-13 (تجريبي)[​](#v12--2026-08-13-تجريبي "رابط مباشر إلى v1.2 — 2026-08-13 (تجريبي)")

* ⚠️ **صارت الواجهة البرمجية حصرية لخطة Enterprise.** لا تُوثَّق المفاتيح إلا ما دام متجرها على **خطة Enterprise سارية**؛ وكل خطة أخرى — وكذلك اشتراك Enterprise منتهي الصلاحية — تتلقى `403 forbidden` (برسالة `API access requires an active Enterprise plan`). ولا تُصدَر المفاتيح الجديدة إلا لمتاجر Enterprise. أما المفاتيح الموجودة لدى متاجر غير Enterprise فتتوقف عن العمل فورًا دون أن تُحذف: تعود إلى العمل لحظة انتقال المتجر إلى Enterprise (أو تجديده)، دون أي إعادة إصدار.
* ⚠️ أُلغيت خطط حدود المعدل القديمة Free / Pro / Unlimited. ويبقى سقف Enterprise عند **600 طلب/دقيقة** لكل مفتاح دون سقف شهري؛ والتجاوزات الخاصة بالمتجر من الدعم تبقى سارية.

## v1.1 — 2026-08-12 (تجريبي)[​](#v11--2026-08-12-تجريبي "رابط مباشر إلى v1.1 — 2026-08-12 (تجريبي)")

* ✨ **صور المنتجات عبر الواجهة البرمجية** — `POST /v1/products/{id}/images` يضيف صورة من رابط `https` عمومي (تتكفّل DZBuild بتنزيلها وتحسينها واستضافتها)، و`PATCH .../images/{image_id}` يضبط النص البديل وترتيب العرض والصورة الرئيسية، و`DELETE .../images/{image_id}` يحذف صورة. الروابط المكرّرة لا تُضاف مرتين، وأول صورة تصبح الرئيسية تلقائيًا، والحد الأقصى 20 صورة لكل منتج.
* ✨ **`PUT /v1/products/{id}/variants`** — إنشاء وإدارة مجموعات الأنواع وخياراتها ومخزون التركيبات في نداء واحد (استبدال كامل). أصبحت الحقول `price_adjustment` و`stock` و`sku` و`image_id` و`show_as_card` لكل خيار قابلة للكتابة، وتُضبط أعلام وضع المخزون نيابةً عنك.
* ✨ `GET /v1/products/{id}` يُرجع الآن كتلة **`combinations`** إضافةً إلى حقول الخيارات الكاملة (`price_adjustment`، `sku`، `show_as_card`، `sort_order`، `is_active`) والنص البديل `alt_text` للصور.
* ⚠️ **تغيير مؤثّر:** أصبح `primary_image` و`images[].url` يُرجعان **روابط CDN كاملة** بدل أسماء الملفات المجرّدة. إذا كان كودك يضيف البادئة يدويًا فاحذف ذلك المنطق.

## v1.0.1 — 2026-05-02 (تجريبي)[​](#v101--2026-05-02-تجريبي "رابط مباشر إلى v1.0.1 — 2026-05-02 (تجريبي)")

* ✨ **`POST /v1/orders`** — إنشاء الطلبات عبر الواجهة البرمجية. مصمَّم للثيمات المخصصة والمتاجر بدون رأس وتطبيقات الجوال وأتمتة الموزّعين. تسعير سطور الطلب معتمد على الخادم؛ دعم كامل للمتغيرات؛ idempotent.
* 📚 دليل جديد: **الثيمات والواجهات المخصصة** — بناء كامل من العرض إلى السلة إلى الـ checkout والـ webhooks.
* 📚 دليل جديد: **للموزّعين** — إدارة متاجر متعددة للعملاء، عمليات بالجملة، علامة بيضاء، نماذج فوترة.
* 📚 دليل جديد: **إعداد البيئة و .env** — تخزين آمن لبيانات الاعتماد عبر Node, Python, PHP, Go, Vercel, Cloudflare, AWS, Docker/K8s, GitHub Actions.
* 📚 توسيع مرجع `Orders` — توثيق كامل للمتغيرات بما في ذلك المخزون لكل متغيّر، المخزون لكل تركيبة، المتغيرات المتدرجة، متغيرات الصورة-نص، عروض القطع المتعددة.

## v1.0 — 2026-04-30 (تجريبي)[​](#v10--2026-04-30-تجريبي "رابط مباشر إلى v1.0 — 2026-04-30 (تجريبي)")

* 🎉 إطلاق نسخة تجريبية أولى.
* مصادقة وحد معدل وذاكرة قراءة مؤقتة، لكل مفتاح.
* نقاط نهاية قراءة للمتجر / المنتجات / الطلبات / العملاء / صفحات الهبوط.
* نقاط نهاية كتابة مع idempotency للمنتجات / الطلبات / صفحات الهبوط.
* استيعاب غير متزامن لـ`/v1/signups` و `/v1/events` (`202 Accepted`).
* Webhooks صادرة مع إعادة محاولة تلقائية.