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

يستدعي تطبيقك نفس واجهة `REST` التي يستعملها التجار، على العنوان `https://api.dzbuild.app/v1`. يصفها مرجعان، وتشرح هذه الصفحة ما يتغيّر عندما تستدعيها برمز تثبيت.

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

**توثيق الواجهة البرمجية على dzbuild.com** يشرح الموارد الرئيسية بمعاملاتها وردودها وأمثلتها، بثلاث لغات:

* الإنجليزية: [dzbuild.com/api-docs](https://dzbuild.com/api-docs/intro)
* العربية: [dzbuild.com/ar/api-docs](https://dzbuild.com/ar/api-docs/intro)
* الفرنسية: [dzbuild.com/fr/api-docs](https://dzbuild.com/fr/api-docs/intro)

كُتبت تلك الصفحات لمفاتيح `API` الخاصة بالتجار. مع رمز التثبيت، تسري قواعد هذه الصفحة حيث تختلف: كل الخطط تستطيع استعمال تطبيقك، والحدود مشروحة في [حدود معدّل الطلبات](https://dzbuild.dev/ar/ar/rate-limits.md)، وبعض نقاط الوصول مغلقة أمام التطبيقات.

**وصف OpenAPI للتطبيقات** ملف `JSON` واحد بصيغة `OpenAPI 3.1`. يسرد 92 عملية يستطيع رمز التثبيت استدعاءها، مع صلاحياتها ومعاملاتها وشكل ردودها. استورده في `Postman` أو `Insomnia`، أو ولّد منه الأنواع (`types`).

[تنزيل dzbuild-apps-v1.json](https://dzbuild.dev/openapi/dzbuild-apps-v1.json)

```
curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json
```

يصرّح الملف بـ `https://api.dzbuild.app` خادمًا له. ويسرد مخطط الأمان `dzOAuth` فيه كل صلاحية مع وصف بالإنجليزية.

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

يمنحك تبادل الرمز رمز وصول واحدًا لكل متجر وافق عليه التاجر (راجع [OAuth](https://dzbuild.dev/ar/ar/oauth.md)). يبدأ كل رمز بـ `dzpk_live_`. أرسله في ترويسة `Authorization` بمخطط `Bearer`:

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

  -H "Authorization: Bearer dzpk_live_xxxxxxxx"
```

الرمز هو الذي يحدّد المتجر. لا يوجد معامل للمتجر في الطلبات، فللعمل على متجر آخر للتاجر نفسه استعمل رمز ذلك المتجر من قائمة `stores` في رد التبادل. احفظ الرموز على خادمك. لا تنتهي صلاحيتها من تلقاء نفسها. يتوقف الرمز عن العمل عندما يزيل التاجر تطبيقك، أو عندما يعيد تثبيته على المتجر نفسه، فيُستبدل الرمز.

| الحالة | الرسالة                            | السبب                                    |
| ------ | ---------------------------------- | ---------------------------------------- |
| `401`  | `Missing Authorization header`     | لا توجد ترويسة `Authorization`.          |
| `401`  | `Unsupported Authorization scheme` | الترويسة لا تبدأ بـ `Bearer`.            |
| `401`  | `Invalid or revoked API key`       | الرمز خاطئ، أو أُلغي بسبب إزالة التطبيق. |

يُفحص كل رمز تثبيت أيضًا مقابل حالة تطبيقك وحالة المتجر. الطلب المرفوض يُجاب بـ `403` مع أحد رموز الخطأ هذه:

| رمز الخطأ           | المعنى                                                |
| ------------------- | ----------------------------------------------------- |
| `app_uninstalled`   | لم يعد التطبيق مثبّتًا في هذا المتجر.                 |
| `app_suspended`     | أوقفت `DZBuild` التطبيق.                              |
| `app_not_approved`  | التطبيق في وضع التجربة ولا يعمل إلا في متاجر مطوّره.  |
| `app_plan_required` | خطة المتجر أدنى من الخطة الدنيا التي حدّدتها للتطبيق. |

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

يضع الرد الناجح النتيجة في `data`. ويضع الخطأ `code` و`message` داخل `error`. يحمل كلاهما `meta.request_id`، فاذكره عند التواصل مع `DZBuild` بشأن طلب ما.

```
{

  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },

  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }

}
```

تُجيب نقاط الوصول التي تعيد قوائم بهذا الشكل:

```
{

  "data": { "items": [...], "next_cursor": "...", "has_more": true },

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

}
```

أرسل `next_cursor` من جديد في المعامل `cursor` لتحصل على الصفحة التالية، وتوقّف عندما تكون قيمة `has_more` هي `false`. ويقبل `GET /v1/orders` أيضًا `since` (الطلبات المنشأة في ذلك الوقت أو بعده) و`status` و`customer_phone`.

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

لا تحتاج `GET /v1/whoami` أي صلاحية. تخبرك بالمتجر الذي ينتمي إليه الرمز وبما يستطيع فعله. وتضيف لرمز التثبيت كائن `app`:

```
{

  "data": {

    "key_id": "dzpk_live_3c9e1a7f5b2d80",

    "store_id": 1234,

    "type": "platform",

    "rate_limit_tier": "enterprise",

    "pilot": true,

    "scopes": ["orders:read", "whatsapp:read", "whatsapp:send"],

    "app": {

      "app_id": 12,

      "client_id": "dzapp_4e1b9c07d2a86f35e0b1",

      "install_id": 57

    }

  },

  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }

}
```

| الحقل             | المعنى                                                                            |
| ----------------- | --------------------------------------------------------------------------------- |
| `store_id`        | المتجر الذي يعمل عليه هذا الرمز.                                                  |
| `scopes`          | الصلاحيات التي منحها التاجر.                                                      |
| `rate_limit_tier` | دائمًا `enterprise` لرموز التثبيت، مهما كانت خطة المتجر.                          |
| `app.app_id`      | معرّف تطبيقك.                                                                     |
| `app.client_id`   | معرّف عميل `OAuth` لتطبيقك.                                                       |
| `app.install_id`  | التثبيت في هذا المتجر. تستعمل حمولات `webhook` مثل `app.uninstalled` نفس المعرّف. |

## نقاط الوصول المغلقة أمام التطبيقات[​](#نقاط-الوصول-المغلقة-أمام-التطبيقات "رابط مباشر إلى نقاط الوصول المغلقة أمام التطبيقات")

تجيب نقاط الوصول هذه بـ `403` على رمز التثبيت، مهما كانت صلاحياته:

| نقاط الوصول                                        | الرد                            | السبب                                                                                                                   |
| -------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `/v1/keys` و`/v1/keys/{key_id}`                    | `Apps cannot use this endpoint` | مفاتيح `API` ملك للتاجر.                                                                                                |
| `/v1/webhooks` وكل ما يتفرّع منها                  | `Apps cannot use this endpoint` | يُضبط `webhook` تطبيقك مرة واحدة في منصة المطورين لكل المتاجر (راجع [Webhooks](https://dzbuild.dev/ar/ar/webhooks.md)). |
| `/v1/changes` وكل ما يتفرّع منها، بما فيها التراجع | `Apps cannot use this endpoint` | سجل التعديلات والتراجع يبقيان للتاجر.                                                                                   |

تحتاج `POST /v1/landing-pages/generate` إلى صلاحية `ai:generate`، ولا تستطيع التطبيقات طلبها لأنها تستهلك رصيد الذكاء الاصطناعي للتاجر. تُجاب بـ `403` مع `Missing scope: ai:generate`.