Skip to content

开放接口

网页侦探提供 开放 API,允许通过 HTTP 远程管理监控任务、客户端、通知渠道等资源。

服务端地址

所有接口统一使用以下基础地址:

https://webdiff.perk-net.com/api

下文路径均相对于该地址。示例:

https://webdiff.perk-net.com/api/open/task/stats

准备工作

  1. 在客户端打开 我的 → 开放接口,开启「开放接口」开关。
  2. 创建 AccessKey / SecretKey 密钥对;SecretKey 仅在创建时展示一次,请妥善保存。
  3. 可选:开启 IP 白名单,仅允许名单内 IP 换取访问令牌(多个 IP 用英文分号 ; 分隔)。

认证流程

开放 API 采用 AccessKey + SecretKey 换取短期 Token 的方式认证。

1. 获取访问令牌

POST https://webdiff.perk-net.com/api/common/openApi/getAccessKey

请求 Header

字段类型必填说明
Content-Typestring固定为 application/json

请求 Body(JSON)

字段类型必填说明
accessKeystringAccessKey
secretKeystringSecretKey

请求示例

json
{
  "accessKey": "pk_xxxxxxxxxxxxxxxx",
  "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

响应 data 字段

字段类型说明
tokenstring后续请求的身份凭证,默认有效期 7200 秒(2 小时)
expiresInnumberToken 有效时长(秒)
nickNamestring用户昵称

响应示例

json
{
  "code": 200,
  "msg": "",
  "data": {
    "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "expiresIn": 7200,
    "nickName": "用户昵称"
  }
}

若账号已有未过期的 Token 且剩余时间 ≥ 300 秒,会复用并续期。

2. 携带 Token 调用接口

在后续请求的 Header 中传入 Token(支持 Header 或 Cookie 读取):

http
GET https://webdiff.perk-net.com/api/open/user/userInfo
token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. 统一响应格式

所有接口返回 JSON:

字段类型说明
codenumber200 表示成功,其它为错误码
msgstring错误描述(成功时通常为空)
dataobject / array / null业务数据;无数据时为 null

4. 分页请求与响应

分页接口(任务列表、客户端列表等)使用统一的 PageDto 请求体与 PageVo 响应结构。

分页请求 Body

字段类型必填说明
currentnumber页码,从 1 开始,默认 1
pageSizenumber每页条数,默认 10
paramsobject查询条件,各接口字段见下文

分页响应 data 字段

字段类型说明
pageNumnumber当前页码
pageSizenumber每页条数
totalnumber总记录数
pagesnumber总页数
listarray当前页数据列表

用户

获取当前用户信息

GET https://webdiff.perk-net.com/api/open/user/userInfo

请求参数:无

响应 data 字段

字段类型说明
idnumber用户 ID
uidstring全局唯一用户标识,格式 U + 8 位大写字母数字
userNamestring用户昵称
headImgUrlstring头像 URL
memberLevelnumber当前会员等级:0 免费、1 会员、2 高级会员、3 企业会员;过期时为 0
memberLevelLabelstring会员等级名称
memberExpireTimestring会员过期时间,格式 yyyy-MM-dd HH:mm:ss;未开通时为 null
taskLimitnumber任务数量上限;-1 表示无限
maxClientsnumber允许同时在线的客户端数量上限;-1 表示无限
globalVarLimitnumber全局变量数量上限;-1 表示无限

响应示例

json
{
  "code": 200,
  "msg": "",
  "data": {
    "id": 10001,
    "uid": "UAB12CD34",
    "userName": "张三",
    "headImgUrl": "https://example.com/avatar.png",
    "memberLevel": 0,
    "memberLevelLabel": "免费用户",
    "memberExpireTime": null,
    "taskLimit": 10,
    "maxClients": 2,
    "globalVarLimit": 5
  }
}

监控任务

任务执行说明

「立即执行」仅向任务所属的 在线客户端 下发指令;任务实际运行在客户端本地,服务端不直接执行监控逻辑。

任务列表(分页)

POST https://webdiff.perk-net.com/api/open/task/list

请求 Body

字段类型必填说明
currentnumber页码,默认 1
pageSizenumber每页条数,默认 10
paramsobject筛选条件
params.keywordstring关键字,按任务名称 / 网址模糊匹配
params.statusnumber启用状态:1 运行中 / 0 已停用;为空表示全部
params.taskTypestring任务类型:WEBSITE / HTTP / RSS / DOMAIN_EXPIRY / SSL_CERT / PING / SCRIPT;为空表示全部
params.clientDeviceIdnumber运行客户端筛选:null 全部、0 未分配(主客户端执行)、-1 全节点、>0 指定客户端设备行 ID

响应 data.list[] 字段

字段类型说明
idnumber任务 ID
namestring任务名称
clientDeviceIdnumber归属客户端设备 ID(兼容旧版,已废弃)
runClientModestring运行方案:SINGLE 单节点 / ALL 全节点 / SPECIFIED 指定节点
runClientDeviceIdsnumber[]指定节点时的客户端设备行 ID 列表
runClientLabelstring运行客户端展示文案
clientDeviceNamestring客户端名称(已废弃,请使用 runClientLabel
taskTypestring任务类型
urlstring监控目标 URL
cronExpressionstringCron 表达式(分 时 日 月 周)
enablednumber是否启用:0 停用 / 1 启用
screenshotEnablednumber是否启用截图
notifyEnablednumber是否启用通知
notifyChannelIdsstring绑定的通知渠道 ID(逗号分隔字符串)
notifyChannelCountnumber绑定的通知渠道数量
elementCountnumber监控元素数量
createTimestring创建时间
updateTimestring更新时间

任务统计

GET https://webdiff.perk-net.com/api/open/task/stats

请求参数:无

响应 data 字段

字段类型说明
totalCountnumber当前用户全部任务数
runningCountnumber当前用户运行中任务数

任务详情

GET https://webdiff.perk-net.com/api/open/task/detail/{id}

路径参数

字段类型必填说明
idnumber任务 ID

响应 data 字段

字段类型说明
idnumber任务 ID
userIdnumber任务所属用户 ID
clientDeviceIdnumber归属客户端设备 ID(兼容旧版)
runClientModestring运行方案
runClientDeviceIdsnumber[]指定节点时的设备行 ID 列表
namestring任务名称
taskTypestring任务类型
taskConfigstring任务类型专属配置(JSON 字符串)
urlstring监控目标 URL
cookiesstringCookie 配置(JSON 字符串)
cookiePlusAccountLabelsobjectCookie Plus 账号 clientId → 中文名称映射
userAgentstring自定义 User-Agent
cronExpressionstringCron 表达式
randomDelayEnablednumber是否启用随机延迟:0 否 / 1
randomDelayMinSecondsnumber随机延迟最小秒数
randomDelayMaxSecondsnumber随机延迟最大秒数
enablednumber是否启用
screenshotEnablednumber是否启用截图
screenshotFullPagenumber是否启用全页长截图
screenshotMaxScrollnumber长截图最大滚动次数
extractScrollEnablednumber提取元素前是否滚动以触发懒加载
extractMaxScrollnumber元素提取前最大滚动次数
notifyEnablednumber是否启用通知
notifyChannelIdsnumber[]绑定的通知渠道 ID 列表
notifyChannelNamesstring[]绑定的通知渠道名称列表
notifyChannelTypesstring[]绑定的通知渠道类型列表
notifyTemplateIdnumber通知模板 ID;null 表示自动匹配内置默认
notifyTemplateNamestring通知模板名称
aiRulestringAI 生成的比对规则
elementsarray监控元素列表,见下表
createTimestring创建时间
updateTimestring更新时间

elements[] 字段

字段类型说明
idnumber元素 ID
selectorstringCSS / XPath 选择器
selectorTypestring选择器类型
extractTypestring提取模式:HTML / TEXT
labelstring元素标签
sortOrdernumber排序序号

taskConfig 说明

taskConfig 为 JSON 字符串,结构因任务类型而异。详见 监控任务类型 各类型说明页。

创建监控任务

POST https://webdiff.perk-net.com/api/open/task/create

请求 Body

字段类型必填说明
namestring任务名称
urlstring监控目标 URL
clientDeviceIdnumber归属客户端设备 ID(兼容旧版)
runClientModestring运行方案:SINGLE / ALL / SPECIFIED,默认 SINGLE
runClientDeviceIdsnumber[]指定节点时的客户端设备行 ID 列表
taskTypestring任务类型,默认 WEBSITE
taskConfigstring任务类型专属配置(JSON 字符串)
cookiesstringCookie 配置(JSON 字符串)
userAgentstring自定义 User-Agent,最长 500 字符
cronExpressionstringCron 表达式(5 字段:分 时 日 月 周),如 0 * * * *
randomDelayEnablednumber是否启用随机延迟
randomDelayMinSecondsnumber随机延迟最小秒数,≥ 0
randomDelayMaxSecondsnumber随机延迟最大秒数,≥ 0
screenshotEnablednumber是否启用截图
screenshotFullPagenumber是否启用全页长截图
screenshotMaxScrollnumber长截图最大滚动次数,1–100
extractScrollEnablednumber提取元素前是否滚动
extractMaxScrollnumber元素提取前最大滚动次数,1–100
notifyEnablednumber是否启用通知
notifyChannelIdsnumber[]绑定的通知渠道 ID 列表
notifyTemplateIdnumber通知模板 ID
aiRulestringAI 生成的比对规则
enablednumber是否启用,默认 1
elementsarray监控元素列表,最多 5 个,见下表

elements[] 字段

字段类型必填说明
selectorstringCSS / XPath 选择器
selectorTypestring选择器类型
extractTypestring提取模式:HTML(默认)/ TEXT
labelstring元素标签
sortOrdernumber排序序号

响应 data:number,新创建的任务 ID

更新监控任务

PUT https://webdiff.perk-net.com/api/open/task/update

请求 Body

字段类型必填说明
idnumber任务 ID
namestring任务名称
urlstring监控目标 URL
clientDeviceIdnumber归属客户端设备 ID(兼容旧版)
runClientModestring运行方案
runClientDeviceIdsnumber[]指定节点时的客户端设备行 ID 列表
taskTypestring任务类型
taskConfigstring任务类型专属配置(JSON 字符串)
cookiesstringCookie 配置(JSON 字符串)
userAgentstring自定义 User-Agent
cronExpressionstringCron 表达式
randomDelayEnablednumber是否启用随机延迟
randomDelayMinSecondsnumber随机延迟最小秒数
randomDelayMaxSecondsnumber随机延迟最大秒数
screenshotEnablednumber是否启用截图
screenshotFullPagenumber是否启用全页长截图
screenshotMaxScrollnumber长截图最大滚动次数
extractScrollEnablednumber提取元素前是否滚动
extractMaxScrollnumber元素提取前最大滚动次数
notifyEnablednumber是否启用通知
notifyChannelIdsnumber[]绑定的通知渠道 ID 列表
notifyTemplateIdnumber通知模板 ID
aiRulestringAI 生成的比对规则
elementsarray监控元素列表,最多 5 个

响应 datanull

删除监控任务

DELETE https://webdiff.perk-net.com/api/open/task/delete/{id}

路径参数

字段类型必填说明
idnumber任务 ID

响应 datanull

批量启用 / 停用任务

PUT https://webdiff.perk-net.com/api/open/task/batch/enabled

请求 Body

字段类型必填说明
idsnumber[]任务 ID 列表,最多 100 个
enablednumber目标状态:1 启用 / 0 停用

响应 data 字段

字段类型说明
successCountnumber成功数量
failureCountnumber失败数量
successIdsnumber[]成功的任务 ID
failuresarray失败明细
failures[].idnumber失败的任务 ID
failures[].messagestring失败原因
successDetailsarray批量启用时返回的成功任务详情(供客户端注册调度);停用时为 []

批量设置运行客户端

PUT https://webdiff.perk-net.com/api/open/task/batch/client-device

请求 Body

字段类型必填说明
idsnumber[]任务 ID 列表,最多 100 个
runClientModestring运行方案:SINGLE / ALL / SPECIFIED
runClientDeviceIdsnumber[]指定节点时的客户端设备行 ID 列表
clientDeviceIdnumber目标运行客户端设备行 ID(兼容旧版,等效于 SPECIFIED + 单设备)

响应 data:同「批量启用 / 停用任务」

立即执行任务

POST https://webdiff.perk-net.com/api/open/task/run-now/{id}

路径参数

字段类型必填说明
idnumber任务 ID

响应 data 字段

字段类型说明
dispatchedboolean是否已成功下发到目标客户端
targetOnlineboolean目标客户端当前是否在线
targetDeviceIdstring目标客户端 deviceId
targetDeviceNamestring目标客户端展示名称
messagestring提示文案

客户端设备

注册 / 上报客户端实例

POST https://webdiff.perk-net.com/api/open/client/device/register

请求 Body

字段类型必填说明
deviceIdstring客户端实例唯一标识(本地持久化生成的 UUID),最长 64 字符
namestring客户端名称,最长 100 字符
osstring客户端平台,如 win32-x64 / cli,最长 50 字符
versionstring客户端版本,最长 50 字符

响应 data 字段

字段类型说明
idnumber设备行 ID
deviceIdstring客户端实例唯一标识
namestring客户端名称
clientOsstring客户端平台
clientVersionstring客户端版本
isPrimarynumber是否主客户端:0 否 / 1
onlineboolean是否在线
taskCountnumber归属该客户端的任务数量
lastSeenstring最后活跃时间
createTimestring创建时间

客户端列表(轻量)

GET https://webdiff.perk-net.com/api/open/client/device/list

请求参数:无

响应 data[] 字段

字段类型说明
idnumber设备行 ID
deviceIdstring客户端实例唯一标识
namestring客户端名称
onlineboolean是否在线
createTimestring创建时间
sessionStartedAtstring本次会话启动时间(SSE 连接建立时刻;离线时为 null

客户端列表(分页)

POST https://webdiff.perk-net.com/api/open/client/device/list/page

请求 Body

字段类型必填说明
currentnumber页码,默认 1
pageSizenumber每页条数,默认 10
paramsobject查询条件(预留扩展,当前为空对象)

响应 data.list[] 字段:同「注册 / 上报客户端实例」响应

客户端统计

GET https://webdiff.perk-net.com/api/open/client/device/stats

请求参数:无

响应 data 字段

字段类型说明
totalCountnumber在册客户端总数
onlineCountnumber当前在线客户端数

重命名客户端

PUT https://webdiff.perk-net.com/api/open/client/device/rename

请求 Body

字段类型必填说明
deviceIdstring客户端实例唯一标识
namestring新名称,最长 100 字符

响应 datanull

删除客户端

DELETE https://webdiff.perk-net.com/api/open/client/device/delete/{deviceId}

路径参数

字段类型必填说明
deviceIdstring客户端实例唯一标识

响应 datanull

设为主客户端

PUT https://webdiff.perk-net.com/api/open/client/device/primary/{deviceId}

路径参数

字段类型必填说明
deviceIdstring客户端实例唯一标识

响应 datanull

踢客户端下线

POST https://webdiff.perk-net.com/api/open/client/device/kick/{deviceId}

路径参数

字段类型必填说明
deviceIdstring客户端实例唯一标识

响应 datanull


通知渠道

通知渠道列表

GET https://webdiff.perk-net.com/api/open/notifyChannel/list

请求参数:无

响应 data[] 字段

字段类型说明
idnumber渠道 ID
namestring渠道名称
typestring渠道类型:local / pushplus / dingtalk / wechatwork / feishu / webhook / email
configstring渠道配置(JSON 字符串)
enablednumber是否启用:0 停用 / 1 启用
createTimestring创建时间
updateTimestring更新时间

config 配置说明

各渠道 config 字段结构详见 通知渠道 及各渠道说明页。

新增通知渠道

POST https://webdiff.perk-net.com/api/open/notifyChannel/create

请求 Body

字段类型必填说明
namestring渠道名称,最长 100 字符
typestring渠道类型:pushplus / dingtalk / wechatwork / feishu / webhook / email
configstring渠道配置(JSON 字符串)
enablednumber是否启用

响应 data:number,新创建的渠道 ID

更新通知渠道

PUT https://webdiff.perk-net.com/api/open/notifyChannel/update

请求 Body

字段类型必填说明
idnumber渠道 ID
namestring渠道名称
typestring渠道类型
configstring渠道配置(JSON 字符串)
enablednumber是否启用

响应 datanull

删除通知渠道

DELETE https://webdiff.perk-net.com/api/open/notifyChannel/delete/{id}

路径参数

字段类型必填说明
idnumber渠道 ID

响应 datanull

构造测试通知请求

POST https://webdiff.perk-net.com/api/open/notifyChannel/test

后端将通知消息渲染成「待发送的 HTTP 请求」返回,调用方根据返回内容自行发起请求。

请求 Body

字段类型必填说明
typestring渠道类型
configstring渠道配置(JSON 字符串)

响应 data 字段

字段类型说明
channelIdnumber渠道 ID(测试时可为 null
channelTypestring渠道类型
channelNamestring渠道展示名称
methodstring请求方法:POST / GET
urlstring完整请求 URL
headersobject请求头(键值对)
bodystring请求体(JSON 字符串);GET 请求可能为空
successCheckstring响应成功判断方式
errorFieldstring识别错误消息时使用的 JSON 字段
localTitlestring本地桌面通知标题(仅 local 类型)
localBodystring本地桌面通知正文(仅 local 类型)

通知模板

通知模板列表

GET https://webdiff.perk-net.com/api/open/notifyTemplate/list

Query 参数

字段类型必填说明
taskTypestring按任务类型过滤
ruleTypestring按规则类型过滤

响应 data[] 字段

字段类型说明
idnumber模板 ID
userIdnumber用户 ID;0 表示系统内置
codestring内置模板 code;用户自定义为空
namestring模板名称
taskTypestring适用任务类型
ruleTypestring适用规则类型
titleTplstring标题模板
bodyTplstring正文模板(Markdown)
isBuiltinnumber是否系统内置:1 是(只读)
isDefaultnumber是否为该 (taskType, ruleType) 组合的默认模板
enablednumber是否启用
createTimestring创建时间
updateTimestring更新时间

通知模板详情

GET https://webdiff.perk-net.com/api/open/notifyTemplate/detail/{id}

路径参数

字段类型必填说明
idnumber模板 ID

响应 data:同列表单项字段

新增通知模板

POST https://webdiff.perk-net.com/api/open/notifyTemplate/create

请求 Body

字段类型必填说明
namestring模板名称,最长 120 字符
titleTplstring标题模板,最长 255 字符
bodyTplstring正文模板(Markdown)
taskTypestring适用任务类型:* / WEBSITE / HTTP / RSS / DOMAIN_EXPIRY / SSL_CERT / PING
ruleTypestring适用规则类型:* / changed / days_before_expiry
enablednumber是否启用

响应 data:number,新创建的模板 ID

更新通知模板

PUT https://webdiff.perk-net.com/api/open/notifyTemplate/update

请求 Body

字段类型必填说明
idnumber模板 ID
namestring模板名称
titleTplstring标题模板
bodyTplstring正文模板
taskTypestring适用任务类型
ruleTypestring适用规则类型
enablednumber是否启用

响应 datanull

删除通知模板

DELETE https://webdiff.perk-net.com/api/open/notifyTemplate/delete/{id}

路径参数

字段类型必填说明
idnumber模板 ID

响应 datanull

预览模板渲染结果

POST https://webdiff.perk-net.com/api/open/notifyTemplate/preview

请求 Body

字段类型必填说明
templateIdnumber模板 ID(与 titleTpl / bodyTpl 二选一)
titleTplstring标题模板(实时预览未保存内容时使用)
bodyTplstring正文模板(实时预览未保存内容时使用)
taskTypestring任务类型,决定 mock 变量集
ruleTypestring规则类型,决定 mock 变量集

响应 data 字段

字段类型说明
titlestring渲染后的标题(纯文本)
bodyMarkdownstring渲染后的正文(Markdown 源)
bodyHtmlstring渲染后的正文(HTML)
bodyTextstring渲染后的正文(纯文本兜底)

GET https://webdiff.perk-net.com/api/open/cookiePlusAccount/list

请求参数:无

响应 data[] 字段

字段类型说明
clientIdstring客户端账号 ID(跨设备一致)
labelstring账号名称
accessKeystringAccess Key
secretKeystringSecret Key
createTimestring创建时间
updateTimestring更新时间

PUT https://webdiff.perk-net.com/api/open/cookiePlusAccount/upsert

请求 Body

字段类型必填说明
clientIdstring客户端账号 ID,最长 64 字符
accessKeystringAccess Key,最长 200 字符
secretKeystringSecret Key,最长 500 字符
labelstring账号名称,最长 200 字符

响应 datanull

DELETE https://webdiff.perk-net.com/api/open/cookiePlusAccount/delete/{clientId}

路径参数

字段类型必填说明
clientIdstring客户端账号 ID

响应 datanull


全局变量

全局变量列表

GET https://webdiff.perk-net.com/api/open/global-var/list

请求参数:无

响应 data[] 字段

字段类型说明
idnumber变量 ID
namestring变量名称
valuestring变量值
remarkstring备注
sortnumber排序序号
createTimestring创建时间
updateTimestring更新时间

保存全局变量

PUT https://webdiff.perk-net.com/api/open/global-var/save

整表替换保存,传入的列表即为保存后的完整变量集。

请求 Body

字段类型必填说明
varsarray全局变量列表
vars[].namestring变量名称,最长 128 字符
vars[].valuestring变量值
vars[].remarkstring备注,最长 255 字符

响应 data[]:保存后的全局变量列表,字段同「全局变量列表」


调用示例

bash
# 1. 换取 Token
TOKEN=$(curl -sS -X POST 'https://webdiff.perk-net.com/api/common/openApi/getAccessKey' \
  -H 'Content-Type: application/json' \
  -d '{"accessKey":"YOUR_AK","secretKey":"YOUR_SK"}' \
  | jq -r '.data.token')

# 2. 查询任务统计
curl -sS 'https://webdiff.perk-net.com/api/open/task/stats' \
  -H "token: $TOKEN"

# 3. 分页查询任务列表
curl -sS -X POST 'https://webdiff.perk-net.com/api/open/task/list' \
  -H "token: $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"current":1,"pageSize":10,"params":{}}'

错误码说明

场景典型响应
AccessKey / SecretKey 无效code 非 200,未授权
开放接口未启用未授权
账号已禁用未授权
IP 不在白名单禁止访问(含请求方 IP)
Token 过期或缺失未授权,需重新换取 Token
参数校验失败code 非 200,msg 含具体字段错误信息