回调通知

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

注：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）

名称	类型	是否必填	说明
cmd	string	否	命令参数，可选值： OnlineFileCountCmd：文档打开文件总数的回调命令 OperateRecordExport：打印或导出操作命令 OpenPageCmd：当用户调用 WebSocket 的 session 接口获取 token 的时候调用（CreateSession） UserJoin：用户建立 WebSocket 连接并发送 session.open UserQuit：关闭在线协作页面时通知用户退出 CommentAdd：新增评论时触发
body	object	否	信息内容
∟ file_id	string	否	文件 ID
∟ file_name	string	否	文件名称
∟ filesize	integer	否	文件大小，单位字节 (B)
∟ filetype	string	否	文件类型（"s"=表格、"w"=文字、"p"=演示、"f"=pdf）
∟ format	string	否	导出或打印格式（如 pdf、xlsx 等）
∟ userid	string	否	用户 ID
∟ user_id	string	否	用户 ID（兼容字段）
∟ permission	string	否	用户权限（编辑 / 预览）
∟ counts	integer	否	当前文档并发数
∟ maxcounts	integer	否	最大文档并发数（套餐限制）
∟ active	integer	否	用户连接占用时长，单位秒 (S)
∟ result	string	否	操作或文件打开结果
∟ detail	string	否	详细信息
∟ operated_time	string	否	回调发生的系统时间
∟ download_url	string	否	下载链接或导出后的文件访问链接
∟ md5	string	否	文件 MD5 校验值
∟ print	string	否	打印相关设置或标记
∟ selection_id	string	否	选区 ID（评论或导出时使用）
∟ text	string	否	文本内容（如评论内容）
∟ is_reply	string	否	是否为评论回复（0/1）
∟ notify_ids	string	否	需要通知的用户 ID 列表（逗号分隔）
∟ comment_id	string	否	评论 ID

请求体示例

示例1：OnlineFileCountCmd

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

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

示例2：OperateRecordExport

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

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

示例3：OpenPageCmd

用户打开新页面时调用

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

示例4：UserQuit

用户关闭页面时调用

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

示例5：UserJoin

用户打开新页面时调用

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

示例6：FileDirty

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

• 用户首次打开文档并编辑，会推送一次
• 当用户保存文档成功后继续编辑才会推送（从保存状态变为改动状态）

{
  "cmd": "FileDirty",
  "body": {}
}

示例7：FileClear

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

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

示例8：CommentAdd

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

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

响应体（Response）

正常返回

200 OK

异常返回

名称	参数类型	是否必填	说明
code	integer	是	错误码
message	string	是	错误提示
details	string	是	错误提示详细信息
hint	string	否	自定义错误信息，当code为40007错误码时必填

异常返回示例

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