# واجهة DZBuild البرمجية صارت live — ابنِ تكاملات مخصصة لمتجرك

اليوم نُطلق **DZBuild API v1** للعموم. مفتاح، توثيق، أمثلة، كل شيء في انتظارك.

## ما يمكنك بناؤه[​](#ما-يمكنك-بناؤه "رابط مباشر إلى ما يمكنك بناؤه")

* **واجهات headless** — متجر React/Vue/Next.js يتحدث بالكامل عبر API.
* **أتمتة back-office** — مزامنة طلبات لـ CRM، استيراد منتجات بالجملة، تأكيد بالجملة.
* **تطبيقات جوال** — iOS / Android بإدارة طلبات وإشعارات.
* **تكاملات شركاء** — ربط Zapier، n8n، Make، أي منصة أتمتة.
* **منصات Reseller** — وكالات تدير عشرات متاجر العملاء من back-office واحد.

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

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

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

### المصادقة[​](#المصادقة "رابط مباشر إلى المصادقة")

```
Authorization: Bearer dzpk_live_<key_id>.<secret>
```

### أنشئ أول مفتاح[​](#أنشئ-أول-مفتاح "رابط مباشر إلى أنشئ أول مفتاح")

من لوحة التحكم: الإعدادات ← `API` عبر الصفحة [`/dashboard/api`](https://dzbuild.com/dashboard/api) — متاحة لمالك المتجر على خطة Enterprise، والسر يظهر مرة واحدة فقط عند الإنشاء فاحفظه.

## ما في v1[​](#ما-في-v1 "رابط مباشر إلى ما في v1")

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

* `/v1/store` — بيانات المتجر
* `/v1/products` — CRUD كامل للمنتجات
* `/v1/orders` — إنشاء، قراءة، انتقال حالة، إلغاء
* `/v1/customers` — قراءة العملاء وطلباتهم
* `/v1/landing-pages` — CRUD لصفحات الهبوط
* `/v1/keys`, `/v1/usage`, `/v1/quotas` — الإدارة

### نقاط المفتاح العام[​](#نقاط-المفتاح-العام "رابط مباشر إلى نقاط المفتاح العام")

* `/v1/signups` — تتبع اشتراكات عالي الحجم بـ HMAC
* `/v1/events` — أحداث عامة

### Webhooks[​](#webhooks "رابط مباشر إلى Webhooks")

* 10 أحداث: `order.*`, `payment.received`, `signup.counted`, `event.recorded`, `product.stock_low`, `webhook.test`
* التواقيع HMAC-SHA256، مع إعادة محاولة تلقائية عند فشل التسليم.

### مثال: إنشاء منتج[​](#مثال-إنشاء-منتج "رابط مباشر إلى مثال: إنشاء منتج")

```
curl -X POST 'https://api.dzbuild.app/v1/products' \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{ "name":"T-shirt", "price":1500, "status":"active" }'
```

### مثال: سرد الطلبات[​](#مثال-سرد-الطلبات "رابط مباشر إلى مثال: سرد الطلبات")

```
curl 'https://api.dzbuild.app/v1/orders?status=pending&limit=20' \

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

## كيف تتصرّف الطلبات[​](#كيف-تتصرّف-الطلبات "رابط مباشر إلى كيف تتصرّف الطلبات")

الـ API مخدوم من شبكة عالمية، فزمن الاستجابة يبقى منخفضًا من أي مكان تنادي منه:

* الطلب بلا مفتاح صالح (أو بلا توقيع HMAC صالح للمفتاح العام) يُرفض بـ `401` قبل أي معالجة.
* حد معدل لكل مفتاح؛ تجاوزه يُعيد `429` مع `retry_after`.
* قراءات `GET` الآمنة قد تُخدَّم من الذاكرة المؤقتة حتى 30 ثانية.
* النقاط عالية الحجم (`/v1/signups`, `/v1/events`) تُعيد `202` فورًا وتُكمل المعالجة لاحقًا.

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

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

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

| الخطة         | طلبات/دقيقة | طلبات/شهر |
| ------------- | ----------- | --------- |
| Free          | 30          | 10K       |
| Pro           | 300         | 500K      |
| غير محدود API | 1200        | 5M        |
| Enterprise    | 6000+       | بلا حدود  |

## Idempotency[​](#idempotency "رابط مباشر إلى Idempotency")

كل POST/PATCH/DELETE يتطلب `Idempotency-Key`. الإعادة بنفس المفتاح خلال 24 ساعة = نفس الاستجابة.

## التصفّح[​](#التصفّح "رابط مباشر إلى التصفّح")

ترقيم بمؤشّر — `cursor` + `next_cursor` + `has_more`.

## SDKs والمكتبات[​](#sdks-والمكتبات "رابط مباشر إلى SDKs والمكتبات")

* مرجع TypeScript / Node.js (قادم من DZBuild)
* مكتبة Python (community)
* مكتبة PHP (community)

## البدء[​](#البدء "رابط مباشر إلى البدء")

[توثيق API الكامل](https://dzbuild.com/ar/ar/api-docs/intro.md)

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

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

```
for row in csv.DictReader(f):

    requests.post('https://api.dzbuild.app/v1/products', json=row, headers={...})
```

### معالج Webhook[​](#معالج-webhook "رابط مباشر إلى معالج Webhook")

```
app.post('/webhook', verifySignature, (req, res) => {

  if (req.body.event === 'order.created') notifyCRM(req.body.data);

  res.status(200).end();

});
```

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

* توثيق: dzbuild.com/api-docs
* بريد: <support@dzbuild.com>
* تيليجرام: t.me/dzbuild

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

API مشمول في خطط Pro فما فوق. في فترة pilot (الآن) لا يحاسَب الاستهلاك. التسعير النهائي يُعلن عند الخروج من pilot.

## التالي[​](#التالي "رابط مباشر إلى التالي")

* v1.1: سعر الشحن من `GET /v1/store`، تركيبات المنتج، روابط رفع صور presigned، استرداد الطلبات.
* v1.2: SDK رسمية بـ Node و Python.

## ابنِ الآن[​](#ابنِ-الآن "رابط مباشر إلى ابنِ الآن")

أنشئ مفتاحك من اللوحة، اقرأ [التوثيق](https://dzbuild.com/ar/ar/api-docs/intro.md)، وابدأ.