إنشاء تطبيق للتجارة الإلكترونية في الجزائر مع DZBuild.dev
تصدير كتالوج المنتجات، أو إرسال تنبيه عند وصول طلبية، أو بناء أداة لوكالة تسيّر متاجر زبائنها: كل هذه المشاريع تبدأ بالسؤال نفسه. كيف يحصل التطبيق على موافقة صاحب المتجر للوصول إلى البيانات التي يحتاجها؟
dzbuild.dev هي بوابة المطورين في DZBuild. تجمع الواجهة البرمجية للتجارة الإلكترونية وقوالب التطبيقات وأدلة التثبيت وموارد للمساعدين البرمجيين. نتبع في هذا الدليل مشروعًا أولًا عمليًا: تطبيقًا يتيح للتاجر تنزيل كتالوج منتجاته بصيغة CSV، بصلاحية قراءة المنتجات فقط.
صفحة إنشاء التطبيقات العامة، التُقطت في 1 أكتوبر 2026. لا تتضمن الصورة أي حساب تاجر أو بيانات متجر.
ما الذي يمكنك بناؤه باستخدام واجهة DZBuild البرمجية؟
تطبيق DZBuild هو خدمة ويب تستضيفها أنت. يوافق التاجر على صلاحياته داخل DZBuild، فيحصل خادمك على رمز وصول لذلك المتجر. يستدعي تطبيقك بعدها واجهة REST API للوصول إلى الموارد التي تسمح بها تلك الصلاحيات. لكل متجر ثبّت التطبيق رمز مستقل. يشرح دليل المطورين التمهيدي هذا المسار.
لمشاريع التجارة الإلكترونية في الجزائر، تشمل الواجهة المنتجات والطلبيات والزبائن والتوصيل وإعداداته وصفحات الهبوط وتخصيص المتجر والإحصائيات وقوالب رسائل الطلبات على WhatsApp. يعتمد الوصول على الصلاحيات المطلوبة وشروط الميزة المستخدمة. إرسال طرد أو رسالة WhatsApp إجراء مستقل؛ تثبيت التطبيق وحده لا ينفّذ أيًا منهما.
يمكنك بناء أداة لتصدير الكتالوج، أو ربط المتجر بأداة التقارير التي تستخدمها، أو إرسال تنبيهات الطلبات إلى فريق العمليات. توفّر القوالب الرسمية نقطة بداية لكل مشروع:
| القالب | ما يوفّره | متى تختاره؟ |
|---|---|---|
| تطبيق أساسي | التثبيت على المتجر ورابط الفتح وإدارة رموز الوصول | تريد إضافة شاشات تطبيقك ووظائفه |
| تصدير المنتجات | قائمة المنتجات وتنزيل ملف CSV | تريد مشروعًا أولًا يقرأ المنتجات دون تغيير المتجر |
| تنبيهات الطلبات | تنبيهات الطلبات الجديدة على Telegram باستعلامات دورية افتراضيًا | تحتاج مثالًا للتنبيهات وتدرك أن بيانات الطلبات ستصل إلى خدمة أخرى |
تجهّز صفحة إنشاء التطبيق تعليمات الإعداد حسب القالب المختار. ويتضمن مستودع القوالب العام أيضًا مثالًا باستخدام Node.js لتشغيله على خادمك.
تثبيت التطبيقات ومفاتيح API الشخصية لهما شروط مختلفة
لا يحتاج التاجر إلى خطة المؤسسات لمجرد تثبيت تطبيق معتمد. تثبيت التطبيقات متاح عبر خطط المتاجر، مع الالتزام بالحد الأدنى للخطة الذي يحدده التطبيق وشروط الميزات التي يستخدمها. أما مفاتيح API الشخصية للتاجر فتحتاج اشتراكًا ساريًا في خطة المؤسسات. تشرح صفحتا مفاهيم التطبيقات ومرجع API هذا الفرق.
إذا كنت توزّع أداة على التجار، فاستخدم مسار تثبيت التطبيقات. يرى صاحب المتجر الصلاحيات قبل الموافقة، ويحصل التطبيق على رمز مستقل لكل متجر. لا تطلب من زبونك مشاركة كلمة مرور لوحة التحكم أو لصق مفتاح API شخصي في محادثة.
التطبيقات في حالة المسودة تقتصر على المتاجر التي يملكها حساب المطور. عضويتك في فريق متجر لشخص آخر لا تكفي. يحتاج التطبيق إلى اعتماد قبل أن يتمكن التجار الآخرون من تثبيته.
أنشئ تطبيقًا لتصدير كتالوج المنتجات
يستخدم قالب الكتالوج صلاحية products:read. لا يحتاج إلى قراءة بيانات الزبائن أو تغيير الطلبات أو إرسال الطرود. لذلك يسهل التحقق من نتيجته: يجب أن تطابق قائمة المنتجات المتجر، وأن يحتوي الملف المنزّل على صفوف المنتجات المتوقعة.
تحتاج حساب DZBuild يملك متجرًا واستضافة لتطبيقك. ولقالب Cloudflare، تحتاج أيضًا حسابك على Cloudflare وصلاحيات النشر المذكورة في ملف README. يحدد مزوّد الاستضافة حدود الاستخدام وتكاليفه.
1. اختر تصدير المنتجات
افتح إنشاء تطبيق، واختر تصدير المنتجات، وأبقِ فقط الصلاحيات التي تستخدمها الميزة. اختر اسمًا لتطبيقك. لا تسمح قواعد التسجيل بوجود dzbuild داخل اسم التطبيق.
تعطيك الصفحة خيارًا للنشر وأوامر محلية والحقول التي تنسخها إلى منصة المطورين. أبقِ ملف README لقالب الكتالوج مفتوحًا أثناء العمل؛ فهو يشرح تفاصيل إعداد هذا القالب.
2. انشر التطبيق وأكمل إعداد التخزين
انشر القالب في حساب الاستضافة. زر النشر وحده لا يكمل إعداد قالب الكتالوج. يطلب ملف README تطبيق ترحيل قاعدة البيانات المرفق بعد النشر الأول بالزر، أو ضبط أمر النشر المذكور فيه لتطبيق الترحيل. تجهّز هذه الخطوة مساحة تخزين التطبيق لبيانات التثبيت.
استخدم عنوان HTTPS المخصص لتطبيقك كما هو. يمكنك البدء بعنوان على workers.dev. وإذا أضفت إشعارات webhook لاحقًا، فستحتاج إلى دومين مناسب تملكه.
3. سجّل التطبيق واحفظ بيانات اعتماده بأمان
افتح منصة المطورين وأنشئ تطبيقًا. انسخ عنوان إعادة التوجيه وعنوان الفتح من تعليمات النشر، وحدد products:read، وأضف أوصاف التطبيق وبيانات الدعم.
إذا استضفت التطبيق على العنوان التوضيحي https://app.example.com، فستكون عناوين القالب كما يلي:
| حقل التسجيل | قيمة توضيحية |
|---|---|
| رابط إعادة التوجيه | https://app.example.com/oauth/callback |
| رابط الفتح | https://app.example.com/launch |
| الصلاحية | products:read |
رابط webhook | اتركه فارغًا في مثال الكتالوج الأول |
استبدل دومين المثال بدومين تطبيقك. يجب أن يطابق عنوان إعادة التوجيه القيمة المسجّلة حرفيًا، بما فيها الشرطة المائلة الأخيرة. اتبع دليل البدء لملء نموذج التسجيل كاملًا.
ضع معرّف التطبيق client_id الذي حصلت عليه عند التسجيل في إعدادات القالب، ثم أعد النشر حسب تعليمات README. احفظ سرّ التطبيق ومفتاح التوقيع في مخزن الأسرار لدى مزوّد الاستضافة كما يوضح القالب. أبقِ رموز وصول المتاجر على خادمك. لا تضعها في شيفرة المتصفح أو لقطة شاشة أو مستودع عام أو طلب ترسله إلى مساعد برمجي.
4. ثبّته على متجر تملكه
افتح صفحة تثبيت تطبيقك ووافق على صلاحية قراءة المنتجات لمتجرك. يتولى القالب مسار التفويض عبر OAuth مع PKCE ويحفظ رمز ذلك التثبيت.
اختبار المسودة يستخدم بيانات المتجر الحقيقية، وليس بيئة تجريبية معزولة. استخدم متجرًا تتحكم فيه، وابدأ بهذه الميزة التي تقرأ البيانات فقط. إذا أضفت صلاحيات كتابة لاحقًا، فاختبر التغييرات الفعلية والإجراءات التي قد تترتب عليها.
أول فحص للواجهة في الدليل هو GET /v1/whoami، الذي يؤكد المتجر والصلاحيات المرتبطة بالرمز. في بيئة تطوير آمنة لديك، حيث يحتوي DZ_TOKEN مسبقًا على رمز التثبيت، يكون الطلب:
curl -sS https://api.dzbuild.app/v1/whoami \
-H "Authorization: Bearer $DZ_TOKEN"
يقرأ هذا الطلب هوية التثبيت. لا ينشئ طلبية ولا يعدّلها. لا تشارك معرّفات الحساب الواردة في الرد أو رمز الوصول.
5. افتح التطبيق وتحقق من ملف CSV
اضغط فتح للتطبيق في لوحة تحكم التاجر، ثم نزّل الكتالوج. قارن الملف بالمنتجات في متجر الاختبار. يصدّر القالب معرّف المنتج واسمه والجزء النصي من رابطه ورمز SKU والسعر والحالة؛ ويشرح ملف README إخراج الملف بترميز UTF-8 لعرض الأسماء العربية.
اختبر كتالوجًا فارغًا، واسم منتج بالعربية، واسمًا يحتوي على فاصلة أو علامة اقتباس. للكتالوج الأكبر، تحقق من عدد الصفوف المصدّرة ولا تفترض أن الشاشة الأولى تعرض كل المنتجات. تعرض شاشة القالب حتى 200 منتج؛ أما التصدير فيتابع صفحات النتائج ضمن حدود التنفيذ لدى مزوّد الاستضافة.
تعامل مع فشل التصدير كخطأ يحتاج إلى إصلاح. لا تعرض ملفًا على أنه الكتالوج الكامل إذا توقفت العملية بسبب صلاحية ناقصة أو جلسة تطبيق منتهية أو بلوغ حد الطلبات.
اربط مساعدًا برمجيًا بالتوثيق
توفّر صفحة ربط المساعدين تعليمات الإعداد للمساعدين البرمجيين. يتيح خادم @dzbuild/docs-mcp العام للأدوات المتوافقة قراءة توثيق المطورين ومرجع الواجهة البرمجية. لا يصل إلى حساب التاجر ولا ينفّذ إجراءات في متجرك.
يمكنك أيضًا إعطاء المساعد فهرس التوثيق ومهارة بناء التطبيقات ووصف OpenAPI. مثال على طلب محدد:
اقرأ توثيق المطورين في DZBuild وقالب الكتالوج. ساعدني في بناء تطبيق لتصدير الكتالوج باستخدام
products:readفقط. احفظ بيانات الاعتماد في مخزن أسرار على الخادم. اختبر الكتالوج الفارغ والأسماء العربية وتعدد صفحات النتائج ورفض التثبيت وسحب صلاحية الوصول.
راجع الشيفرة الناتجة وشغّل اختباراتها قبل ربطها ببيانات متجر. يوضح دليل البناء بالذكاء الاصطناعي أخطاء متكررة، منها طلب صلاحيات غير ضرورية وافتراض أن رمزًا واحدًا يصل إلى عدة متاجر.
قبل إضافة إشعارات webhook أو إجراءات تغيّر المتجر
يعمل مثال الكتالوج دون webhook. لاستقبال أحداث الطلبات أو إشعارات إزالة التطبيق، سجّل رابط webhook وتحقق منه في منصة المطورين. لا يُقبل عنوان على workers.dev لاستقبال هذه الإشعارات؛ يحتاج التطبيق إلى دومين مناسب تملكه. ولا تستطيع رموز تثبيت التطبيقات إدارة واجهة التاجر /v1/webhooks. اتبع دليل إشعارات التطبيقات.
تحقق من توقيع إشعار webhook قبل معالجة محتواه، وتعامل مع الإشعارات المكررة، وتوقف عن استخدام رمز المتجر عند سحب الوصول. تحتاج طلبات POST وPATCH وDELETE إلى Idempotency-Key، ويستدعي رد 429 الانتظار وفق قيمة Retry-After. يشرح دليل حدود الطلبات هذه القواعد.
لإضافة وظائف WhatsApp، اقرأ دليل الربط مع WhatsApp قبل إضافة الإرسال. صلاحية التطبيق لا تلغي شروط الخطة أو رصيد الرسائل الذي تحتاجه الميزة.
جهّز التطبيق لمراجعة إتاحته للتجار
قبل الإرسال، اختبر التطبيق على متجرك وجهّز شعاره وأوصافه بالإنجليزية والعربية والفرنسية وبريد الدعم وعنوان الفتح بـ HTTPS وعنوان إعادة التوجيه والصلاحيات المطلوبة. إذا أعددت webhook، يجب التحقق منه. تجد المتطلبات الدقيقة في قائمة المراجعة.
وضّح البيانات التي يقرأها التطبيق والتغييرات التي يجريها وطريقة الحصول على المساعدة. تطبيق تصدير الكتالوج يحتاج صلاحية قراءة المنتجات؛ إضافة صلاحيات لا تتعلق بوظيفته تصعّب تقييم الغرض منها. راجع متطلبات الأمان لمعرفة كيفية التعامل مع بيانات الاعتماد وبيانات التجار.
بعد الاعتماد، يصبح التطبيق متاحًا للتجار الذين يستوفون شروطه. الاعتماد لا يضمن التثبيتات أو الإيرادات: يحتاج التاجر إلى فائدة واضحة من التطبيق ودعم يمكن الاعتماد عليه.
أسئلة قبل أن تبدأ
هل تستضيف DZBuild تطبيقي؟
تستضيف التطبيق في حساب الاستضافة أو الخادم الذي تختاره. توفّر DZBuild الربط بالمتجر والواجهة البرمجية. تدعم القوالب الرسمية Cloudflare Workers، ويضم المستودع مثالًا باستخدام Node.js.
هل يمكن اختبار تطبيق مسودة على متجر زبون؟
تثبيت المسودة متاح فقط على المتاجر التي يملكها حساب المطور. أما متجر الزبون فيحتاج إلى اعتماد التطبيق قبل أن يتمكن صاحبه من تثبيته.
ماذا يحدث عندما يزيل التاجر التطبيق؟
يُلغى رمز وصول التثبيت، وعلى التطبيق التعامل مع فقدان الوصول. يشرح قالب الكتالوج كيفية التعامل مع ردود رفض الوصول عندما لا يكون إشعار إزالة التطبيق عبر webhook مفعّلًا.
من أين أبدأ؟
افتح إنشاء تطبيق على dzbuild.dev، واختر تصدير المنتجات، واتبع تعليمات إعداد القالب مع دليل البدء. إذا لم يكن لديك حساب DZBuild بعد، استخدم صفحة التسجيل.