الطلبات هي قلب المنصة. كل طلب:

وهذه خريطة الانتقالات التي تفرضها الواجهة البرمجية بالضبط، لكل حالة:

الإلغاء مشروع فقط من pending وconfirmed وprocessing — الطلب الذي بلغ shipped أو delivered لم يعد يمكن إلغاؤه.

وتعديل الطلب بـ PATCH إلى الحالة التي هو عليها أصلًا هو عملية 200 بلا أثر.

cancelled و returned حالتان نهائيتان — لا يمكن الخروج منهما.

أنشئ طلبًا جديدًا للمتجر المنادي. يستعمله الثيمات المخصصة والتطبيقات المحمولة والموزّعون وأي واجهة headless ترسل الطلبات من خادمها الخاص بدل استعمال checkout واجهة المتجر المدمجة.

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

يُنشأ الطلب بحالة pending. لا يُلتزَم المخزون عند الإنشاء — أول انتقال إلى حالة مُلتزِمة (confirmed أو processing أو shipped أو delivered) هو من يخصم المخزون، تمامًا كتدفّق اللوحة. الهدف من ذلك: ترك مساحة لفريق العمليات لتصفية الطلبات الوهمية والمكررة وغير المُجاب عنها قبل لمس المخزون.

العملاء يُزال تكرارهم بالمتجر + رقم الهاتف. إن وُجد عميل بهذا الهاتف في متجرك، يُحدَّث (الاسم، الولاية، البلدية، العنوان، البريد) ويُعاد استخدامه. وإلا يُنشَأ سجل جديد.

هام — تسعير معتمد على الخادم. أنت لا تُحدّد سعر السطر. يُستعمل دائمًا سعر المنتج الحالي في الكتالوج. إن أرسلت حقل price فهو يُتجاهل.

وprice_adjustment لكل متغيّر معتمد على الخادم أيضًا: لكل زوج (group_name, option_name) يطابق خيارًا حقيقيًا على المنتج، تستبدل DZBuild قيمة price_adjustment الخاصة بالكتالوج. قيمتك تبقى فقط للأزواج غير الموجودة في الكتالوج — وهو تساهُل مقصود للتكاملات القديمة — لذا فأي "خصم" سالب تخترعه يُهمَل بصمت لأي خيار حقيقي. عامل price_adjustment عند الإدخال على أنه معلوماتي فقط: أعِد إرسال القيمة كما وردت من GET /v1/products/{id} كي يطابق إجماليك المحسوب عند العميل إجمالي الخادم.

كل كائن متغيّر يصف خيارًا مختارًا لمجموعة متغيرات على المنتج:

أرسل كائن متغيّر واحد لكل مجموعة مختارة على هذا السطر. فـ "تيشيرت أحمر مقاس L" يصبح إدخالين (واحد لـ Color/Red وآخر لـ Size/L). تعرضها DZBuild على صفحة الطلب في اللوحة كما لو اختارها العميل من الواجهة تمامًا.

للمنتجات التي تستخدم متغيرات لكل قطعة (مثل عرض "اشترِ 3 تيشيرتات، اختر لونًا لكل قطعة")، استخدم quantity = 1 لكل سطر وأنشئ سطرًا لكل قطعة — هذا أنظف ربط.

الإجمالي يُحسب على الخادم: subtotal + shipping_cost - discount + payment_fee (لا يقل عن 0). و subtotal نفسه = sum(items[].quantity × (price + Σ variants.price_adjustment)).

تُؤخذ الحقول shipping_cost وdiscount وpayment_fee كما أُرسلت تمامًا — والتحقق الوحيد هو أن كلًّا منها ≥ 0. وهي لا تُقارَن بأسعار الشحن أو أكواد الخصم المعرَّفة في متجرك، لذلك يجب استدعاء POST /v1/orders من خادم موثوق فقط، ولا يجوز إطلاقًا استدعاؤه من كود متصفح أو تطبيق يمكن للزبون العبث به.

إنشاء الطلب يُرجع HTTP 200 وليس 201 — لا تتفرّع على رمز الحالة؛ تحقّق من data.id / data.order_number بدلًا من ذلك. الجسم بنفس شكل GET /v1/orders/{id} — معبّأ بالكامل بالإجماليات المحسوبة، وكتلة العميل المعيارية، وسطور العناصر التي أنشأتها للتو (مع متغيراتها).

صيغة order_number هي ORD-{store_id}-{YYYYMMDD}-{8 أحرف hex كبيرة}. وطلبات صفحات الهبوط تستعمل LP-{8 أحرف hex كبيرة}. أما الطلبات المُنشأة قبل 2026-06-02 فتحمل لاحقة قديمة من 4 أحرف hex، لذا يجب أن يقبل المحلّل الطولين.

سقف الطلبات الشهري. الخطة Free محدودة بـ 30 طلبًا في الشهر التقويمي؛ أما Pro و Unlimited و Enterprise فبلا سقف. واسم خطة غير معروف يعود أيضًا إلى سقف 30/شهر المجاني. العدّاد شهري تقويمي ويشمل كل مصادر الطلبات (واجهة المتجر + صفحة الهبوط + لوحة التحكم + الواجهة البرمجية).

كل POST يجب أن يحمل رأس Idempotency-Key. إن أعدت المحاولة بنفس المفتاح ونفس المتجر خلال 24 ساعة نُعيد لك نفس الاستجابة — يُنشأ الطلب مرة واحدة فقط. انظر Idempotency.

إنشاء طلب يُطلق order.created لكل اشتراكات /v1/webhooks على هذا الحدث. انظر أحداث Webhook.

⚠️ تنبيه — /v1/webhooks ترى نشاط الواجهة البرمجية فقط

اشتراكات /v1/webhooks تُطلق فقط للتغييرات التي تمت عبر واجهة v1. أما الطلبات الموضوعة على واجهة المتجر أو على صفحة هبوط، وتغييرات الحالة من لوحة التحكم، فلا تُطلق order.created / order.confirmed / order.shipped.

للحصول على أحداث تغطي كل نشاط الطلبات، استعمل إضافة Webhooks (/dashboard/addons ← "Webhooks — Connect n8n, Make & Zapier"، تتطلب خطة Unlimited) وهي تلتقط كل طلب مهما كان مصدره — أو واصل الاستطلاع عبر GET /v1/orders?since=….

الطلب المُنشأ عبر الواجهة البرمجية هو إدراج مبسّط. مقارنةً بطلب من واجهة المتجر أو صفحة هبوط أو لوحة التحكم، فهو لا:

ولاحظ أيضًا أن العميل الذي تُنشئه الواجهة البرمجية تُخزَّن فيه سلسلة customer.name كاملةً في first_name ويُترك last_name فارغًا؛ أما العميل الموجود مسبقًا والمطابَق برقم الهاتف فيُستبدَل فيه first_name فقط، ويُترك أي last_name موجود دون تغيير.

اسرد الطلبات. ترقيم بالمؤشّر.

المصادقة: أي مفتاح منصة نشِط للمتجر (orders:read ممنوحة افتراضيًا وغير مطبَّقة بشكل منفصل في v1؛ المفحوصة هي orders:write فقط على نقاط الكتابة).

قيمة status غير الصالحة أو since غير القابلة للتحليل تُتجاهَل بصمت — فتحصل على القائمة غير المصفّاة لا على 400. ولا يوجد فلتر payment_status في v1؛ صفِّ من جانب العميل.

عرض القائمة مضغوط عمدًا (بدون عناصر ولا متغيرات). اطلب GET /v1/orders/{id} للتفاصيل الكاملة.

تفاصيل كاملة مع سطور العناصر والمتغيرات وكتلة العميل.

المصادقة: أي مفتاح منصة نشِط للمتجر (orders:read غير مطبَّقة بشكل منفصل في v1).

مصفوفة variants على كل عنصر هي المرجع لما اختاره العميل. كل إدخال يحمل order_item_id وgroup_name وoption_name وcolor_code (لمتغيرات اللون) وprice_adjustment (الإضافة لكل قطعة، وتُرجَع كسلسلة string في JSON لا كعدد). لعروض القطع المتعددة قد ترى عدة إدخالات متغيرات على نفس العنصر بتجميعات مختلفة — انظر ملاحظات القطع المتعددة أدناه.

إضافات المنتج (الحقول المخصصة المدفوعة التي يضبطها التاجر على منتج) ليس لها أي سطح في v1: لا يمكنك إرسالها في POST /v1/orders، وGET /v1/orders/{id} لا يُرجع أي إدخالات إضافات. أما الطلب الموضوع على واجهة المتجر مع إضافات فيُقرأ عبر الواجهة البرمجية وقيمة الإضافات مدمجة أصلًا في items[].price (وبالتالي في amounts.subtotal) — لكن بدون أي سطر إضافة ولا عنوان ولا نسبة ملف.

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

الجسم يجب أن يكون {"status": "<one of the 7>"}. نتحقق من الانتقال مقابل الجدول في دورة الحياة؛ وإلا نُرجع 400 مع الحالات التالية المسموح بها. وتعديل الطلب إلى حالته الحالية هو عملية 200 بلا أثر.

تُرجع 200 وتفاصيل الطلب المحدّث. الانتقالات المتزامنة على نفس الطلب تُنفَّذ بالتسلسل: إن غيّر طلبٌ آخر الحالة قبلك، يفشل طلبك بنظافة بـ bad_request ("order status changed concurrently; retry") بدل أن يُطبَّق مرتين.

حالات الالتزام بالمخزون هي confirmed وprocessing وshipped وdelivered.

المخزون لا يُتحقَّق منه: الخصم يتوقف عند الصفر، فلا يُرفض البيع الزائد أبدًا، وأي مشكلة في المخزون لا تُفشل تغيير الحالة ولا تتراجع عنه. ويتصرّف المخزون تمامًا كما يتصرّف مع الطلبات المُدارة من لوحة التحكم.

نقطة مريحة — تكافئ تمامًا PATCH /v1/orders/{id} مع {"status":"cancelled"}. نفس جدول الانتقالات، بلا أي صلاحية إضافية. الإلغاء مشروع فقط من pending وconfirmed وprocessing؛ ومن shipped أو delivered ستحصل على 400 bad_request (فتلك الحالتان لا تنتقلان إلا إلى delivered / returned).

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

تجعل المتغيرات منتجًا واحدًا يغطي خيارات متعددة (لون، حجم، خامة، سعة…). على الواجهة يضغط العملاء بطاقات المتغيرات لاختيار ما يريدون؛ على الواجهة البرمجية ترسل أنت الخيارات المختارة كجزء من الطلب.

للمنتج 0 أو أكثر من مجموعات المتغيرات. للمجموعة 0 أو أكثر من الخيارات. كل خيار يمكن أن يحمل:

اقرأ GET /v1/products/{id} لرؤية كل المجموعات والخيارات لمنتج:

منتج بـ 2 ألوان × 3 مقاسات لديه 6 تركيبات.

حوّل اختيار العميل إلى إدخال متغيّر واحد لكل مجموعة مختارة. لـ "تيشيرت أحمر مقاس L":

الأسماء التي ترسلها تُحفظ كما هي على الطلب — يجب أن تطابق ما أعاده GET /v1/products/{id}. price_adjustment يُضاف لسعر السطر (فيكون final_price = product.price + Σ price_adjustment)، لكن لأي زوج موجود في الكتالوج يستبدل الخادم قيمته الخاصة، فأرسل رقم الكتالوج.

إن فعّل التاجر variant_stock_enabled على منتج، يحمل كل خيار متغيّر عداد مخزونه. اقرأه من options[].stock. الواجهة لا تمنعك من إنشاء طلب بـ quantity > stock — هذا قرار التاجر. ويُخصم المخزون عند أول انتقال إلى حالة مُلتزِمة (confirmed، processing، shipped، delivered) ولا يُتحقَّق منه أبدًا: الخصم يتوقف عند الصفر، فيُسجَّل البيع الزائد بدل أن يُرفض.

إن فُعّل combination_stock_enabled يُتتبع المخزون لكل تركيبة (Red+L = 5، Red+M = 8…). التركيبات لم تُكشف بعد على نقطة المنتجات العامة (ستُكشف في v1.1 كمصفوفة combinations[] على GET /v1/products/{id}/combinations). حاليًا يُطبَّق مخزون التركيبات عند تأكيد الطلب ويظهر في لوحة التحكم.

تتيح إضافة Cascading Variants للتاجر جعل خيارات المجموعة B تعتمد على اختيار المجموعة A (مثل "علامة → موديل" — اختيار "Apple" للعلامة يُظهر فقط "iPhone 15" / "iPhone 14" للموديل). وهذه الإضافة تتطلب خطة Pro.

لا يكشف GET /v1/products/{id} أي معلومات عن التدرّج — فخريطة الأب/الابن لا تُطبَّق إلا في واجهة المتجر وفي لوحة التحكم. لا يستطيع عميلك اكتشاف قواعد التدرّج عبر الواجهة البرمجية في v1: ثبّتها في الكود أو اقرأها من لوحة التحكم. وإرسال تركيبة غير صالحة يُنشئ الطلب رغم ذلك (لا نمنعه) — لكن التاجر سيرفضه عند التأكيد.

بعض التجار يستخدمون نوع image_text للمتغيرات (صورة مصغرة بجانب اسم الخيار). على الواجهة البرمجية ما زلت ترسل group_name + option_name — الصورة شأن واجهة فقط ولا تكون جزءًا من حمولة الطلب.

إن أطلق التاجر عرض "اشترِ 3، اختر ألوانًا"، يختار العميل متغيرًا مختلفًا لكل قطعة. على الواجهة البرمجية:

ثلاثة سطور منفصلة، كل واحد quantity = 1. هكذا تعرض صفحة الطلب لون كل قطعة بنظافة.

تبني واجهة React/Vue/Next.js تتحدث مع الواجهة البرمجية بدلًا من ثيمات DZBuild المضمّنة. التدفّق:

انظر دليل الثيمات والواجهات المخصصة لخطوات كاملة.

استخدم فلتر since:

الاستطلاع هو الأداة الصحيحة هنا. فاشتراك /v1/webhooks على order.created لا يغطي إلا الطلبات التي أنشأها تكاملك أنت عبر الواجهة البرمجية — أما طلبات واجهة المتجر وصفحات الهبوط فلا تُطلقه أبدًا، ولذلك لا يمكنه أن يحلّ محل مسح since. انظر Webhooks.