دليل زد للتكامل مع ERP: ماذا تبني، وبأي ترتيب

لماذا هذا الدليل

مرجع الـ APIs على docs.zid.sa يخبرك ماذا يقبل كل Endpoint وماذا يُرجع. لكن حين تربط متجر زد بنظام ERP أو نظام محاسبي أو WMS أو نظام خلفي خاص بك، سؤالك مختلف: أي Endpoints يحتاجها التكامل؟ وبأي ترتيب؟ وأي سلوك يكسر التكامل في الشهر الثالث من التشغيل؟

دليل التكامل مع ERP مكتوب للإجابة على هذه الأسئلة الثلاثة تحديدًا. هو رفيق عملي لمرجع الـ APIs، لا بديل عنه: المرجع يبقى المصدر المعتمد لكل Request وResponse، والدليل يحمل ما يغيّر تصميم التكامل.

الدليل محايد تجاه النظام: يصف جانب زد من العقد، والقرارات التي يفرضها أي ERP، لا Connector مزوّد بعينه. ويخدم الحالتين معًا — تطبيق خاص لمتجر واحد، أو تطبيق عام في سوق التطبيقات يثبّته عدد من التجار. جمهوره المطوّرون ومعماريو الحلول والمستشارون الوظيفيون.

ماذا بداخله

يلخّص الدليل نفسه في جملة واحدة: زد تدفع إليك الطلبات والمنتجات والمخزون والعملاء عبر Webhook، وكل ما عداها تسحبه بنفسك داخل حد 60 طلبًا في الدقيقة لكل تطبيق لكل متجر. فاحسم «Push أم Pull» لكل Object قبل أن تكتب سطرًا واحدًا من الكود.

• الجزء الأول — مفاهيم قبل الكود: Push مقابل Pull، الـ Base URLs والـ Headers المختلفة لكل عائلة API، الـ OAuth ودورة حياة الـ Tokens، رحلة التثبيت التي تشترطها زد، الـ Scopes، نموذج المبالغ وVAT، حالة الطلب، المنتجات والـ Variants والمخزون، العملاء، الخصومات، محافظ العملاء، وطلبات الأسواق مثل مزيد وTrendyol.
• الجزء الثاني — قرارات التصميم: ما الذي تحسمه لكل Object على حدة (اتجاه المزامنة، ومصدر الحقيقة لكل حقل)، وتسع أسئلة تزيل أغلب الالتباس لاحقًا، وجدول يربط كل مفهوم في زد بما يقابله في أي ERP مع ما يجب الانتباه له.
• الجزء الثالث — البناء: مزامنة المنتجات والمخزون، الطلبات قراءةً وإنشاءً مع مرجع حقول كامل، المرتجعات والـ Credit Notes، الكوبونات والعروض، مستقبِل الـ Webhooks، الأخطاء والحدود والنقص الصامت، المبالغ والفوترة والمطابقة، ثم الاختبار والتحويل والإطلاق.
• الملحق: أمثلة محلولة بأرقام حقيقية من متجر تجريبي — طلب بكوبون واحد، وطلب بثلاثة كوبونات، وطلب Bundle، ودورة مرتجع كاملة — وجدول يربط كل سؤال تشغيلي بالقسم الذي يجيب عليه.

كيف تستخدمه

• اختر مسار القراءة في الصفحة الثانية. معماري الحل يبدأ من Push مقابل Pull ثم قرارات التصميم ثم الحدود. المطوّر يبدأ من الـ Headers والـ OAuth ثم الطلبات والـ Webhooks. المستشار المالي يبدأ من المبالغ والخصومات والفوترة.
• ابدأ من الجدول الأخير إذا كان سؤالك محددًا. جدول في نهاية الدليل يربط كل سؤال تشغيلي — «متى تُنشأ الفاتورة؟»، «كيف تُطابق العملاء؟» — برقم القسم وصفحته.
• استخدمه كقاعدة معرفة. كل قسم فرعي وحدة مستقلة فيها الادعاء ومسارات الحقول ومثال واحد، فيصلح كما هو لمساعد ذكاء اصطناعي أو RAG Index أو دليل دعم داخلي.
• اعبر قائمة الفحص قبل الإطلاق. الدليل يختم بمصفوفة اختبار وقائمة فحص Go-live وما تحتاجه المراقبة بعد التشغيل، إضافة إلى الشكل الذي تطلبه زد في أي تصعيد تقني.

خمسة أخطاء يوفّرها عليك

يفتح الدليل بخمسة أخطاء تكسر التكاملات في شهرها الثالث، وكلٌّ منها مربوط بالقسم الذي يعالجه:

1. وضع access_token في Header الـ Bearer، بينما مكانه X-Manager-Token.
2. غياب Job مراقَب لتجديد الـ Tokens التي تنتهي صلاحيتها بعد سنة.
3. إعادة حساب الإجماليات بدل ترحيل payment.invoice[] كما هي.
4. تشغيل منطق الفوترة بناءً على حالة الطلب بدل حالة الدفع.
5. إعادة إرسال عملية كتابة غير Idempotent دون البحث عنها أولًا.

قبل أن تبدأ

النسخة المنشورة هنا هي 1.2.0، روجعت في 7 أكتوبر 2026 مقابل منصة زد ومتجر تجريبي حيّ. سلوك المنصة يتغيّر، فإن اختلفت نسختك المحمّلة عن التوثيق المنشور على docs.zid.sa فالتوثيق هو الأصح.

الدليل ليس استشارة ضريبية أو قانونية؛ أقسام VAT والفوترة تشرح إعدادات المنصة ومعاني الحقول فقط. ومتاجر زد تعمل في أكثر من دولة: ما يخص السعودية وحدها — الفوترة الإلكترونية (ZATCA) والعنوان الوطني المختصر — موسوم داخل الدليل بعلامة KSA only، وما عداه مستقل عن السوق.