لأصحاب المتاجر الذين يبيعون في محل وفي متجرهم على DZBuild. صاحب المتجر وحده يستطيع ربط صندوق؛ أعضاء الفريق لا يستطيعون.

لكل الخطط. الصندوق ليس مفتاح API، فلا يحتاج خطة Enterprise ولا يأخذ مكان مفتاح.

بعد تسجيل أول صندوق تظهر إضافة DZBuild POS في لوحة التحكم مع الصناديق المرتبطة وزر الفصل وآخر المبيعات والمرتجعات وإغلاقات Z. الرابط https://dzbuild.com/dashboard/connected-devices يفتح هذه الصفحة.

الاكتشاف: GET https://dzbuild.com/.well-known/oauth-authorization-server (RFC 8414).

الصندوق عميل OAuth 2.0 عام اسمه dzbuild-pos-windows، بلا سرّ. يُقبل S256 وحده في PKCE، والتحويل يكون إلى http://127.0.0.1:PORT/oauth/callback على أي منفذ.

يدخل صاحب المتجر من متصفح النظام ويختار المتاجر التي يستعملها الصندوق، حتى 10 متاجر. ويمكن ربط الصندوق برمز أيضاً: يعرض الصندوق رمزاً، ويكتبه صاحب المتجر في https://dzbuild.com/device من هاتفه.

رمز الوصول يبدأ بـ dzpos_ ويدوم 15 دقيقة. رمز التحديث يُستبدل عند كل استعمال وينتهي بعد 30 يوماً دون استعمال أو 180 يوماً في المجموع. إرسال رمز تحديث قديم من جديد ينهي الربط.

كل نداء يحمل X-DZ-Store مع رقم المتجر، ما عدا GET /v1/me. المتجر الذي لم يختره صاحبه يُرجع 403.

كل POST وPATCH وDELETE يحمل Idempotency-Key، بالقواعد المذكورة في التكرار الآمن.

الحدود: 120 طلباً في الدقيقة لكل صندوق و600 لكل متجر. حصة الواجهة البرمجية الشهرية لا تنطبق على الصناديق.

فصل الصندوق من لوحة التحكم ينهي الربط: التحديث التالي يُرجع 400 invalid_grant ونبضة الاتصال التالية 410 device_revoked.

يعدّل العنصر المنتج المرتبط مسبقاً بـ external_id الخاص به. وإن لم يوجد، يتبنّى منتجاً بلا متغيرات له نفس sku وغير مرتبط بعد. وإن لم يوجد، ينشئ منتجاً بمخزون 0.

يُعثر على الفئة بـ external_id الخاص بها، أو تُنشأ من اسمها.

تذكر الاستجابة كل عنصر: external_id وid وstatus (created أو updated) وerror: null. العنصر المرفوض يحمل كائن error ولا يحمل id ولا status.

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

الدفعة لا تضبط المخزون أبداً. المخزون يمرّ عبر نداء التعديلات.

لا يُعدَّل إلا مخزون المنتجات التي تتابع المخزون على مستوى المنتج. المنتج الذي له مخزون لكل متغير يُرجع خطأ العنصر variant_product، والذي لا يتابع المخزون not_tracked، والمنتج الذي لم يعد موجوداً unknown_product.

تذكر الاستجابة كل عنصر بـ ref مع status إما ok وإما error.

تغييرات مخزون الصندوق لا تظهر أبداً في سجل تغييرات لوحة التحكم ولا تعرض تراجعاً.

تُحفظ الوثائق كما أُرسلت ولا تتغير أبداً: لا يوجد مسار تعديل أو حذف.

يُرجع البيع 201 مع {"id": 99120, "stock_applied": false}. المخزون يمرّ عبر نداء التعديلات، ولا يمرّ أبداً عبر وثيقة.

وثائق الصندوق منفصلة عن الطلبات. لا تُحسب في حدّ الطلبات الشهري للمتجر، ولا تُرسل أي إشعار، ولا تصل أبداً إلى Google Sheets ولا إلى webhooks.

المبالغ نصوص بخانتين عشريتين، والكميات أرقام بثلاث خانات عشرية على الأكثر، مع حتى 500 سطر و20 دفعة في الوثيقة.

إرسال وثيقة سُجّل external_id الخاص بها من قبل يُرجع 409 already_exists مع الرقم المسجّل في error.details.id. يعدّ الصندوق ذلك نجاحاً.

المرتجع على بيع متجر آخر يُرجع 404 not_found.

تعطي GET /v1/orders?updated_since=... وGET /v1/orders/{id} طلبات المتجر بصيغة الصندوق مع منتجاتها. order_number هو الرقم القصير للمتجر إن وُجد.

POST /v1/orders/{id}/claim مع device_id وterminal: أول صندوق يأخذ الطلب. الصندوق نفسه إذا أخذه من جديد يتلقى 200، وأي صندوق آخر يتلقى 409 order_claimed.

PATCH /v1/orders/{id} مع status يتطلب أخذ الطلب (409 claim_required في غير ذلك). الانتقالات المسموحة: من pending أو confirmed إلى processing أو shipped أو delivered، ومن processing إلى shipped أو delivered، ومن shipped إلى delivered. أي انتقال آخر يُرجع 409 transition_not_allowed.

تأخذ POST /v1/orders/{id}/cancel الحقل reason (out_of_stock أو customer_unreachable أو duplicate أو other) وnote اختيارية حتى 500 حرف. يعود المخزون حسب قواعد مخزون المتجر. إذا كان صندوق آخر قد أخذ الطلب، يُرجع الإلغاء 409 order_claimed.

تغيير الحالة من الصندوق يشغّل نفس الخطوات التي يشغّلها تغيير من لوحة التحكم، ومنها الإشعارات وتحديث Google Sheets.

تحتفظ الحافة بالنداء حتى 25 ثانية وتجيب فور حدوث تغيير.

النداء الأول، دون مؤشر، يبدأ بحدث order.updated لكل طلب في حالة pending أو confirmed أو processing.

الأنواع: order.created وorder.updated وproduct.updated وproduct.deleted وinventory.level_changed وcustomer.updated وdevice.revoked. لكل حدث id ثابت، فيستطيع الصندوق تجاهل التكرار.

يحمل inventory.level_changed الحقول old وnew وdelta وsource: order عندما يحرّك طلبٌ المخزون (مع رقم الطلب)، وdashboard لأي تغيير آخر حدث خارج الصندوق، وpos عندما يغيّره صندوق آخر في المتجر نفسه (يتجاهل الصندوق هذا المصدر).

كتابات الصندوق نفسه على المنتجات والمخزون لا تُرسل إليه من جديد.

يحمل device.revoked الحقل device_id كنص، مرة واحدة، بعد فصل الصندوق.

المؤشر الذي لم تُصدره هذه الواجهة يُرجع 400 bad_request.