احراز هویت
REST API در Statnive از احراز هویت استاندارد WordPress REST استفاده میکند. میتوانید با application passwords، احراز هویت مبتنی بر cookie (برای کاربران واردشده) یا هر plugin احراز هویتی که با WordPress REST API یکپارچه میشود، احراز هویت کنید. endpointهای خواندن به دسترسی manage_options نیاز دارند؛ endpointهای جمعآوری عمومی (/hit، /event، /engagement) برای بازدیدکنندگان احراز هویت نشده باز هستند تا ردیاب بتواند ارسال کند.
URL پایه
تمام endpointها در فضای نام statnive/v1 ثبت شدهاند:
https://yoursite.com/wp-json/statnive/v1/endpointهای موجود
Reporting (نیازمند manage_options)
GET /summary
خلاصهای از معیارهای کلیدی برای یک بازه زمانی مشخص بازمیگرداند.
پارامترها:
from(string، الزامی) — تاریخ شروع در قالبYYYY-MM-DD.to(string، الزامی) — تاریخ پایان در قالبYYYY-MM-DD.
GET /sources
تفکیک منابع ترافیک بر اساس کانال را بازمیگرداند.
GET /pages
تحلیلهای در سطح صفحه را بهترتیب تعداد بازدید صفحه بازمیگرداند.
GET /pages/entry
برترین صفحات ورودی (landing) را برای یک بازه زمانی بازمیگرداند.
GET /pages/exit
برترین صفحات خروج را برای یک بازه زمانی بازمیگرداند.
GET /realtime
شمارش کنونی بازدیدکنندگان فعال و فید بازدیدهای اخیر صفحه را بازمیگرداند.
GET /utm
تفکیک تجمیعی پارامترهای UTM را برای یک بازه زمانی بازمیگرداند.
GET /events
تعداد تجمیعی رویدادهای سفارشی را برای یک بازه زمانی بازمیگرداند.
GET /events/{name}
جزئیات یک رویداد نامگذاریشده را بازمیگرداند.
GET /dimensions/{type}
تفکیک تجمیعی را برای یک بُعد واحد بازمیگرداند ({type} یکی از انواع بُعد پشتیبانیشده است، برای مثال country، device، browser، language).
درآمد WooCommerce (نسخه 1.0.0+، نیازمند manage_options)
همه endpointهای درآمد بازه تاریخ from + to (YYYY-MM-DD) را میپذیرند. endpointهای صفحهبندیشده علاوه بر آن limit (1 تا 200، پیشفرض 25؛ products پیشفرض 10، حداکثر 100) را میپذیرند.
GET /revenue/wc-status
وضعیت فعالسازی WooCommerce، وضعیت HPOS، وضعیت انتساب و پیشرفت پر کردن خودکار را بازمیگرداند.
POST /revenue/backfill
وارد کردن ناهمگام تاریخی سفارشها را از طریق Action Scheduler (یا پشتیبان WP-cron) فعال میکند.
GET /revenue/summary
5 KPI را بازمیگرداند: سفارشها، درآمد ناخالص، درآمد خالص، میانگین ارزش سفارش، مجموع و نرخ بازپرداخت، مالیات + ارسال. سطلبندی تاریخ از COALESCE(date_paid_gmt, date_created_gmt) (نسخه 1.1.0+) استفاده میکند تا تمدید اشتراکها و سفارشهای با پرداخت تأخیری در روزی که پرداخت تسویه شده است قرار بگیرند.
GET /revenue/timeseries
درآمد روزانه و تعداد سفارشها را برای بازه تاریخ بازمیگرداند.
GET /revenue/by-channel
سفارشها، درآمد و AOV را به تفکیک 8 کانال ترافیک Statnive (مستقیم، دستیارهای هوش مصنوعی، جستجوی ارگانیک، شبکههای اجتماعی، ایمیل، ارجاع، جستجوی پولی، اجتماعی پولی) بازمیگرداند.
GET /revenue/by-utm
درآمد را به تفکیک utm_source، utm_medium و utm_campaign بازمیگرداند (صفحهبندیشده).
GET /revenue/by-landing
درآمد را به تفکیک صفحه فرود ورودی بازمیگرداند (صفحهبندیشده).
GET /revenue/products
محصولات برتر را بر اساس واحد فروختهشده و درآمد بازمیگرداند، بازپرداختها اعمال میشوند و واریانتها زیر والد گروهبندی میشوند (صفحهبندیشده؛ پیشفرض limit=10).
GET /revenue/funnel
قیف 4 مرحلهای سبد خرید تا خرید را بازمیگرداند (مشاهده محصول → افزودن به سبد → شروع پرداخت → تکمیل خرید). نسخه 1.1.0+ درصد تبدیل در هر مرحله را نمایش میدهد، با درصد کل که در برابر مخرج گستردهترین مرحله محاسبه میشود.
GET /revenue/refunds
روند نرخ بازپرداخت و محصولات با بیشترین بازپرداخت را بازمیگرداند.
GET /revenue/coupons
استفاده از کوپنها را بازمیگرداند: کد، تعداد، مبلغ تخفیف و درآمد خالص پس از تخفیف (صفحهبندیشده).
مشاور Ask me! (نسخه 1.1.0+، نیازمند manage_options)
GET /advisor/questions
فهرست کامل پرسشهای Ask me! (116 پرسش × 10 دسته) را با برچسب دسته ترجمهشده، نشانگرهای طرح (free / paid)، viz_hint و آرایه دوزبانه searchable[] بازمیگرداند.
POST /advisor/answers
دستهای از شناسه پرسشها را در برابر دادههای فعلی سایت پاسخ میدهد. بدنه: { "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 را اعمال میکند.
Configuration (نیازمند manage_options)
GET /settings
تنظیمات کنونی افزونه را بازمیگرداند.
PUT /settings
تنظیمات افزونه را بهروزرسانی میکند. یک بدنه JSON از کلیدهای مجاز را میپذیرد (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
مجموعه self-test درونفرایندی را اجرا میکند.
POST /cron/run
شغلهای cron زمانبندیشده Statnive را بهصورت دستی فعال میکند.
POST /diagnostics/enable-dbip-city
پشتیبان DB-IP City را برای جستجوهای GeoIP فعال میکند.
GET /privacy-audit
خلاصهای از ممیزی حریم خصوصی بازمیگرداند.
Tracker collection (عمومی)
این endpointها توسط ردیاب همراه افزونه نوشته میشوند و عمداً باز هستند تا بازدیدکنندگان احراز هویت نشده بتوانند pageview و رویداد ارسال کنند:
POST /hit
یک hit بازدید صفحه را ثبت میکند.
POST /event
یک رویداد سفارشی را ثبت میکند.
POST /engagement
یک بهروزرسانی تعامل نشست (عمق اسکرول، زمان روی صفحه) را ثبت میکند.
محدودیت نرخ
endpointهای جمعآوری ردیاب (/hit، /event، /engagement) دارای محدودسازی در سطح برنامه در برابر کلاینتهای سوءاستفادهگر هستند. endpointهای گزارشگیری به رفتار استاندارد WordPress REST تکیه میکنند — polling خودکار سنگین را در لایه کش خود بپیچید.