الإحصائيات

النقطة 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.