✨ 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.

✨ يُرجع 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 خاص بنداء الدفعة من الصندوق.

✨ حقول شريط الشراء. يقبل PATCH /v1/store/design الحقول buybar_show_mobile وbuybar_show_qty وfc_show_qty وproduct_button_size (normal أو large) في كل الخطط: تُظهر شريط الشراء على الهاتف والكمية في الشريط وفي نموذج الطلب السريع أو تُخفيها، وتضبط حجم أزرار الشراء. انظر المتجر.

✨ يُرجع GET /v1/store الحقول store_theme وfast_checkout_theme وvariant_card_style، أي المفاتيح الثلاثة المستعملة، للقراءة فقط.

✨ يعرض GET /v1/themes قوالب الطلب السريع وأنماط المتغيرات في fast_checkout وvariant_styles، ولكل عنصر خطته وهل يستطيع المتجر استعماله وأيّها المستعمل. انظر القوالب.

✨ كتابات التصميم والقوالب تُرجع 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.

⚠️ حذف منتج تستعمله صفحة هبوط صار مرفوضاً بـ 409 product_in_use_by_landing_page. يذكر الخطأ الصفحات في landing_pages[] مع id وtitle وslug. احذف صفحة الهبوط أولاً، أو اربطها بمنتج آخر عبر PATCH /v1/landing-pages/{id}، ثم احذف المنتج. انظر المنتجات.

✨ أقسام الصفحة الرئيسية. تقرأ 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، فالمفاتيح الحالية تعمل معها. انظر أقسام الصفحة الرئيسية.

✨ كل كتابة على تخطيط الصفحة الرئيسية يمكن التراجع عنها، بما فيها إضافة قسم. تحمل الاستجابة change_id لـ POST /v1/changes/{id}/undo، التي تُرجع 409 layout_changed إذا تغيّرت الصفحة من جديد منذ ذلك.

⚠️ لكتابات تخطيط الصفحة الرئيسية ميزانيتها الخاصة: 30 في الدقيقة و5 في الوقت نفسه لكل متجر. انظر حدود المعدل.

✨ تطبيقات الأطراف الأخرى. يُثبَّت التطبيق على المتجر عبر OAuth ويستدعي الواجهة البرمجية برمز تثبيت، مع أي خطة. قد تتلقى نداءات التطبيق أربعة رموز 403 جديدة، هي app_uninstalled وapp_suspended وapp_not_approved وapp_plan_required، ولكل تثبيت حدّ خاص قدره 120 طلباً في الدقيقة يُفحص قبل حدّ المتجر. انظر الأخطاء.

⚠️ تاريخ 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 المسجّلة قبل ذلك تحتاج تسجيلاً جديداً. انظر التحقق من التواقيع.

✨ PUT يقبل Idempotency-Key اختيارياً، ومعه تنطبق قواعد إعادة التشغيل نفسها.

⚠️ إعادة التشغيل idempotent تعمل على المضيفين معاً، وإعادة استعمال مفتاح بجسم مختلف تُرجع 422 idempotency_key_reuse. انظر التكرار الآمن.

⚠️ لا يوجد طلب تمهيدي CORS: طلب OPTIONS يتلقى 401 المعتاد، والواجهة البرمجية مخصّصة للنداءات من خادم إلى خادم فقط.

⚠️ حالات الرفض تعبر الحافة كما هي: رد 403 الخاص بالتطبيقات، أو 429، من api.dzbuild.app يصل بحالته ومحتواه الحقيقيين بدل 401.

✨ رسائل واتساب عبر الواجهة البرمجية. GET /v1/whatsapp/templates يسرد قوالب رسائل الطلبات التي اعتمدتها المنصة مع حالة اعتمادها، وGET /v1/whatsapp/balance يقرأ رصيد واتساب الخاص بالمتجر، وGET /v1/whatsapp/messages يسرد الرسائل المرسلة للزبائن، وPOST /v1/orders/{id}/whatsapp يرسل قالباً واحداً لزبون طلب معيّن ويخصمه من الرصيد. يجب أن تكون إضافة مرسل واتساب مفعّلة. النطاقان الجديدان هما whatsapp:read وwhatsapp:send. انظر رسائل واتساب.

⚠️ النطاقات تُجمَّد لحظة إنشاء المفتاح، فالمفتاح الذي أُنشئ قبل هذا الإصدار لا يملك النطاقين الجديدين: أنشئ مفتاحاً جديداً لاستعمالهما.

⚠️ إعادة المحاولة بعد 402 no_credit أو 422 تحتاج Idempotency-Key جديداً. أول استجابة تُحفظ 24 ساعة وتُعاد للمفتاح نفسه والجسم نفسه، فشحن الرصيد أو تصحيح الطلب لا يغيّر شيئاً مع المفتاح القديم.

✨ كل رسالة في GET /v1/whatsapp/messages تحمل الحقل billing: charged عندما يفوتر WhatsApp الرسالة، وfree عندما يعود رصيدها إلى المحفظة، وnull ما دامت النتيجة غير معروفة بعد.

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

✨ صار بالإمكان كتابة الطلبات. 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 ينقل المؤشّر. المؤشّر ليس صلاحية: المتجر الذي لم يوافق عليه التاجر لا مفتاح له ولا يمكن اختياره.

✨ إدارة ذاتية للمفاتيح — أصبح بإمكان مالكي المتاجر على خطة Enterprise إنشاء مفاتيح API وإلغاؤها من لوحة التحكم عبر الإعدادات ← واجهة API (/dashboard/api). تُعرض الأسرار مرة واحدة عند الإنشاء.

⚠️ حد المعدل في الدقيقة يُطبَّق الآن لكل متجر، مشتركًا بين جميع مفاتيح المتجر (كان سابقًا لكل مفتاح). سقف Enterprise دون تغيير عند 600 طلب/دقيقة.

⚠️ يمكن للمتجر الآن الاحتفاظ بـ 3 مفاتيح نشطة كحد أقصى (بدلًا من 20)، عبر جميع طرق الإنشاء — لوحة التحكم وPOST /v1/keys والمفاتيح الصادرة من الدعم. إلغاء مفتاح يحرّر مكانه.

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

⚠️ أُلغيت خطط حدود المعدل القديمة Free / Pro / Unlimited. ويبقى سقف Enterprise عند 600 طلب/دقيقة لكل مفتاح دون سقف شهري؛ والتجاوزات الخاصة بالمتجر من الدعم تبقى سارية.

✨ صور المنتجات عبر الواجهة البرمجية — 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 كاملة بدل أسماء الملفات المجرّدة. إذا كان كودك يضيف البادئة يدويًا فاحذف ذلك المنطق.

✨ POST /v1/orders — إنشاء الطلبات عبر الواجهة البرمجية. مصمَّم للثيمات المخصصة والمتاجر بدون رأس وتطبيقات الجوال وأتمتة الموزّعين. تسعير سطور الطلب معتمد على الخادم؛ دعم كامل للمتغيرات؛ idempotent.

📚 دليل جديد: الثيمات والواجهات المخصصة — بناء كامل من العرض إلى السلة إلى الـ checkout والـ webhooks.

📚 دليل جديد: للموزّعين — إدارة متاجر متعددة للعملاء، عمليات بالجملة، علامة بيضاء، نماذج فوترة.

📚 دليل جديد: إعداد البيئة و .env — تخزين آمن لبيانات الاعتماد عبر Node, Python, PHP, Go, Vercel, Cloudflare, AWS, Docker/K8s, GitHub Actions.

📚 توسيع مرجع Orders — توثيق كامل للمتغيرات بما في ذلك المخزون لكل متغيّر، المخزون لكل تركيبة، المتغيرات المتدرجة، متغيرات الصورة-نص، عروض القطع المتعددة.

🎉 إطلاق نسخة تجريبية أولى.

مصادقة وحد معدل وذاكرة قراءة مؤقتة، لكل مفتاح.

نقاط نهاية قراءة للمتجر / المنتجات / الطلبات / العملاء / صفحات الهبوط.

نقاط نهاية كتابة مع idempotency للمنتجات / الطلبات / صفحات الهبوط.

استيعاب غير متزامن لـ/v1/signups و /v1/events (202 Accepted).

Webhooks صادرة مع إعادة محاولة تلقائية.