# الإحصائيات

النقطة `GET /v1/analytics` تُرجع الأرقام التي تعرضها الصفحة الرئيسية للوحة التحكم لفترة معيّنة: عشرة مؤشرات أداء (`KPI`)، لكل منها قيمته في فترة مقارنة ونسبة التغيّر، وثماني سلاسل للرسوم البيانية. استعملها لتقارير عملائك أو للتصدير إلى أداة `BI` بدل إعادة حساب الأرقام من `GET /v1/orders`. الواجهة البرمجية ولوحة التحكم تتقاسمان التعريفات نفسها والذاكرة المؤقتة نفسها، فتعرضان الأرقام نفسها للفترة نفسها. معنى كل رقم بالنسبة للتاجر مشروح في صفحة [الإحصائيات والتحليلات](https://dzbuild.com/ar/ar/docs/marketing/analytics.md) من توثيق التاجر.

تحسب الواجهة البرمجية دائماً كل الزيارات: صفحات المتجر وصفحات الهبوط معاً. فلتر الزيارات في لوحة التحكم (صفحات الهبوط وحدها، أو المتجر وحده) لا مقابل له هنا.

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

* يحتاج المفتاح صلاحية `analytics:read`. المفاتيح المُنشأة من لوحة التحكم (**الإعدادات ← واجهة API**، `/dashboard/api`) تحملها منذ الإصدار `v1.7`. **الصلاحيات تُجمَّد لحظة إنشاء المفتاح**، فالمفتاح الأقدم يُرجع `403 forbidden` مع الرسالة `Missing scope: analytics:read`: أنشئ مفتاحاً جديداً من لوحة التحكم. والمفتاح المُنشأ عبر `POST /v1/keys` لا يحصل إلا على الصلاحيات التي يملكها المفتاح الذي أنشأه.
* المفاتيح الشخصية تحتاج متجراً على خطة Enterprise سارية. رمز التطبيق المثبَّت لا يرتبط بخطة Enterprise، لكنه يحتاج `analytics:read` ضمن الصلاحيات التي وافق عليها التاجر. انظر [المقدمة](https://dzbuild.com/ar/ar/api-docs/intro.md).
* الإيرادات والربح ومتوسط قيمة الطلب، وقيم `revenue` داخل الرسوم البيانية، لا تُرسل إلا إذا كان المفتاح تابعاً لحساب مالك المتجر. وإلا تغيب هذه الحقول من الإجابة: فهي لا تُضبط على `0` ولا على `null`.

| النطاق           | الوصف                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `analytics:read` | قراءة إحصائيات المتجر ومؤشرات الأداء. مُضمَّنة في مفاتيح التاجر المُنشأة ابتداءً من `v1.7`؛ المفتاح الأقدم يحتاج مفتاحاً جديداً. |

## `GET /v1/analytics`[​](#get-v1analytics "رابط مباشر إلى get-v1analytics")

التقرير الخاص بفترة واحدة.

**المصادقة:** مفتاح منصة بصلاحية `analytics:read`.

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

| المعامل | النوع        | الافتراضي    | ملاحظات                                                                                                                                   |
| ------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `range` | string       | `this_month` | `today` أو `yesterday` أو `7d` أو `30d` أو `this_month` أو `last_month` أو `this_year` أو `custom`. أي قيمة أخرى تُرجع `400 bad_request`. |
| `from`  | `YYYY-MM-DD` | لا شيء       | اليوم الأول. إلزامي مع `range=custom`، ويُتجاهل في غير ذلك.                                                                               |
| `to`    | `YYYY-MM-DD` | لا شيء       | اليوم الأخير. إلزامي مع `range=custom`، ويُتجاهل في غير ذلك. لا يكون قبل `from` أبداً، ولا بعده بأكثر من 365 يوماً.                       |

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

| `range`      | الفترة                                    | تُقارَن بـ                             | `group_by`                 |
| ------------ | ----------------------------------------- | -------------------------------------- | -------------------------- |
| `today`      | اليوم                                     | أمس                                    | `hour`                     |
| `yesterday`  | أمس                                       | اليوم الذي قبله                        | `hour`                     |
| `7d`         | اليوم و6 أيام قبله                        | الأيام الـ7 التي قبلها                 | `day`                      |
| `30d`        | اليوم و29 يوماً قبله                      | الأيام الـ30 التي قبلها                | `day`                      |
| `this_month` | من اليوم 1 إلى آخر يوم في الشهر الجاري    | الشهر السابق كاملاً                    | `day`                      |
| `last_month` | الشهر السابق كاملاً                       | الشهر الذي قبله                        | `day`                      |
| `this_year`  | من 1 جانفي إلى 31 ديسمبر من السنة الجارية | السنة السابقة كاملة                    | `month`                    |
| `custom`     | من `from` إلى `to`، واليومان محسوبان      | العدد نفسه من الأيام قبل `from` مباشرة | `hour` أو `day` أو `month` |

في `custom` تكون قيمة `group_by` هي `hour` إذا كان `to` هو `from` نفسه أو اليوم الذي يليه، و`day` إذا كان `to` بعد `from` بـ90 يوماً على الأكثر، و`month` فيما زاد على ذلك. الفترتان `this_month` و`this_year` تمتدان إلى نهاية الشهر أو السنة، فهما تقارنان الأيام المنقضية حتى الآن بشهر سابق كامل أو بسنة سابقة كاملة.

يُحفظ التقرير في الذاكرة المؤقتة 120 ثانية لكل متجر وفترة، ولوحة التحكم تقرأ من الذاكرة المؤقتة نفسها. قد يُرجع النداء أرقاماً عمرها دقيقتان على الأكثر، والنداءات خلال تلك المدة تحصل على الأرقام نفسها.

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

```
curl 'https://api.dzbuild.app/v1/analytics?range=7d' \

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

فترة مخصصة:

```
curl 'https://api.dzbuild.app/v1/analytics?range=custom&from=2026-09-01&to=2026-09-30' \

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

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

الإجابة على `range=7d` يوم 6 أكتوبر 2026، لمفتاح أنشأه مالك المتجر. السلاسل الزمنية والقوائم مقطوعة بعد أول عناصرها.

```
{

  "data": {

    "period": {

      "from": "2026-09-30 00:00:00",

      "to": "2026-10-06 23:59:59",

      "prev_from": "2026-09-23 00:00:00",

      "prev_to": "2026-09-29 23:59:59",

      "label": "7d",

      "group_by": "day"

    },

    "kpis": {

      "total_orders": { "value": 48, "change": 20, "previous": 40 },

      "delivered_orders": { "value": 31, "change": 7, "previous": 29 },

      "cancelled_orders": { "value": 6, "change": -25, "previous": 8 },

      "total_revenue": { "value": 186000, "change": 8, "previous": 172000 },

      "total_profit": { "value": 61500, "change": 6, "previous": 58000 },

      "avg_order_value": { "value": 4350, "change": -1, "previous": 4400 },

      "total_visitors": { "value": 1520, "change": 17, "previous": 1300 },

      "page_views": { "value": 4810, "change": 17, "previous": 4100 },

      "conversion_rate": { "value": 3.2, "change": 3, "previous": 3.1 },

      "new_customers": { "value": 41, "change": 17, "previous": 35 }

    },

    "charts": {

      "revenue_over_time": [

        { "label": "09/30", "orders": 7, "revenue": 24500 },

        { "label": "10/01", "orders": 5, "revenue": 18000 }

      ],

      "orders_by_hour": [

        { "hour": "00:00", "orders": 0, "impressions": 35 },

        { "hour": "01:00", "orders": 1, "impressions": 22 }

      ],

      "orders_by_status": {

        "pending": 5,

        "confirmed": 4,

        "processing": 2,

        "shipped": 9,

        "delivered": 20,

        "cancelled": 6,

        "returned": 2

      },

      "top_products": [

        {

          "id": 12,

          "name": "Classic watch",

          "image": "https://cdn.dzbuild.app/uploads/products/123/123_1700000000_example.webp",

          "qty_sold": 14,

          "revenue": 49000,

          "views": 380

        }

      ],

      "visitors_over_time": [

        { "label": "09/30", "page_views": 690, "unique_visitors": 215, "orders": 7 },

        { "label": "10/01", "page_views": 702, "unique_visitors": 230, "orders": 5 }

      ],

      "devices": {

        "desktop": { "count": 510, "percent": 11 },

        "mobile": { "count": 4180, "percent": 87 },

        "tablet": { "count": 120, "percent": 2 }

      },

      "traffic_sources": [

        { "source": "facebook", "count": 2900, "percent": 60 },

        { "source": "direct", "count": 1210, "percent": 25 },

        { "source": "tiktok", "count": 700, "percent": 15 }

      ],

      "top_wilayas": [

        { "wilaya": "الجزائر", "orders": 9, "revenue": 41000 },

        { "wilaya": "وهران", "orders": 6, "revenue": 27500 }

      ]

    }

  }

}
```

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

| الحقل                  | المعنى                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `from`، `to`           | بداية الفترة ونهايتها، بصيغة `YYYY-MM-DD HH:MM:SS` وبتوقيت الجزائر.                          |
| `prev_from`، `prev_to` | بداية فترة المقارنة ونهايتها.                                                                |
| `label`                | قيمة `range` التي طلبتها.                                                                    |
| `group_by`             | حجم الوحدة الزمنية في `revenue_over_time` و`visitors_over_time`: `hour` أو `day` أو `month`. |

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

لكل مؤشر ثلاثة أرقام: `value` للفترة، و`previous` لفترة المقارنة، و`change` وهي نسبة التغيّر المئوية مقرَّبة إلى عدد صحيح. إذا كانت `previous` تساوي `0` أو أقل، تكون `change` مساوية لـ`100` إذا كانت `value` أكبر من `0`، وتساوي `0` في غير ذلك. المبالغ مقرَّبة إلى أعداد صحيحة.

| المؤشر             | ما يحسبه                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `total_orders`     | الطلبات المُنشأة في الفترة، أياً كانت حالتها.                                                                             |
| `delivered_orders` | الطلبات المُسلَّمة في الفترة، محسوبة في يوم تسليمها.                                                                      |
| `cancelled_orders` | الطلبات المُنشأة في الفترة والملغاة الآن.                                                                                 |
| `total_revenue`    | للمالك فقط. المجموع الفرعي ناقص الخصم للطلبات المُسلَّمة في الفترة. الشحن ورسوم الدفع غير محسوبة.                         |
| `total_profit`     | للمالك فقط. `total_revenue` ناقص الكمية × سعر التكلفة لعناصر تلك الطلبات. المنتج الذي لا سعر تكلفة له تُحسب تكلفته صفراً. |
| `avg_order_value`  | للمالك فقط. متوسط إجمالي الطلب للطلبات المُنشأة في الفترة، دون الطلبات الملغاة والمرتجعة.                                 |
| `total_visitors`   | الزوار الفريدون في الفترة، صفحات المتجر وصفحات الهبوط معاً.                                                               |
| `page_views`       | مشاهدات الصفحات في الفترة، صفحات المتجر وصفحات الهبوط معاً.                                                               |
| `conversion_rate`  | `total_orders` ÷ `total_visitors` × 100، برقم واحد بعد الفاصلة. `0` إذا لم يكن هناك زوار.                                 |
| `new_customers`    | سجلات الزبائن المُنشأة في الفترة.                                                                                         |

هذه المؤشرات تأتي من مجموعات طلبات مختلفة، فلا تتطابق حسابياً: `total_revenue` ÷ `total_orders` لا يساوي `avg_order_value`.

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

| الرسم                | المحتوى                                                                                                                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `revenue_over_time`  | عنصر لكل وحدة زمنية: `label`، و`orders` المُنشأة في تلك الوحدة، وللمالك فقط `revenue`، أي مجموع إجماليات تلك الطلبات التي حالتها الآن مُسلَّمة. وهو ليس `total_revenue` الذي يُحسب بيوم التسليم ولا يدخل فيه الشحن.                                                                   |
| `orders_by_hour`     | 24 عنصراً دائماً، من `00:00` إلى `23:00`: الطلبات المُنشأة ومشاهدات الصفحات (`impressions`) في تلك الساعة من اليوم، على طول الفترة كلها.                                                                                                                                              |
| `orders_by_status`   | الطلبات المُنشأة في الفترة حسب حالتها الحالية: `pending` و`confirmed` و`processing` و`shipped` و`delivered` و`cancelled` و`returned`.                                                                                                                                                 |
| `top_products`       | حتى 10 منتجات حسب الكمية المباعة في الطلبات المُنشأة في الفترة، دون الطلبات الملغاة والمرتجعة. لكل منتج `id` و`name` و`image` (رابط الصورة الرئيسية أو `null`) و`qty_sold` و`views` (الزوار الفريدون على المنتج في الفترة)، وللمالك فقط `revenue` (الكمية × السعر المسجَّل في الطلب). |
| `visitors_over_time` | عنصر لكل وحدة زمنية: `label` و`page_views` و`unique_visitors` و`orders`. الزائر الذي يعود في يوم آخر يُحسب في الوحدتين، لذا قد يتجاوز مجموع قيم `unique_visitors` قيمة `total_visitors`.                                                                                              |
| `devices`            | مشاهدات الصفحات حسب الجهاز: المفاتيح `desktop` و`mobile` و`tablet`، لكل منها `count` و`percent`. الجهاز الذي لا مشاهدات له لا مفتاح له، ويكون الحقل مصفوفة فارغة `[]` إذا لم تكن في الفترة أي زيارة.                                                                                  |
| `traffic_sources`    | حتى 6 مصادر حسب مشاهدات الصفحات، الأكثر أولاً، لكل منها `source` و`count` و`percent`. وقيمة `percent` هي الحصة بين المصادر المذكورة فقط.                                                                                                                                              |
| `top_wilayas`        | حتى 10 ولايات حسب عدد الطلبات المُنشأة في الفترة، بكل الحالات: `wilaya` (الاسم بالعربية، و`غير محدد` للطلبات التي لا ولاية لها) و`orders`، وللمالك فقط `revenue`، أي مجموع إجماليات تلك الطلبات أياً كانت حالتها.                                                                     |

تتبع التسميات قيمة `group_by`: من `00:00` إلى `23:00` في `hour` (24 عنصراً؛ وفترة `custom` من يومين تجمع اليومين في الساعات نفسها)، و`MM/DD` في `day`، واسم الشهر بالإنجليزية مع السنة في `month`، مثل `Sep 2026`. الأيام التي بعد اليوم والأشهر التي بعد الشهر الجاري لا تظهر.

تسجّل المنصة `source` بإحدى القيم `direct` أو `facebook` أو `instagram` أو `tiktok` أو `google` أو `youtube` أو `twitter` أو `snapchat` أو `telegram` أو `other`. الزيارة التي يحمل رابطها `utm_source` تُصنَّف حسب هذا الوسم (`fb` تُحسب `facebook`، و`ig` تُحسب `instagram`، و`x` تُحسب `twitter`، وأي وسم خارج القائمة يُحسب `other`)؛ والزيارة بدونه تُصنَّف حسب الموقع الذي جاءت منه.

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

| HTTP | الرمز            | السبب                                                                                                                                                                                                                   |
| ---- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`    | `range` ليست إحدى القيم الثماني (`Invalid range. Allowed: ...`)، أو فترة `custom` ينقصها `from` أو `to` أو ليسا بصيغة `YYYY-MM-DD`، أو يكون فيها `to` قبل `from` أو بعده بأكثر من 365 يوماً (`Invalid date range ...`). |
| 401  | `unauthorized`   | مفتاح خاطئ أو مفقود.                                                                                                                                                                                                    |
| 402  | `quota_exceeded` | استُنفدت حصة الطلبات الشهرية للمتجر. راجع [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).                                                                                                             |
| 403  | `forbidden`      | `Missing scope: analytics:read`، أو مفتاح شخصي متجره ليس على خطة Enterprise سارية (`API access requires an active Enterprise plan`).                                                                                    |
| 429  | `rate_limited`   | تجاوز حد الطلبات في الدقيقة للمتجر، وهو مشترك بين كل مفاتيحه، أو الحد الخاص بكل تثبيت لرمز التطبيق المثبَّت. انتظر مدة `Retry-After`. راجع [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).            |

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

* **نهايات الأشهر.** إذا كان رقم اليوم الحالي غير موجود في الشهر السابق، كما في 31 أكتوبر، فإن `range=last_month` تُرجع الشهر الجاري، و`range=this_month` تُقارَن بالشهر الجاري نفسه. وتُقارَن `last_month` أيضاً بنفسها إذا كان اليوم غير موجود قبل شهرين، كما في 30 أفريل. في تلك الأيام، اطلب التواريخ التي تحتاجها عبر `range=custom`.