المصادقة

تستخدم REST API في Statnive المصادقة القياسية لـ WordPress REST. يمكنكم المصادقة باستخدام application passwords، أو المصادقة القائمة على Cookie (للمستخدمين المسجّلين)، أو أي إضافة مصادقة تتكامل مع WordPress REST API. تتطلب نقاط النهاية للقراءة صلاحية manage_options؛ نقاط نهاية التجميع العامة (/hit، /event، /engagement) مفتوحة للزوار غير المصادق عليهم لتتمكن أداة التتبع من النشر.

عنوان URL الأساسي

تُسجَّل كل نقاط النهاية ضمن مساحة الاسم statnive/v1:

https://yoursite.com/wp-json/statnive/v1/

نقاط النهاية المتاحة

التقارير (تتطلب manage_options)

GET /summary

تُعيد ملخّصاً للمقاييس الرئيسية لنطاق زمني محدّد.

المعاملات:

• from (string، إلزامي) — تاريخ البداية بصيغة YYYY-MM-DD.
• to (string، إلزامي) — تاريخ النهاية بصيغة YYYY-MM-DD.

GET /sources

تُعيد تفصيل مصادر حركة المرور حسب القناة.

GET /pages

تُعيد التحليلات على مستوى الصفحة مرتّبة حسب عدد مشاهدات الصفحة.

GET /pages/entry

تُعيد أعلى صفحات الدخول (الهبوط) لنطاق زمني.

GET /pages/exit

تُعيد أعلى صفحات الخروج لنطاق زمني.

GET /realtime

تُعيد العدد الحالي للزوار النشطين وتغذية مشاهدات الصفحات الأخيرة.

GET /utm

تُعيد تفصيلات معاملات UTM المجمّعة لنطاق زمني.

GET /events

تُعيد عدّ الأحداث المخصصة المجمّعة لنطاق زمني.

GET /events/{name}

تُعيد تفاصيل حدث مسمّى واحد.

GET /dimensions/{type}

تُعيد التفصيلات المجمّعة لبُعد واحد ({type} هو واحد من أنواع الأبعاد المدعومة، مثل country و device و browser و language).

إيرادات WooCommerce ‏(v1.0.0+، تتطلب manage_options)

تقبل جميع نقاط نهاية الإيرادات نطاقاً زمنياً from + to (YYYY-MM-DD). تقبل نقاط النهاية ذات الصفحات إضافياً limit ‏(1–200، الافتراضي 25؛ products افتراضياً 10، أقصى 100).

GET /revenue/wc-status

تُعيد حالة تفعيل WooCommerce، وحالة HPOS، وحالة الإسناد، وتقدّم إعادة التعبئة.

POST /revenue/backfill

تُشغّل استيراداً غير متزامن للطلبات التاريخية عبر Action Scheduler (أو احتياطي WP-cron).

GET /revenue/summary

تُعيد مؤشرات الأداء الخمسة: الطلبات، الإيرادات الإجمالية، الإيرادات الصافية، متوسط قيمة الطلب، إجمالي المستردات + المعدل، الضريبة + الشحن. يستخدم التجميع الزمني COALESCE(date_paid_gmt, date_created_gmt) ‏(v1.1.0+) بحيث تهبط تجديدات الاشتراكات وطلبات الدفع المتأخر في يوم تسوية الدفع.

GET /revenue/timeseries

تُعيد الإيرادات اليومية وأعداد الطلبات للنطاق الزمني.

GET /revenue/by-channel

تُعيد الطلبات والإيرادات و AOV مفصَّلة حسب قنوات Statnive الثماني للزيارات (مباشر، AI Assistants، البحث العضوي، وسائل التواصل الاجتماعي، البريد الإلكتروني، الإحالة، البحث المدفوع، الترويج المدفوع).

GET /revenue/by-utm

تُعيد الإيرادات مفصَّلة حسب utm_source و utm_medium و utm_campaign (بصفحات).

GET /revenue/by-landing

تُعيد الإيرادات مفصَّلة حسب صفحة الهبوط الأولى (بصفحات).

GET /revenue/products

تُعيد أعلى المنتجات حسب الوحدات المباعة والإيرادات، مع تطبيق المستردات، وتجميع المتغيرات تحت المنتج الأصل (بصفحات؛ الافتراضي limit=10).

GET /revenue/funnel

تُعيد مسار التحويل من السلة إلى الشراء من 4 مراحل (مشاهدة المنتج ← الإضافة إلى السلة ← بدء الدفع ← إتمام الشراء). تُظهر v1.1.0+ نسبة التحويل لكل خطوة، مع احتساب «النسبة الإجمالية» مقابل مقام أوسع خطوة.

GET /revenue/refunds

تُعيد اتجاه معدل الاسترداد وأعلى المنتجات المُسترَدة.

GET /revenue/coupons

تُعيد استخدامات الكوبونات: الرمز، العدد، مبلغ الخصم، والإيرادات الصافية بعد الخصم (بصفحات).

مستشار Ask me! ‏(v1.1.0+، تتطلب manage_options)

GET /advisor/questions

تُعيد قائمة أسئلة Ask me! الكاملة (116 سؤالاً × 10 فئات) مع تسميات الفئات المترجمة، وعلامات الخطة (free / paid)، و viz_hint، ومصفوفة searchable[] ثنائية اللغة.

POST /advisor/answers

تحلّ دفعة من معرّفات الأسئلة مقابل بيانات الموقع الحالي. Body: ‏{ "ids": ["q2","q41",…], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }. تُعيد مغلَّف إجابة واحد لكل معرّف (حالة ok مع حمولة viz، أو coming_soon، أو error).

GET /advisor/preferences

تُعيد معرّفات الأسئلة المثبَّتة للمستخدم الحالي من wp_usermeta (5 تثبيتات افتراضية إذا لم تُضبط: q2, q41, q23, q72, q81).

PUT /advisor/preferences

تُحدّث معرّفات الأسئلة المثبَّتة للمستخدم الحالي. تُهمل المعرّفات غير المعروفة وتُطبّق سقف MAX_PINS = 10.

التهيئة (تتطلب manage_options)

GET /settings

تُعيد إعدادات الإضافة الحالية.

PUT /settings

تُحدّث إعدادات الإضافة. تقبل JSON body من المفاتيح المسموح بها (tracking_enabled، respect_dnt، respect_gpc، consent_mode، retention_days، retention_mode، excluded_ips، excluded_roles، geoip_enabled، maxmind_license_key).

GET /diagnostics

تُعيد لقطة لصحة الإضافة (جداول DB، حالة GeoIP، جدول cron، البيئة).

POST /self-test

تشغّل مجموعة الاختبار الذاتي داخل العملية.

POST /cron/run

تُشغّل يدوياً مهام cron المجدولة لـ Statnive.

POST /diagnostics/enable-dbip-city

تفعّل احتياطي DB-IP City لاستعلامات GeoIP.

GET /privacy-audit

تُعيد ملخّص تدقيق الخصوصية.

تجميع أداة التتبع (عامة)

تُكتب إلى نقاط النهاية هذه أداة التتبع المضمّنة وهي مفتوحة عمداً ليتمكن الزوار غير المصادق عليهم من نشر مشاهدات الصفحات والأحداث:

POST /hit

تسجّل زيارة مشاهدة صفحة.

POST /event

تسجّل حدثاً مخصصاً.

POST /engagement

تسجّل تحديث تفاعل الجلسة (عمق التمرير، الوقت في الصفحة).

تحديد المعدّل

نقاط نهاية تجميع أداة التتبع (/hit، /event، /engagement) تحمل تحكّماً على مستوى التطبيق ضد العملاء المسيئين. تعتمد نقاط نهاية التقارير على سلوك WordPress REST القياسي — غلّفوا الاستفسارات الآلية الثقيلة في طبقة تخزين مؤقت خاصة بكم.