# واجهة DZBuild البرمجية

أنشئ تطبيقاتك لمتاجر DZBuild

أنشئ تطبيقات يستطيع التجار تثبيتها على متاجرهم في DZBuild. زر [بوابة المطورين dzbuild.dev](https://dzbuild.dev/ar/) للاطلاع على القوالب الرسمية والأدلة، أو [ابدأ إنشاء تطبيق](https://dzbuild.dev/ar/apps/new).

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

تتيح لك واجهة DZBuild البرمجية إدارة متجرك برمجيًا: المنتجات، الطلبات، العملاء، صفحات الهبوط، بالإضافة إلى **متتبع اشتراكات** عالي الحجم للتجار الذين يدمجون DZBuild في منصاتهم الخاصة.

**عنوان القاعدة:** `https://api.dzbuild.app/v1` — وهو عنوان القاعدة العام الوحيد المدعوم. **الإصدار:** مستقر على `v1`. أي تغييرات جذرية تتطلب بادئة مسار جديدة. **التنسيق:** JSON دخولًا وخروجًا، بترميز UTF-8. **المصادقة:** انظر [المصادقة](https://dzbuild.com/ar/ar/api-docs/authentication.md). **مفاتيح API الشخصية:** تحتاج إلى متجر باشتراك سارٍ في خطة المؤسسات. لا ينطبق هذا الشرط على رموز تثبيت التطبيقات، التي تخضع لشروط الوصول المرتبطة أعلاه. **الحالة:** تجريبي (Pilot). ينشئ مالك متجر على خطة Enterprise سارية مفاتيحه الشخصية من لوحة التحكم عبر **الإعدادات ← واجهة API** (`/dashboard/api`). يُسجَّل المفتاح الجديد في البرنامج التجريبي تلقائيًا ويعمل فورًا، فلا حاجة إلى طلب أي شيء من الدعم.

وجّه تكاملك إلى `api.dzbuild.app` ولا شيء غيره

العنوان `https://dzbuild.com/api/v1` هو مجرد اسم بديل داخلي، وليس هدفًا للتكامل. على هذا المضيف: المساران `/v1/signups` و`/v1/events` غير موجودين (`404`)، ونداءات المفتاح العام (`DZ-Public`) تُرفض بـ`401`. أما إعادة التشغيل idempotent وحد المعدل لكل متجر فيسريان على المضيفين معًا.

## بداية سريعة[​](#بداية-سريعة "رابط مباشر إلى بداية سريعة")

```
curl https://api.dzbuild.app/v1/ping
```

الاستجابة:

```
{ "data": { "pong": true, "time": "2026-04-30T20:15:59.836Z", "edge": true },

  "meta": { "request_id": "...", "api_version": "v1", "edge": true } }
```

طلب موثَّق:

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

  -H "Authorization: Bearer <your_key_id>.<your_key_secret>"
```

الاستجابة:

```
{ "data": { "key_id": "dzpk_live_xxxxxxxxxxxxxx", "store_id": 10, "type": "platform",

            "rate_limit_tier": "enterprise", "pilot": true,

            "scopes": ["store:read", "store:write", "products:read", "products:write",

                       "orders:read", "orders:write", "customers:read", "landing_pages:read",

                       "landing_pages:write", "promos:read", "promos:write", "pixels:read",

                       "pixels:write", "shipping:read", "shipping:write", "webhooks:read",

                       "webhooks:write", "usage:read", "analytics:read", "whatsapp:read",

                       "whatsapp:send"] },

  "meta": { "request_id": "...", "api_version": "v1" } }
```

يسرد `scopes` ما يحق لهذا المفتاح استدعاؤه: نقطة النهاية التي تحتاج إلى صلاحية غائبة عن القائمة تُرجع `403` مع `Missing scope:` متبوعة باسم الصلاحية. ومع رمز تطبيق مثبّت تحمل استجابة `whoami` أيضًا `app`، مع `app_id` و`client_id` و`install_id` الخاصة به.

## بنية الاستجابة[​](#بنية-الاستجابة "رابط مباشر إلى بنية الاستجابة")

كل الاستجابات تتبع الشكل ذاته:

**نجاح**

```
{ "data": ..., "meta": { "request_id": "...", "api_version": "v1" } }
```

**خطأ**

```
{ "error": { "code": "rate_limited", "message": "...", "retry_after": 12 },

  "meta": { "request_id": "...", "api_version": "v1" } }
```

## رؤوس الاستجابة[​](#رؤوس-الاستجابة "رابط مباشر إلى رؤوس الاستجابة")

| الرأس                | متى                                                                              | المعنى                                                                                                                                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Request-Id`       | في كل استجابة                                                                    | القيمة نفسها الموجودة في `meta.request_id`، إلا في استجابة كتابة مُعادة (`Idempotency-Replay: 1`): محتواها هو المحتوى المخزَّن، فيبقى فيه `meta.request_id` الخاص بالنداء الأول. أرسل رأس `X-Request-Id` خاصًا بك وسنعيده كما هو، لتتطابق سجلاتك مع سجلاتنا. |
| `X-Api-Version`      | في معظم الاستجابات                                                               | دائمًا `v1`.                                                                                                                                                                                                                                                 |
| `X-Cache`            | في `GET /v1/products` و`GET /v1/landing-pages` و`GET /v1/store` ومساراته الفرعية | دائمًا `MISS`: هذه القراءات تُخدَم حديثًا.                                                                                                                                                                                                                   |
| `Idempotency-Replay` | في عمليات الكتابة المُعادة                                                       | القيمة `1` تعني أن هذه هي الاستجابة المخزَّنة لنداء سابق بنفس `Idempotency-Key` — ولم يحدث أي أثر جانبي جديد. انظر [Idempotency](https://dzbuild.com/ar/ar/api-docs/idempotency.md).                                                                         |

## معلومات مفيدة[​](#معلومات-مفيدة "رابط مباشر إلى معلومات مفيدة")

* يُتحقَّق من مفتاحك في كل طلب — سواء كان Bearer token أو توقيع HMAC لمفتاح عام.
* الحد لكل دقيقة يُطبَّق **لكل متجر** — جميع مفاتيح المتجر تتشارك ميزانية واحدة — ضمن نافذة ثابتة مدتها 60 ثانية (يُصفَّر العدّاد مع كل دقيقة من ساعة الحائط). والتطبيق تقريبي عند الدفعات الكبيرة، لذا تعامل مع `429` بحذر بدل ضبط وتيرتك تمامًا على الحد. وهو يخصّ نداءات الواجهة البرمجية وحدها — فواجهة متجر التاجر وصفحة إتمام الطلب ولوحة التحكم لا تستهلكه أبدًا. انظر [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).
* كل طلب `GET` يُخدَم حديثًا من المنصة: لا توجد ذاكرة قراءة مؤقتة على حافة `api.dzbuild.app`، فتُرجع `GET /v1/products` و`GET /v1/landing-pages` و`GET /v1/store` وكل طلب `GET` تحته القيمَ الحالية في كل نداء. خزّن من جهتك عندما تقرأ بحجم كبير.
* الكتابات عالية الحجم (`/v1/signups`, `/v1/events`) تُقبل بشكل غير متزامن وتُرجع `202 Accepted` فورًا — نداؤك لا ينتظر انتهاء المعالجة.