资源工坊

回调通知 ​

打开或关闭文件时，WPS 会回调一些通知，目前有 7 类回调通知（详情查看下文的请求示例）。

注：1.某些错误会导致不触发打开文件总数的回调通知。2.接口只能用来运维和运营统计，请不要依赖该接口做计费、版本保存等需求

请求说明 ​

请求地址回调地址 + uri（默认为：/v1/3rd/onnotify）
请求方法POST
签名方式无

请求头（Header） ​

名称是否必填说明
Content-Type是固定为: application/json
X-Weboffice-File-Id是文件id
X-Wps-Weboffice-Token否开发者通过JSSDK设置用于用户鉴权TOKEN

查询参数（Query） ​

名称参数类型是否必填说明
_w_third_*object否合作方自定义参数, _w_third_作为前缀,_w_third_appid,_w_third_file_id 字段已被使用，对接方请合理避开

请求体（Body） ​

名称类型是否必填说明
cmdstring否命令参数，可选值： OnlineFileCountCmd：文档打开文件总数的回调命令 OperateRecordExport：打印或导出操作命令 OpenPageCmd：当用户调用WebSocket的session 接口获取token的时候会调用，即 CreateSession 接口调用 UserJoin：当用户进行 WebSocket 连接建立之后，发送 session.open 的时候 UserQuit：在关闭在线编辑协作页面的时候会调用通知用户退出 CommentAdd：>=v6.1.2301.20230116在新增评论的时候会调用通知用户
bodyobject否信息内容
  ∟ file_idstring否文件ID
  ∟ filesizeinteger否文件大小，单位字节 (B)
  ∟ filetypestring否文件类型，有四种，分别是 "s"(表格)、"w"(文字)、"p"(演示)、"f"(pdf)
  ∟ useridstring否用户 id
  ∟ permissionstring否用户权限，编辑或预览
  ∟ countsinteger否当前文档并发数
  ∟ maxcountsinteger否最大文档并发数（套餐限制）
  ∟ activeinteger否用户链接占用时长，单位秒 (S)
  ∟ resultstring否打开结果
  ∟ detailstring否详细信息
  ∟ operated_timestring否回调时系统时间
  ∟ comment_idstring否评论id
  ∟ user_idstring否用户 id

请求体示例 ​

示例1：OnlineFileCountCmd

企业已经打开文件总数，仅打开一个未打开的文件时调用，某些错误会导致不触发打开文件总数的回调通知

json
{
  "cmd": "OnlineFileCountCmd",
  "body": {
    "file_id": "id",
    "userid": "032026",
    "counts": 13,
    "maxcounts": 20,
    "operated_time": "1597127230"
  }
}

示例2：OperateRecordExport

每次对文件进行打印或导出操作时调用

json
{
  "cmd": "OperateRecordExport",
  "body": {
    "file_id": "685540",
    "operated_time": "1597127230"
  }
}

示例3：OpenPageCmd

用户打开新页面时调用

json
{
  "cmd": "OpenPageCmd",
  "body": {
    "result": "ErrorCode",
    "detail": "ErrorDetail"
  }
}

示例4：UserQuit

用户关闭页面时调用

json
{
  "cmd": "UserQuit",
  "body": {
    "active": "20",
    "file_id": "685540",
    "filesize": "894",
    "filetype": "s",
    "operated_time": "1597127230",
    "permission": "write",
    "userid": "53226"
  }
}

示例5：UserJoin

用户打开新页面时调用

json
{
  "cmd": "UserJoin",
  "body": {
    "permission": "write",
    "userid": "59-322032026",
    "operated_time": "1597127230"
  }
}

示例6：FileDirty

当文档从无变化到有变化的时候，会推送该消息。文档状态改变时才会推送，举例以下推送几种情况：

  • 用户首次打开文档并编辑，会推送一次
  • 当用户保存文档成功后继续编辑才会推送（从保存状态变为改动状态）
json
{
  "cmd": "FileDirty",
  "body": {}
}

示例7：FileClear

当文档从有改动状态变为已保存状态时，会推送该消息。通常为调用保存成功之后推送

json
{
  "cmd": "FileClear",
  "body": {}
}

示例8：CommentAdd

当文档新增评论时，会推送该消息

json
{
  "cmd": "CommentAdd",
  "body": {
    "comment_id": "1663000276",
    "file_id": "00420d8637e5a3692eba4d29cb636cf5",
    "operate_time": "1669622740",
    "user_id": "100"
  }
}

响应体（Response） ​

正常返回 ​

200 OK

异常返回 ​

名称参数类型是否必填说明
codeinteger是错误码
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填

异常返回示例 ​

json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}