资源工坊

回调API列表 ​

获取文件信息 ​

页面渲染文件时需通过此回调获取文件元数据，包括当前文件信息、当前用户信息、操作权限信息

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/info）

请求方法： GET

签名方式： 无

请求头（Header） ​

名称是否必填说明
X-Weboffice-File-Id是文件id,字符串长度不超过64位
X-Wps-Weboffice-Token否开发者通过JSSDK设置用于用户鉴权TOKEN

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的自定义参数

响应体（Response） ​

正常返回 ​
名称类型是否必填说明
fileobject是文件信息
  ∟ idstring是文件id,字符串长度不超过64位
  ∟ namestring是文件名必须带后缀
  ∟ versioninteger是文档版本号，int32类型，从1开始累加，最大长度2147483647
  ∟ sizeinteger是文档大小，单位为字节；此处需传文件真实大小，否则会出现异常
  ∟ creatorstring是创建者id，字符串长度不超过32位
  ∟ create_timeinteger是创建时间，时间戳，单位为秒
  ∟ modifierstring是修改者id，字符串长度不超过32位
  ∟ modify_timeinteger是最近修改时间，时间戳，单位为秒
  ∟ download_urlstring是文档下载地址
  ∟ preview_pagesinteger是限制预览页数（不超过5000） 1. 用户操作权限 user.permission 为 write 时，限制不生效；2. 用户操作权限 user.permission 为 read 时，previewPages 默认值为 0，不限制预览页数；previewPages >= 1 时，限制生效，限制的页数为 previewPages 字段的值
  ∟ user_aclobject否用户权限
      ∟ renameinteger否重命名权限，1为打开该权限，0为关闭该权限，默认为0
      ∟ historyinteger否历史文件打开权限，1为打开该权限，0为关闭该权限，默认为1
      ∟ copyinteger否复制权限，1为打开该权限，0为关闭该权限，默认为1
      ∟ exportinteger否导出权限，1为打开该权限，0为关闭该权限，默认为1
      ∟ printinteger否打印权限，1为打开该权限，0为关闭该权限，默认为1
      ∟ commentinteger否评论权限，1为打开该权限，0为关闭该权限，编辑场景，默认为1，预览场景，默认为0。
      ∟ copy_controlinteger否限制在当前系统内复制粘贴，1为打开该权限，0为关闭该权限，默认为0。v7.1.2304.20230419新增
  ∟ watermarkobject否水印参数
      ∟ typeinteger否水印类型， 0为无水印； 1为文字水印
      ∟ valuestring否文字水印的文字，支持通过\r\n换行，支持emoji表情当type为1时此字段必选
      ∟ fillstylestring否水印的颜色（含透明度），非必选，有默认值。格式为：rgba( 192, 192, 192, 0.6 )
      ∟ fontstring否水印的字体，非必选，有默认值。格式为bold 20px Serif
若使用默认字体时，需确认环境中已有该字体
      ∟ rotatefloat否水印的旋转度(弧度)，非必选，有默认值，默认为-0.7853982
      ∟ horizontalinteger否水印水平间距，非必选，有默认值，默认为50
      ∟ verticalinteger否水印垂直间距，非必选，有默认值，默认为100
userobject是用户信息
  ∟ idstring是用户id，长度不超过32位
  ∟ namestring是用户名称
  ∟ permissionstring是用户操作权限，write：可编辑，read：只读模式
  ∟ avatar_urlstring否用户头像地址，支持url和base64
正常返回示例 ​
json
{
    "file": {
        "id": "132aa30a87064",
        "name": "example.doc",
        "version": 1,
        "size": 200,
        "creator": "id0",
        "create_time": 1136185445,
        "modifier": "id1000",
        "modify_time": 1551409818,
        "download_url": "http://www.xxx.cn/v1/file?fid=f132aa30a87064",
        "preview_pages": 3,
        "user_acl": {
            "rename": 1,
            "history": 1,
            "copy": 1,
            "export": 1,
            "print": 1,
            "comment": 1
        },
        "watermark": {
            "type": 1,
            "value": "禁止传阅\r\nwps-1000",
            "fillstyle": "rgba( 192, 192, 192, 0.6 )",
            "font": "bold 20px Serif",
            "rotate": -0.7853982,
            "horizontal": 50,
            "vertical": 100
        }
    },
    "user": {
        "id": "id1000",
        "name": "wps-1000",
        "permission": "read",
        "avatar_url": "http://xxx.cn/id=1000"
    }
}
异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

获取用户信息 ​

在线编辑页面批量获取当前正在编辑和编辑过文档的用户信息，需以数组的形式返回响应。

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/user/info）

请求方法： POST

签名方式： 无

请求头（Header） ​

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

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的自定义参数

请求体（Body） ​

名称类型是否必填说明
idsarray是字符串数组，用户 id 数组
请求体示例 ​
json
{
    "ids": ["id1000", "id2000"]
}

响应体（Response） ​

正常返回 ​
名称类型是否必填说明
usersarray是用户信息数组
  ∟ idstring是用户 ID，字符串长度不超过 32 位
  ∟ namestring是用户名
  ∟ avatar_urlstring否用户头像地址，支持url 和 base64
正常返回示例 ​
json
{
  "users": [
    {
       "id": "id1000",
       "name": "wps-1000",
       "avatar_url": "http://xxx.cn/?id=1000"
    },
    {
      "id": "id2000",
      "name": "wps-2000",
      "avatar_url": "http://xxx.cn/?id=2000"
    }
  ]
}
异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

上传文件新版本 ​

当文档在线编辑并保存之后，上传该文档最新版本到对接的应用，同时版本号进行相应的变更，需要对接方内部实现文件多版本管理机制。

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/save）

请求方法： POST

签名方式： 无

请求头（Header） ​

名称是否必填说明
Content-Type是固定为: multipart/form-data
X-Weboffice-File-Id是文件id,字符串长度不超过64位
X-Weboffice-Save-Type是新版本类型，可选值：auto：自动保存机制触发的新版本： 1. 所有用户1分钟内未修改会触发的保存  2.版本回退触发的保存 3. WebSocket链接断开触发的保存 manual：用户手动保存触发的新版本：  1. 用户手动关闭网页触发的保存  2. 用户通Ctrl+S触发的保存
X-Wps-Weboffice-Token否开发者通过JSSDK设置用于用户鉴权TOKEN

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的自定义参数

请求体（Body） ​

名称类型是否必填说明
filefile是新版本的文件的文件流

响应体（Response） ​

正常返回 ​

当对接应用获取文件信息成功且完成版本保存后，返回以下信息：

名称类型是否必填说明
fileobject是新版本的文件
  ∟ idstring是文件 id，字符串长度不超过 64位
  ∟ namestring是文件名（含后缀名）
  ∟ versioninteger是文档版本号，int32类型，从1开始累加，最大长度2147483647版本号请勿随意返回
  ∟ sizeinteger是文件大小，单位B（字节）
  ∟ download_urlstring是文件下载地址
正常返回示例 ​
json
{
  "file": {
    "id": "f132aa30a87064",
    "name": "example.doc",
    "version": 2,
    "size": 200,
    "download_url": "http://www.xxx.cn/v1/file?fid=f132aa30a87064"
  }
}
异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

文件重命名 ​

用户在在线编辑页面修改了文件名后，把新的文件名上传到服务端保存。

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/rename）

请求方法： PUT

签名方式： 无

请求头（Header） ​

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

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的自定义参数

请求体（Body） ​

参数参数类型是否必填说明
namestring是文件新名称（限制 240 个字符长度）

响应体（Response） ​

正常返回 ​

200 OK

异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

通知此文件目前有哪些人正在协作 ​

当有用户加入或者退出协作的时候，上传当前文档协作者的用户信息，可以用作上下线通知。

注：1.接口只能用来统计在线人数使用或大盘统计，并不代表用户页面的开关。请不要依赖该接口做单一用户的计费、判断退出等逻辑。2.此接口可以根据需要实现，若不实现直接返回 http 响应码 200。

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/online）

请求方法： POST

签名方式： 无

请求头（Header） ​

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

查询参数（Query） ​

名称类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的所有用户以w_third开头的自定义参数

请求体（Body） ​

名称类型是否必填说明
idsarray是字符串数组，用户 id 数组

响应体（Response） ​

正常返回 ​

200 OK

异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当code为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

回调通知 ​

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

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

回调说明 ​

回调地址： 回调地址+uri（默认/v1/3rd/onnotify）

请求方法： POST

签名方式： 无

请求头（Header） ​

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

查询参数（Query） ​

名称类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的自定义参数

请求体（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
请求体示例 ​
html
//
企业已经打开文件总数，仅打开一个未打开的文件时调用，某些错误会导致不触发打开文件总数的回调通知
{ "cmd": "OnlineFileCountCmd", "body": { "file_id": "id", //
文件id,字符串长度不超过64位 "userid": "032026", // 用户 Id "counts": 13, //
当前文档并发数 "maxcounts": 20, // 最大文档并发数（套餐限制） "operated_time":
"1597127230" // 回调时系统时间 } } // 每次对文件进行打印或导出操作时调用 {
"cmd": "OperateRecordExport", "body": { "file_id": "685540", //
文件id,字符串长度不超过64位 "operated_time": "1597127230", // 回调时系统时间 } }
// 用户打开新页面时调用 { "cmd": OpenPageCmd, "body": { "result": ErrorCode, //
打开结果 "detail": ErrorDetail // 详细信息 } } // 用户关闭页面时调用 { "cmd":
"UserQuit", "body": { "active": "20", // 用户链接占用时长，单位秒 (S) "file_id":
"685540", // 文件id,字符串长度不超过64位 "filesize": "894", //
文件大小，单位字节 (B) "filetype": "s", // 文件类型，有四种，分别是
"s"(表格)、"w"(文字)、"p"(演示)、"f"(pdf) "operated_time": "1597127230", //
回调时系统时间 "permission": "write", // 用户权限，编辑或预览 "userid": "53226"
// 用户 id } } // 用户打开新页面时调用 { "cmd": "UserJoin", "body": {
"permission": "write", // 用户权限，编辑或预览 "userid": "59-322032026", // 用户
id "operated_time": "1597127230", // 回调时系统时间 } }
//当文档从无变化到有变化的时候，会推送该消息
//文档状态改变时才会推送，举例以下推送几种情况
//用户首次打开文档并编辑，会推送一次
//当用户保存文档成功后继续编辑才会推送（从保存状态变为改动状态） { "cmd":
"FileDirty", "body": {}, }
//当文档从有改动状态变为已保存状态时，会推送该消息。通常为调用保存成功之后推送 {
"cmd": "FileClear", "body": {}, } 当文档新增评论时，会推送该消息。 { "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": "自定义错误提示"
}

获取特定版本的文件信息 ​

适用版本>=v6.0.2206.20220629

在历史版本预览和回滚历史版本的时候，获取特定版本文档的文件信息。

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/version/:version）

请求方法： GET

签名方式： 无

请求头（Header） ​

名称是否必填说明
X-Weboffice-File-Id是文件id,字符串长度不超过64位
X-Wps-Weboffice-Token否开发者通过JSSDK设置用于用户鉴权TOKEN

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的所有用户以w_third开头的自定义参数

路径参数（Path） ​

名称类型是否必填说明
versioninteger是版本号

响应体（Response） ​

正常返回 ​

当对接应用获取文件信息成功且完成版本保存后，返回以下信息：

名称类型是否必填说明
fileobject是新版本的文件
  ∟ idstring是文件 id，字符串长度不超过 64
  ∟ namestring是文件名（含后缀名）
  ∟ versioninteger是文档版本号，int32类型，从1开始累加，最大长度2147483647
  ∟ sizeinteger是文件大小，单位B（字节）
  ∟ create_timeinteger是创建时间，时间戳，单位为秒
  ∟ creatorstring是创建者 id，字符串长度不超过 32
  ∟ modify_timeinteger是修改时间，时间戳，单位为秒
  ∟ modifierstring是修改者 id，字符串长度不超过 32
  ∟ download_urlstring是文件下载地址
正常返回示例 ​
json
{
  "file": {
    "id": "f132aa30a87064",
    "name": "example.doc",
    "version": 6,
    "size": 200,
    "create_time": 1136185445,
    "creator": "id0",
    "modify_time": 1551409818,
    "modifier": "id1000",
    "download_url": "http://www.xxx.cn/v1/file?fid=f132aa30a87064&version=6"
  }
}
异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当result为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}

获取所有历史版本文件信息 ​

适用版本>=v6.0.2206.20220629

分页获取当前文档所有历史版本的文件信息，以数组的形式，按版本号从大到小的顺序返回响应。 （特别注意：该接口对接方需实现分页返回，且需倒序返回）

回调说明 ​

回调地址： 回调地址 + uri（默认/v1/3rd/file/history）

请求方法： POST

签名方式： 无

请求头（Header） ​

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

查询参数（Query） ​

参数参数类型是否必填说明
*（任意参数）*（任意类型）否在获取编辑链接时按需求传入的query中的所有用户以w_third开头的自定义参数

请求体（Body） ​

名称类型是否必填说明
idstring否文件id
offsetinteger是查询记录偏移量
countinteger是记录总数

响应体（Response） ​

正常返回 ​

当对接应用获取文件信息成功且完成版本保存后，返回以下信息：

名称类型是否必填说明
historiesarray是历史记录
  ∟ idstring是文件 id，字符串长度不超过 64
  ∟ namestring是文件名（含后缀名）
  ∟ versioninteger是文档版本号，int32类型，从1开始累加，最大长度2147483647
  ∟ sizeinteger是文件大小，单位B（字节）
  ∟ download_urlstring是文件下载地址
  ∟ create_timeinteger是创建时间，时间戳，单位为秒
  ∟ modify_timeinteger是修改时间，时间戳，单位为秒
  ∟ creatorobject是创建者信息
      ∟ idstring是用户 ID，字符串长度不超过 32
      ∟ namestring是用户名
      ∟ avatar_urlstring是用户头像地址，支持url 和 base64
  ∟ modifierobject是最近修改者信息
      ∟ idstring是用户 ID，字符串长度不超过 32
      ∟ namestring是用户名
      ∟ avatar_urlstring是用户头像地址，支持url 和 base64
正常返回示例 ​
json
{
  histories: [
    {
      id: "f132aa30a87064",
      name: "example.doc",
      version: 3,
      size: 200,
      download_url: "http://www.xxx.cn/v1/file?fid=f132aa30a87064&version=3",
      create_time: 1136185445,
      modify_time: 1539847453,
      creator: {
        id: "id0",
        name: "wps-0",
        avatar_url: "http://xxx.cn/?id=0"
      },
      modifier: {
        id: "id1000",
        name: "wps-1000",
        avatar_url: "http://xxx.cn/?id=1000"
      }
    },
    {
      id: "f132aa30a87064",
      name: "example.doc",
      version: 2,
      size: 200,
      download_url: "http://www.xxx.cn/v1/file?fid=f132aa30a87064&version=2",
      create_time: 1136185445,
      modify_time: 1539847453,
      creator: {
        id: "id0",
        name: "wps-0",
        avatar_url: "http://xxx.cn/?id=0"
      },
      modifier: {
        id: "id1000",
        name: "wps-1000",
        avatar_url: "http://xxx.cn/?id=1000"
      }
    },
    {
      id: "f132aa30a87064",
      name: "example.doc",
      version: 1,
      size: 200,
      download_url: "http://www.xxx.cn/v1/file?fid=f132aa30a87064&version=1",
      create_time: 1136185445,
      modify_time: 1539847453,
      creator: {
        id: "id0",
        name: "wps-0",
        avatar_url: "http://xxx.cn/?id=0"
      },
      modifier: {
        id: "id1000",
        name: "wps-1000",
        avatar_url: "http://xxx.cn/?id=1000"
      }
    }
  ]
}
异常返回 ​
名称类型是否必填说明
codeinteger是错误码，详细见《回调错误码》
messagestring是错误提示
detailsstring是错误提示详细信息
hintstring否自定义错误信息，当result为40007错误码时必填
异常返回示例 ​
json
{
  "code": 40005,
  "message": "InvalidArgument",
  "details": "参数错误",
  "hint": "自定义错误提示"
}