身份验证

Statnive 的 REST API 使用标准的 WordPress REST 身份验证。您可以使用应用程序密码、基于 Cookie 的身份验证（针对已登录用户），或任何与 WordPress REST API 集成的身份验证插件进行认证。读取类端点要求 manage_options 权限；公开的采集端点（/hit、/event、/engagement）对未认证访客开放，以便跟踪器进行 POST。

基础 URL

所有端点均注册于 statnive/v1 命名空间下：

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

可用端点

报表（要求 manage_options）

GET /summary

返回指定日期范围内关键指标的摘要。

参数：

  • from（字符串，必填）—— 起始日期，格式为 YYYY-MM-DD。
  • to（字符串，必填）—— 结束日期，格式为 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

返回 5 项 KPI：订单数、总收入、净收入、平均订单金额、退款总额 + 退款率、税费 + 运费。日期分桶使用 COALESCE(date_paid_gmt, date_created_gmt)（v1.1.0+），以便订阅续费和延迟支付订单落在付款实际清算的当天。

GET /revenue/timeseries

返回指定日期范围内每日的收入和订单数。

GET /revenue/by-channel

按 Statnive 的 8 个流量渠道（直接访问、AI 助手、自然搜索、社交媒体、邮件、引荐来源、付费搜索、付费社交）返回订单数、收入和平均订单金额细分。

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

针对当前站点数据批量解析一批问题 ID。请求体：{ "ids": ["q2","q41",…], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }。每个 ID 返回一个答案信封（状态 ok 附 viz 数据、coming_soon 或 error）。

GET /advisor/preferences

返回当前用户在 wp_usermeta 中钉选的问题 ID（如果未设置则使用默认的 5 个钉选：q2, q41, q23, q72, q81）。

PUT /advisor/preferences

更新当前用户钉选的问题 ID。丢弃未知 ID 并强制执行 MAX_PINS = 10 上限。

配置（要求 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

返回插件健康状况的快照（数据库表、GeoIP 状态、cron 计划、运行环境）。

POST /self-test

运行进程内的自检套件。

POST /cron/run

手动触发 Statnive 的定时 cron 任务。

POST /diagnostics/enable-dbip-city

为 GeoIP 查询启用 DB-IP City 备用源。

GET /privacy-audit

返回隐私审计摘要。

跟踪器采集（公开）

以下端点由内置的跟踪器写入，特意保持开放，以便未认证访客可以提交页面浏览和事件：

POST /hit

记录一次页面浏览。

POST /event

记录一次自定义事件。

POST /engagement

记录一次会话互动更新（滚动深度、停留时长）。

速率限制

跟踪器采集端点（/hit、/event、/engagement）在应用层针对滥用客户端进行节流。报表端点遵循标准的 WordPress REST 行为 —— 对于密集的自动化轮询，请在调用方加上自己的缓存层。

免费获取 Statnive