# إنشاء تطبيق للتجارة الإلكترونية في الجزائر مع DZBuild.dev

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

**[dzbuild.dev](https://dzbuild.dev/ar/) هي بوابة المطورين في DZBuild.** تجمع الواجهة البرمجية للتجارة الإلكترونية وقوالب التطبيقات وأدلة التثبيت وموارد للمساعدين البرمجيين. نتبع في هذا الدليل مشروعًا أولًا عمليًا: تطبيقًا يتيح للتاجر تنزيل كتالوج منتجاته بصيغة `CSV`، بصلاحية قراءة المنتجات فقط.

![بوابة DZBuild العامة للمطورين تعرض قوالب التطبيقات الرسمية الثلاثة وشعار DZBuild الأصلي.](/ar/assets/images/cover-ar-1829a25a83efccc12fdb581dd5c9983c.png)

*صفحة إنشاء التطبيقات العامة، التُقطت في 1 أكتوبر 2026. لا تتضمن الصورة أي حساب تاجر أو بيانات متجر.*

## ما الذي يمكنك بناؤه باستخدام واجهة DZBuild البرمجية؟[​](#ما-الذي-يمكنك-بناؤه-باستخدام-واجهة-dzbuild-البرمجية "رابط مباشر إلى ما الذي يمكنك بناؤه باستخدام واجهة DZBuild البرمجية؟")

تطبيق `DZBuild` هو خدمة ويب تستضيفها أنت. يوافق التاجر على صلاحياته داخل `DZBuild`، فيحصل خادمك على رمز وصول لذلك المتجر. يستدعي تطبيقك بعدها واجهة `REST API` للوصول إلى الموارد التي تسمح بها تلك الصلاحيات. لكل متجر ثبّت التطبيق رمز مستقل. يشرح [دليل المطورين التمهيدي](https://dzbuild.dev/ar/intro) هذا المسار.

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

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

| القالب          | ما يوفّره                                                         | متى تختاره؟                                                       |
| --------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
| تطبيق أساسي     | التثبيت على المتجر ورابط الفتح وإدارة رموز الوصول                 | تريد إضافة شاشات تطبيقك ووظائفه                                   |
| تصدير المنتجات  | قائمة المنتجات وتنزيل ملف `CSV`                                   | تريد مشروعًا أولًا يقرأ المنتجات دون تغيير المتجر                 |
| تنبيهات الطلبات | تنبيهات الطلبات الجديدة على `Telegram` باستعلامات دورية افتراضيًا | تحتاج مثالًا للتنبيهات وتدرك أن بيانات الطلبات ستصل إلى خدمة أخرى |

تجهّز [صفحة إنشاء التطبيق](https://dzbuild.dev/ar/apps/new) تعليمات الإعداد حسب القالب المختار. ويتضمن [مستودع القوالب العام](https://github.com/DZBuild-com/dzbuild-app-starter) أيضًا مثالًا باستخدام `Node.js` لتشغيله على خادمك.

## تثبيت التطبيقات ومفاتيح API الشخصية لهما شروط مختلفة[​](#تثبيت-التطبيقات-ومفاتيح-api-الشخصية-لهما-شروط-مختلفة "رابط مباشر إلى تثبيت التطبيقات ومفاتيح API الشخصية لهما شروط مختلفة")

**لا يحتاج التاجر إلى خطة المؤسسات لمجرد تثبيت تطبيق معتمد.** تثبيت التطبيقات متاح عبر خطط المتاجر، مع الالتزام بالحد الأدنى للخطة الذي يحدده التطبيق وشروط الميزات التي يستخدمها. أما مفاتيح `API` الشخصية للتاجر فتحتاج اشتراكًا ساريًا في خطة المؤسسات. تشرح صفحتا [مفاهيم التطبيقات](https://dzbuild.dev/ar/concepts) و[مرجع API](https://dzbuild.dev/ar/api-reference) هذا الفرق.

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

التطبيقات في حالة المسودة تقتصر على المتاجر التي يملكها حساب المطور. عضويتك في فريق متجر لشخص آخر لا تكفي. يحتاج التطبيق إلى اعتماد قبل أن يتمكن التجار الآخرون من تثبيته.

## أنشئ تطبيقًا لتصدير كتالوج المنتجات[​](#أنشئ-تطبيقًا-لتصدير-كتالوج-المنتجات "رابط مباشر إلى أنشئ تطبيقًا لتصدير كتالوج المنتجات")

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

تحتاج حساب `DZBuild` يملك متجرًا واستضافة لتطبيقك. ولقالب `Cloudflare`، تحتاج أيضًا حسابك على `Cloudflare` وصلاحيات النشر المذكورة في ملف `README`. يحدد مزوّد الاستضافة حدود الاستخدام وتكاليفه.

### 1. اختر تصدير المنتجات[​](#1-اختر-تصدير-المنتجات "رابط مباشر إلى 1. اختر تصدير المنتجات")

افتح [إنشاء تطبيق](https://dzbuild.dev/ar/apps/new)، واختر **تصدير المنتجات**، وأبقِ فقط الصلاحيات التي تستخدمها الميزة. اختر اسمًا لتطبيقك. لا تسمح قواعد التسجيل بوجود `dzbuild` داخل اسم التطبيق.

تعطيك الصفحة خيارًا للنشر وأوامر محلية والحقول التي تنسخها إلى منصة المطورين. أبقِ [ملف README لقالب الكتالوج](https://github.com/DZBuild-com/dzbuild-app-starter/tree/main/cloudflare-catalog) مفتوحًا أثناء العمل؛ فهو يشرح تفاصيل إعداد هذا القالب.

### 2. انشر التطبيق وأكمل إعداد التخزين[​](#2-انشر-التطبيق-وأكمل-إعداد-التخزين "رابط مباشر إلى 2. انشر التطبيق وأكمل إعداد التخزين")

انشر القالب في حساب الاستضافة. **زر النشر وحده لا يكمل إعداد قالب الكتالوج.** يطلب ملف `README` تطبيق ترحيل قاعدة البيانات المرفق بعد النشر الأول بالزر، أو ضبط أمر النشر المذكور فيه لتطبيق الترحيل. تجهّز هذه الخطوة مساحة تخزين التطبيق لبيانات التثبيت.

استخدم عنوان `HTTPS` المخصص لتطبيقك كما هو. يمكنك البدء بعنوان على `workers.dev`. وإذا أضفت إشعارات `webhook` لاحقًا، فستحتاج إلى دومين مناسب تملكه.

### 3. سجّل التطبيق واحفظ بيانات اعتماده بأمان[​](#3-سجّل-التطبيق-واحفظ-بيانات-اعتماده-بأمان "رابط مباشر إلى 3. سجّل التطبيق واحفظ بيانات اعتماده بأمان")

افتح [منصة المطورين](https://dzbuild.com/dashboard/developer) وأنشئ تطبيقًا. انسخ عنوان إعادة التوجيه وعنوان الفتح من تعليمات النشر، وحدد `products:read`، وأضف أوصاف التطبيق وبيانات الدعم.

إذا استضفت التطبيق على **العنوان التوضيحي** `https://app.example.com`، فستكون عناوين القالب كما يلي:

| حقل التسجيل        | قيمة توضيحية                             |
| ------------------ | ---------------------------------------- |
| رابط إعادة التوجيه | `https://app.example.com/oauth/callback` |
| رابط الفتح         | `https://app.example.com/launch`         |
| الصلاحية           | `products:read`                          |
| رابط `webhook`     | اتركه فارغًا في مثال الكتالوج الأول      |

استبدل دومين المثال بدومين تطبيقك. يجب أن يطابق عنوان إعادة التوجيه القيمة المسجّلة حرفيًا، بما فيها الشرطة المائلة الأخيرة. اتبع [دليل البدء](https://dzbuild.dev/ar/getting-started) لملء نموذج التسجيل كاملًا.

ضع معرّف التطبيق `client_id` الذي حصلت عليه عند التسجيل في إعدادات القالب، ثم أعد النشر حسب تعليمات `README`. احفظ سرّ التطبيق ومفتاح التوقيع في مخزن الأسرار لدى مزوّد الاستضافة كما يوضح القالب. أبقِ رموز وصول المتاجر على خادمك. لا تضعها في شيفرة المتصفح أو لقطة شاشة أو مستودع عام أو طلب ترسله إلى مساعد برمجي.

### 4. ثبّته على متجر تملكه[​](#4-ثبّته-على-متجر-تملكه "رابط مباشر إلى 4. ثبّته على متجر تملكه")

افتح صفحة تثبيت تطبيقك ووافق على صلاحية قراءة المنتجات لمتجرك. يتولى القالب مسار التفويض عبر `OAuth` مع `PKCE` ويحفظ رمز ذلك التثبيت.

**اختبار المسودة يستخدم بيانات المتجر الحقيقية، وليس بيئة تجريبية معزولة.** استخدم متجرًا تتحكم فيه، وابدأ بهذه الميزة التي تقرأ البيانات فقط. إذا أضفت صلاحيات كتابة لاحقًا، فاختبر التغييرات الفعلية والإجراءات التي قد تترتب عليها.

أول فحص للواجهة في الدليل هو `GET /v1/whoami`، الذي يؤكد المتجر والصلاحيات المرتبطة بالرمز. في بيئة تطوير آمنة لديك، حيث يحتوي `DZ_TOKEN` مسبقًا على رمز التثبيت، يكون الطلب:

```
curl -sS https://api.dzbuild.app/v1/whoami \

  -H "Authorization: Bearer $DZ_TOKEN"
```

يقرأ هذا الطلب هوية التثبيت. لا ينشئ طلبية ولا يعدّلها. لا تشارك معرّفات الحساب الواردة في الرد أو رمز الوصول.

### 5. افتح التطبيق وتحقق من ملف CSV[​](#5-افتح-التطبيق-وتحقق-من-ملف-csv "رابط مباشر إلى 5. افتح التطبيق وتحقق من ملف CSV")

اضغط **فتح** للتطبيق في لوحة تحكم التاجر، ثم نزّل الكتالوج. قارن الملف بالمنتجات في متجر الاختبار. يصدّر القالب معرّف المنتج واسمه والجزء النصي من رابطه ورمز `SKU` والسعر والحالة؛ ويشرح ملف `README` إخراج الملف بترميز `UTF-8` لعرض الأسماء العربية.

اختبر كتالوجًا فارغًا، واسم منتج بالعربية، واسمًا يحتوي على فاصلة أو علامة اقتباس. للكتالوج الأكبر، تحقق من عدد الصفوف المصدّرة ولا تفترض أن الشاشة الأولى تعرض كل المنتجات. تعرض شاشة القالب حتى 200 منتج؛ أما التصدير فيتابع صفحات النتائج ضمن حدود التنفيذ لدى مزوّد الاستضافة.

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

## اربط مساعدًا برمجيًا بالتوثيق[​](#اربط-مساعدًا-برمجيًا-بالتوثيق "رابط مباشر إلى اربط مساعدًا برمجيًا بالتوثيق")

توفّر [صفحة ربط المساعدين](https://dzbuild.dev/ar/agents/connect) تعليمات الإعداد للمساعدين البرمجيين. يتيح خادم `@dzbuild/docs-mcp` العام للأدوات المتوافقة قراءة توثيق المطورين ومرجع الواجهة البرمجية. **لا يصل إلى حساب التاجر ولا ينفّذ إجراءات في متجرك.**

يمكنك أيضًا إعطاء المساعد [فهرس التوثيق](https://dzbuild.dev/llms.txt) و[مهارة بناء التطبيقات](https://dzbuild.dev/skills/dzbuild-apps/SKILL.md) و[وصف OpenAPI](https://dzbuild.dev/openapi/dzbuild-apps-v1.json). مثال على طلب محدد:

> اقرأ توثيق المطورين في DZBuild وقالب الكتالوج. ساعدني في بناء تطبيق لتصدير الكتالوج باستخدام `products:read` فقط. احفظ بيانات الاعتماد في مخزن أسرار على الخادم. اختبر الكتالوج الفارغ والأسماء العربية وتعدد صفحات النتائج ورفض التثبيت وسحب صلاحية الوصول.

راجع الشيفرة الناتجة وشغّل اختباراتها قبل ربطها ببيانات متجر. يوضح [دليل البناء بالذكاء الاصطناعي](https://dzbuild.dev/ar/build-with-ai) أخطاء متكررة، منها طلب صلاحيات غير ضرورية وافتراض أن رمزًا واحدًا يصل إلى عدة متاجر.

## قبل إضافة إشعارات webhook أو إجراءات تغيّر المتجر[​](#قبل-إضافة-إشعارات-webhook-أو-إجراءات-تغيّر-المتجر "رابط مباشر إلى قبل إضافة إشعارات webhook أو إجراءات تغيّر المتجر")

يعمل مثال الكتالوج دون `webhook`. لاستقبال أحداث الطلبات أو إشعارات إزالة التطبيق، سجّل رابط `webhook` وتحقق منه في منصة المطورين. لا يُقبل عنوان على `workers.dev` لاستقبال هذه الإشعارات؛ يحتاج التطبيق إلى دومين مناسب تملكه. ولا تستطيع رموز تثبيت التطبيقات إدارة واجهة التاجر `/v1/webhooks`. اتبع [دليل إشعارات التطبيقات](https://dzbuild.dev/ar/webhooks).

تحقق من توقيع إشعار `webhook` قبل معالجة محتواه، وتعامل مع الإشعارات المكررة، وتوقف عن استخدام رمز المتجر عند سحب الوصول. تحتاج طلبات `POST` و`PATCH` و`DELETE` إلى `Idempotency-Key`، ويستدعي رد `429` الانتظار وفق قيمة `Retry-After`. يشرح [دليل حدود الطلبات](https://dzbuild.dev/ar/rate-limits) هذه القواعد.

لإضافة وظائف `WhatsApp`، اقرأ [دليل الربط مع WhatsApp](https://dzbuild.com/ar/ar/blog/whatsapp-ecommerce-integration-algeria.md) قبل إضافة الإرسال. صلاحية التطبيق لا تلغي شروط الخطة أو رصيد الرسائل الذي تحتاجه الميزة.

## جهّز التطبيق لمراجعة إتاحته للتجار[​](#جهّز-التطبيق-لمراجعة-إتاحته-للتجار "رابط مباشر إلى جهّز التطبيق لمراجعة إتاحته للتجار")

قبل الإرسال، اختبر التطبيق على متجرك وجهّز شعاره وأوصافه بالإنجليزية والعربية والفرنسية وبريد الدعم وعنوان الفتح بـ `HTTPS` وعنوان إعادة التوجيه والصلاحيات المطلوبة. إذا أعددت `webhook`، يجب التحقق منه. تجد المتطلبات الدقيقة في [قائمة المراجعة](https://dzbuild.dev/ar/review-guidelines).

وضّح البيانات التي يقرأها التطبيق والتغييرات التي يجريها وطريقة الحصول على المساعدة. تطبيق تصدير الكتالوج يحتاج صلاحية قراءة المنتجات؛ إضافة صلاحيات لا تتعلق بوظيفته تصعّب تقييم الغرض منها. راجع [متطلبات الأمان](https://dzbuild.dev/ar/security) لمعرفة كيفية التعامل مع بيانات الاعتماد وبيانات التجار.

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

## أسئلة قبل أن تبدأ[​](#أسئلة-قبل-أن-تبدأ "رابط مباشر إلى أسئلة قبل أن تبدأ")

### هل تستضيف DZBuild تطبيقي؟[​](#هل-تستضيف-dzbuild-تطبيقي "رابط مباشر إلى هل تستضيف DZBuild تطبيقي؟")

تستضيف التطبيق في حساب الاستضافة أو الخادم الذي تختاره. توفّر `DZBuild` الربط بالمتجر والواجهة البرمجية. تدعم القوالب الرسمية `Cloudflare Workers`، ويضم المستودع مثالًا باستخدام `Node.js`.

### هل يمكن اختبار تطبيق مسودة على متجر زبون؟[​](#هل-يمكن-اختبار-تطبيق-مسودة-على-متجر-زبون "رابط مباشر إلى هل يمكن اختبار تطبيق مسودة على متجر زبون؟")

تثبيت المسودة متاح فقط على المتاجر التي يملكها حساب المطور. أما متجر الزبون فيحتاج إلى اعتماد التطبيق قبل أن يتمكن صاحبه من تثبيته.

### ماذا يحدث عندما يزيل التاجر التطبيق؟[​](#ماذا-يحدث-عندما-يزيل-التاجر-التطبيق "رابط مباشر إلى ماذا يحدث عندما يزيل التاجر التطبيق؟")

يُلغى رمز وصول التثبيت، وعلى التطبيق التعامل مع فقدان الوصول. يشرح قالب الكتالوج كيفية التعامل مع ردود رفض الوصول عندما لا يكون إشعار إزالة التطبيق عبر `webhook` مفعّلًا.

### من أين أبدأ؟[​](#من-أين-أبدأ "رابط مباشر إلى من أين أبدأ؟")

افتح [إنشاء تطبيق على dzbuild.dev](https://dzbuild.dev/ar/apps/new)، واختر **تصدير المنتجات**، واتبع تعليمات إعداد القالب مع [دليل البدء](https://dzbuild.dev/ar/getting-started). إذا لم يكن لديك حساب `DZBuild` بعد، استخدم [صفحة التسجيل](https://dzbuild.com/register).