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

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

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

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

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

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

المصادقة: مفتاح منصة بصلاحيتَي orders:write وorders:read. يتطلب Idempotency-Key. الرد يعيد قراءة الطلب، لذلك المفتاح الذي يملك orders:write وحدها يُحفَظ طلبه لكنه يتلقى 403 forbidden، وإعادة المحاولة بنفس Idempotency-Key تُعيد نفس 403.

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

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

هام — تسعير معتمد على الخادم. أنت لا تُحدّد سعر السطر. يُستعمل دائمًا سعر المنتج الحالي في الكتالوج. إن أرسلت حقل 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 (لا يقل عن 0)، حيث shipping_cost هو ما يحسبه الخادم نفسه. و subtotal نفسه = sum(items[].quantity × (price + Σ variants.price_adjustment)).

الحقل الوحيد الذي يُؤخذ من جسم طلبك هو discount. يجب أن يكون ≥ 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. إن أعدت نفس الطلب (نفس Idempotency-Key ونفس مفتاح API ونفس بايتات الجسم) خلال 24 ساعة نُعيد لك نفس الاستجابة مع Idempotency-Replay: 1، فيُنشأ الطلب مرة واحدة فقط. ردود الخطأ تُعاد هي أيضًا، ما عدا 429 و5xx، ونفس Idempotency-Key مع جسم مختلف يرد بـ 422 idempotency_key_reuse: أرسل الطلب المصحَّح بمفتاح جديد. انظر 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 (ضمن الصلاحيات الافتراضية). المفتاح الذي لا يملكها يتلقى 403 forbidden "Missing scope: orders:read".

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

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

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

المصادقة: مفتاح بصلاحية orders:read. المفتاح الذي لا يملكها يتلقى 403 forbidden.

store_seq هو رقم الطلب الظاهر في لوحة التحكم (#644)؛ إنشاء الطلب عبر الـ API يرقّمه قبل الرد، وفي الحالة النادرة التي يفشل فيها الترقيم يبقى null إلى أن يُملأ بعد قليل. يصبح shipment.sent_to_delivery صحيحًا (true) عندما تقبل شركة التوصيل الطرد، وdelivery_company هي الشركة (معرّفها النصي) وdelivery_tracking رقم التتبع. shipment.last_send_failure هو آخر إرسال مرفوض لهذا الطلب (at وprovider وmessage كما أرسلتها الشركة) أو null إن لم يفشل أي إرسال. ويكون دائمًا null متى صار sent_to_delivery صحيحًا، فالفشل السابق لا يظهر بعد إرسال ناجح. تُرجع نداءات الإنشاء والتحديث والإلغاء الكائن نفسه.

مصفوفة 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 وorders:read. يتطلب Idempotency-Key. بدون orders:read تتغير الحالة فعلًا، لكن الرد يكون 403 forbidden.

الجسم يجب أن يكون {"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 وorders:read. يتطلب Idempotency-Key. بدون orders:read يُلغى الطلب فعلًا، لكن الرد يكون 403 forbidden.

يسلّم الطلب لشركة التوصيل الخاصة بالمتجر، وهو نفس الإرسال الذي يقوم به الزر في لوحة التحكم. لا يمكن استرجاع الطرد بعد أن تستلمه الشركة، لذلك يمر كل إرسال بنداءين ويوافق التاجر على الأول.

المصادقة: مفتاح بصلاحية delivery:send. يتطلب Idempotency-Key. المفاتيح المُنشأة من الإعدادات ← واجهة API لا تحمل هذه الصلاحية وتتلقى 403 forbidden؛ أما التطبيق فيحصل عليها عندما يوافق التاجر عليها أثناء التثبيت.

عادةً يجري الإرسال في الخلفية ويرد بـ 202 مع queued: true. اقرأ GET /v1/orders/{id} إلى أن يصبح shipment.sent_to_delivery صحيحًا ومعه delivery_tracking، أو إلى أن يُظهر shipment.last_send_failure رفض الشركة. وإن لم يكن التشغيل في الخلفية متاحًا يجري الإرسال داخل النداء نفسه: 200 مع sent وprovider وtracking، أو 422 courier_refused مع رسالة الشركة. بعد أن تقبل الشركة الطرد، ينتقل الطلب من pending أو confirmed إلى processing، وهذا يخصم المخزون إن لم يكن قد خُصم. الطلبات من نوع التسليم pickup لا تُسلَّم أبدًا لشركة توصيل. والإرسال في الخلفية الذي يتوقف قبل الاتصال بالشركة، مثل إرسال طلب pickup أو شركة غير مرتبطة، يرد مع ذلك بـ 202 ولا يغيّر أيًا من حقلَي shipment.

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

للمنتج 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…). يُرجعها GET /v1/products/{id} في combinations[] (لكل واحدة id وsku وstock وis_active وخياراتها options) مع combination_count؛ وتتوقف القائمة عند 300 عنصر، ويُخبرك combinations_truncated إن قُطعت. انظر المنتجات. ويتحرك مخزون التركيبات في نفس اللحظة التي يتحرك فيها باقي مخزون الطلب.

تتيح إضافة 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.