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

كل تغيير إضافي في واجهة المنصّة يظهر هنا بالمراجعة المؤرّخة التي تحملها الترويسة X-Dukkan-Api-Version، وكل تغيير في عقد الثيمات بتاريخه. الأحدث أولاً. سياسة الإصدارات في مرجع الواجهة.

2026-09-10: الطلبات التي تنشئها التطبيقات#

المراجعة المؤرّخة الثالثة من v1 (X-Dukkan-Api-Version: 2026-09-10). كلها إضافية:

• نطاقان جديدان. orders:create ينشئ طلبات بأسعار يحددها التطبيق؛ وهو منفصل عن orders:write ولا يتضمّن قراءة الطلبات. clients:write ينشئ سجلات العملاء ويحدّثها، ومقيّد باتفاقية معالجة البيانات تماماً مثل clients:read؛ وتصل نقاط نهاية العملاء في مراجعة لاحقة. صار orders:write يُقرأ في شاشة الموافقة «تحديث حالة الطلب وملاحظته ووسومه». مرجع النطاقات.
• POST /orders ينشئ طلباً بأسعار الوحدة المتفق عليها، لخيارات الكتالوج والبنود المخصصة (OrderItem.kind إما variant أو custom)، ويعيد احتساب المجاميع، ويخصم المخزون وفق سياسة المخزون أو يتجاوزه، ويربط العميل، وينبّه التاجر، ويطلق order.created بقيمة source: "app". رموز خاصة: 422 currency_not_allowed وinvalid_request مع details.fields، و404 variant_not_found، و409 variant_unavailable وpayment_method_disabled وinsufficient_stock مع details.lines. الطلبات التي تنشئها التطبيقات.
• PATCH /orders/{id} يحدّث الملاحظة، ويضيف الوسوم أو يزيلها كعمليات مجموعات، ويدمج خصائص التطبيق المستدعي وحده؛ وتظهر الخاصية reference شريحةً في صفحة الطلب عند التاجر. Order.tags وOrderDetail.note وOrderDetail.attributes حقول جديدة، ويصفّي GET /orders?tag= حسب الوسم.
• GET /store يعيد هوية المتجر العلنية ومعطيات الدفع من دون نطاق: عملة التسعير وعملات المتجر، وجدول الصرف الذي تطبّقه صفحة الدفع بالشكل scaled / 10^scale، وطرق الدفع المفعّلة، وقائمة المحافظات.
• GET /products يكسب q (بحث مرتّب بالتطابق الجزئي في الاسم واسم الخيار وSKU وDSIN والباركود) وstatus وids؛ ويعيد GET /products/variants?ids= التحقق من حتى 100 خيار دفعةً واحدة مع اسم منتجها وحالته.
• تحمل حمولة order.created الحقل source.
• تضيف @dukkan.one/app-sdk 0.3.0 الدوال orders.create وorders.update وproducts.search وproducts.variants وstore.get، والخطأين المنمّطين DukkanValidationError وDukkanConflictError مع insufficientLines، ومساعدَي الصرف exchangeRateFor وbuildCreateOrderLines. وتصدّر @dukkan.one/nuxt 0.3.0 الدالتين enforceLimit وclientIp من @dukkan.one/nuxt/runtime. الحزمة في أي تطبيق Node، وحدة Nuxt.

2026-09-09 — حزمة التطبيقات ووحدة Nuxt والأداة#

عدّة المطوّر الرسمية، منشورة تحت وسم التوزيع next حتى 1.0.0:

• @dukkan.one/app-sdk: عميل منمّط لواجهة المنصّة مولَّد من مستند OpenAPI، وOAuth مع PKCE ورموز دوّارة خلف TokenStore يسلسل التجديدات، ومستقبِل Webhooks يتحقق على البايتات الخام ويزيل التكرار على معرّف الحدث الموقّع، ومساعدات تجارة للمبالغ بالوحدات الصغرى وانتقالات الطلبات، ومخطط dukkan.app.toml. يعمل على Node وWorkers وBun وDeno. البداية السريعة، المرجع.
• @dukkan.one/nuxt: تركّب مسارات التثبيت وإعادة التوجيه وWebhooks من dukkan.app.toml وتطلب عقداً واحداً، defineDukkanApp. وحدة Nuxt.
• @dukkan.one/cli: يحمل الأمر dukkan الآن app init وapp config push وpull وapp dev بنفق عام وجلسة تطوير وapp webhook trigger وapp logs، إلى جانب أوامر الثيمات دون تغيير. تحوّل @dukkan.one/theme-cli إليه مع تنبيه إهمال. مرجع الأداة.
• يُنشر العقد للغات الأخرى، مع متجهات الاختبار ومخطط الإعداد، على /contracts/v1/. العقد للغات الأخرى.

2026-09-09 — عقد حزمة التطبيقات#

المراجعة المؤرّخة الثانية من v1 (X-Dukkan-Api-Version: 2026-09-09). كلها إضافية:

• تحمل استجابات الرموز (في المنحتين) install_id وstore_id وstore_slug، وعند التحديث scope أيضاً. اجعل المعرّفات مفتاح تخزينك؛ راجع التفويض.
• يصف GET /installation التثبيت والمتجر خلف الرمز: النطاقات الفعلية، وقناة التوزيع، والأس العشري لعملة المتجر ولغته ومنطقته الزمنية، واشتراك Webhooks الحالي.
• تحمل أغلفة Webhooks install_id موقّعاً؛ وتضيف التسليمات الترويسة غير الموقّعة X-Dukkan-Install-Id للبحث عن السر. تحمل تجارب المتاجر التجريبية test: true.
• يطلق POST /webhooks/test تسليماً موقّعاً واحداً لأي موضوع مشترَك فيه على متجر تجريبي، عبر صندوق الصادر وعامل التسليم الحقيقيين.
• رمز تحديث يُقدَّم مجدداً خلال 30 ثانية من تدويره، وخلفه ما زال صالحاً، يُعدّ سباقاً: invalid_grant دون إلغاء. راجع منحة التحديث.
• تحمل استجابات 429 الترويسة Retry-After؛ وpayment_status صار تعداداً منشوراً؛ وينشر مستند OpenAPI مخطط حمولة كل موضوع تحت x-dukkan-topic-payloads.
• تعرض لوحة التحكم المسودات التي يديرها dukkan.app.toml وتنبّه عندما تختلف البوابة عن الملف. أسرار توقيع Webhooks المُنشأة من لوحة التحكم تستخدم الآن البادئة dk_whsec_ مثل الواجهة.

2026-09-02 — التوثيق#

• إعادة بناء التوثيق بالشجرة الحالية، وتصحيح عقد الهيكل في دليل الثيمات ({% layout %} + {% block %})، وإضافة fulfillment.requested إلى جدول المواضيع، ومراجع كاملة للنطاقات وLiquid والأداة.

2026-08 — عقد الثيمات#

كلها إضافية إلا ما يُذكر:

• الأقسام على أربع صفحات: enabled_on على تعريف القسم يفتحه لـ product وcategory وcart؛ غيابه يبقي الرئيسية فقط. page_sections يصل إلى القوالب الأربعة.
• غلاف الأقسام منصّي (تغيير في التأليف لا في المستندات): snippets/sections.liquid محجوز ويُحقن عند الدفع؛ الثيم يكتب snippets/section-body.liquid؛ إصدار data-dukkan-section من الثيم مرفوض. الأجسام تُصيَّر مرتين، والفارغ لا يُصدر غلافاً، وband: true يُستثنى من التناوب sec--alt.
• مفاتيح جديدة في المخطط: info وcategory وband وenabled_on على القسم؛ localized على الإعدادات النصية؛ font على خيار select.
• نوعان جديدان: datetime وrichtext (يُعرض بالمرشّح richtext).
• مستند الإعدادات: المفتاح translations محجوز لترجمات localized (تضييق مقبول ما دامت الثيمات الخارجية في المتاجر التجريبية)؛ إعدادات url تقبل مسارات مطلقة على المضيف نفسه.
• مرشّحات جديدة: file_alt وfile_focal_style وtel_href وwa_href وmoney_major وdate_localized. img_url أصبح عقد شبكة الصور بسلّم عروض ثابت.
• سياق v1: product.savings وvariant.savings، وproduct.sold_count، وproduct.image_color، وحقول صورة التصنيف الأربعة image_url وimage_color وimage_alt وimage_focal_style (بديل الحرف الأول يبقى إلزامياً).
• الأرقام المشرقية: إعداد arabic_numerals يحوّل مرشّحات المال إلى الأرقام العربية ويُختم الجذر بـ data-dukkan-numerals="arabic".
• وحدات منصّة التشغيل: كشف عند التمرير، زر شراء ثابت، العودة إلى الأعلى، الوضع الليلي [data-scheme="dark"]، نموذج «أعلمني عند التوفّر»، المعاينة السريعة، وأثر الطيران للحزم.
• الأداء: صفحات الثيمات المنشورة قابلة للتخزين المشترك؛ المعاينات والمتاجر التجريبية والسلة والبحث مستثناة.
• تحديثات الثيمات: تحديثات الثيمات الأولى تُطبَّق تلقائياً على تثبيتاتها؛ الثيمات الخارجية تتحدّث عبر المراجعة والمسودة فقط.

2026-08-29 — سوق الثيمات#

• اكتمال دورة النشر: الوسائط (غلاف + 3–8 لقطات بنص بديل عربي)، وملاحظات الإصدار بلغتين، والسحب، والسحب من السوق والاستعادة، ومتجر العرض المملوك للمنصّة، والتحديث كمسودة للتاجر، والإحصاءات. راجع انشر ثيماً.
• قرارات المنتج: معاينة قبل الشراء، ومعالجة الاسترداد عبر مالية دكان وفق شروط المطوّرين، والرد الأول خلال 5 أيام عمل.

2026-08-19 — المتاجر التجريبية واتفاقية البيانات#

• المتاجر التجريبية تولد مزروعة: 3 لكل مؤسسة، 90 يوماً قابلة للتجديد، أوامر إعادة التهيئة والتجديد والحذف. راجع المتاجر التجريبية.
• الأداة @dukkan.one/theme-cli@0.1.0 وتدفق رمز الجهاز DKN-XXXXXX.
• نسخة اتفاقية معالجة البيانات 2026-08-19.

2026-08-10 — شروط المطوّرين#

• النسخة الأولى من شروط المطوّرين.

2026-08-09 — واجهة المنصّة v1#

المراجعة المؤرّخة الأولى لـ v1 (X-Dukkan-Api-Version: 2026-08-09):

• الموارد: الطلبات، والشحنات، والاستردادات، والمنتجات، والخصومات، وحركات المخزون، واشتراك Webhooks.
• الأعراف: Idempotency-Key على كل كتابة، ومؤشرات تصفّح مبهمة، و180 طلباً في الدقيقة لكل تثبيت، وغلاف خطأ موحّد.
• الأحداث الـ12 بما فيها fulfillment.requested، بتوقيع HMAC-SHA256 وإعادة محاولة حتى 8 مرات.