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

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

قبل أن تبدأ

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

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

GET /v1/analytics

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

المصادقة: مفتاح منصة بصلاحية 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

الإجابة على 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`	استُنفدت حصة الطلبات الشهرية للمتجر. راجع حدود المعدل.
403	`forbidden`	`Missing scope: analytics:read`، أو مفتاح شخصي متجره ليس على خطة Enterprise سارية (`API access requires an active Enterprise plan`).
429	`rate_limited`	تجاوز حد الطلبات في الدقيقة للمتجر، وهو مشترك بين كل مفاتيحه، أو الحد الخاص بكل تثبيت لرمز التطبيق المثبَّت. انتظر مدة `Retry-After`. راجع حدود المعدل.

حدود معروفة

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

المقالات ذات الصلة

الإحصائيات والتحليلات