# 回调说明
下文接口由接入方实现，用于文件编辑、文件格式转换、文件重命名的调用。接口最终由文档中台调用，请务必严格遵循说明实现接口，否则可能造成中台调用异常。请求参数由文档中台发送，接入方请重点关注响应参数。
通用响应结构：
{
"code": 200,
"message": "success",
"data": {}
}
code 为 200 时表示请求成功，否则表示请求失败。请求成功或失败均会在 message、data 中附带相关信息。
# 获取文件元数据
获取文件元数据，包括当前文件信息和当前用户信息。
API 地址：/v1/3rd/file/info
调用方法：GET
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
响应示例：
{
"code": 200,
"message": "success",
"data": {
"file": {
"id": "id1000", // 文件 id，字符串长度小于 4(必填)
"name": "example.doc", // 文件名(必须带文件后缀) (必填)
"version": 1, // 当前版本号，必须大于 0，同时位数小于 11 (必填)
"size": 200, // 文件大小，单位为 B(文件真实大小，否则会出现异常) (必填)
"creator": "id0", // 创建者 id，字符串长度小于 40 (必填)
"createTime": 1619078626, // 创建时间，时间戳，单位为秒 (必填)
"modifier": "id1000", // 修改者 id，字符串长度小于 40 (必填)
"modifyTime": 1619078626, // 修改时间，时间戳，单位为秒 (必填)
"downloadUrl": "http://www.xxx.cn/v1/file?fid=id1000", // 文档下载地址 (必填)
// 非必填
"watermark": {
"type": 1, // 水印类型， 0 为无水印； 1 为文字水印
"value": "禁止传阅", // 文字水印的文字，当 type 为 1 时，此字段必填
"fillstyle": "rgba( 192, 192, 192, 0.6 )", // 水印的透明度，非必填，有默认值
"font": "bold 20px Serif", // 水印的字体，非必填，有默认值
"fontSize": "18px", // 水印的字体大小，非必填，有默认值
"rotate": -0.7853982, // 水印的旋转度，非必填，有默认值
"horizontal": 50, // 水印水平间距，非必填，有默认值
"vertical": 100, // 水印垂直间距，非必填，有默认值
"color": "black", // 水印颜色，非必填，有默认值
"width": 180, // 水印宽度，非必填，有默认值
"height": 80 // 水印高度，非必填，有默认值
}
},
// 必填
"user": {
"id": "id1000", // 用户 id，长度小于 32 (必填)
"name": "xx", // 用户名称 (必填)
"permission": "write", // 用户操作权限，write：可编辑，read：预览 (必填)
"avatarUrl": "http://xxx.cn/id=1000" // 用户头像地址 (非必填)
}
}
}
注意：
- 文件名一定要带格式后缀；
- 返回参数类型必须与示例一致；
- 不要带注释。
# 获取用户信息
批量获取正在编辑和编辑过文档的用户信息，以数组形式返回。
API 地址：/v1/3rd/user/info
调用方法：POST
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
请求参数：
| 参数名 | 参数类型 | 数据类型 | 是否必须 | 备注 |
|---|---|---|---|---|
| ids | body | string[] | 是 | 用户 ID 列表 |
请求示例：
{
"ids": ["id1000", "id1001"]
}
响应示例：
{
"code": 200,
"message": "success",
"data": {
"users": [
{
"id": "id1000", // 用户 ID，字符串长度小于 32
"name": "xxx", // 用户名
"avatarUrl": "http://xxx.cn/?id=1000" // 用户头像
},
{
"id": "id1001", // 用户 ID，字符串长度小于 32
"name": "xxx", // 用户名
"avatarUrl": "http://xxx.cn/?id=1001" // 用户头像
}
]
}
}
# 文档回存
当文档在线编辑并保存后，上传该文档最新的版本文件及版本号，接入方需要存储该文件。
API 地址：/v1/3rd/file/save
调用方法：POST
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
| saveType | auto/manual | 自动保存（auto）/手动保存（manual |
| saveVersion | long | 版本号 |
请求参数：
| 参数名 | 参数类型 | 数据类型 | 是否必须 | 备注 |
|---|---|---|---|---|
| file | body | file | 是 | 是 |
响应示例：
{
"code": 200,
"message": "success",
"data": {
"file": {
"id": "id1000", // 文件 id，字符串长度小于 40
"name": "example.doc", // 文件名
"size": 200, //文件大小，单位是 B
"downloadUrl": "http://www.xxx.cn/v1/file?fid=id1000" // 文件下载地址
}
}
}
# 获取历史版本
获取当前文档所有历史版本的文件信息，以数组的形式，按版本号从大到小的顺序返回响应。
API 地址：/v1/3rd/file/history
调用方法：POST
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
响应示例：
点击查看
{
"code": 200,
"message": "success",
"data": {
"histories": [
{
"id": "id1000", // 文件 id,字符串长度小于 40
"name": "example.doc", // 文件名
"version": 3, // 版本号，位数小于 11
"size": 200, // 文件大小
"downloadUrl": "http://www.xxx.cn/v1/file?fid=id1000&version=3", // 文档下载地址
"createTime": 1619078626, // 创建时间，以时间戳表示，单位为秒
"modifyTime": 1619078626, // 修改时间，以时间戳表示，单位为秒
"creator": {
"id": "id0", // 创建者 id，字符串长度小于 40
"name": "id-0", // 创建者名字
"avatarUrl": "http://xxx.cn/?id=0" // 创建者头像地址
},
"modifier": {
"id": "id1000", // 修改者 id，字符串长度小于 40
"name": "xxx", // 修改者名字
"avatarUrl": "http://xxx.cn/?id=1000" // 修改者头像地址
}
},
{
"id": "id100", // 文件 id,字符串长度小于 40
"name": "example.doc", // 文件名
"version": 2, // 版本号，位数小于 11
"size": 200, // 文件大小
"downloadUrl": "http://www.xxx.cn/v1/file?fid=id100&version=2", // 文档下载地址
"createTime": 1619078626, // 创建时间，以时间戳表示，单位为秒
"modifyTime": 1619078626, // 修改时间，以时间戳表示，单位为秒
"creator": {
"id": "id0", // 创建者 id，字符串长度小于 40
"name": "id-0", // 创建者名字
"avatarUrl": "http://xxx.cn/?id=0" // 创建者头像地址
},
"modifier": {
"id": "id1000", // 修改者 id，字符串长度小于 40
"name": "xxx", // 修改者名字
"avatarUrl": "http://xxx.cn/?id=1000" // 修改者头像地址
}
},
{
"id": "id100", // 文件 id,字符串长度小于 40
"name": "example.doc", // 文件名
"version": 1, // 当前版本号，必须大于 0，同时位数小于 11
"size": 200, // 文件大小
"downloadUrl": "http://www.xxx.cn/v1/file?fid=id100&version=1", // 文档下载地址
"createTime": 1619078626, // 创建时间，以时间戳表示，单位为秒
"modifyTime": 1619078626, // 修改时间，以时间戳表示，单位为秒
"creator": {
"id": "id0", // 创建者 id，字符串长度小于 40
"name": "id-0", // 创建者名字
"avatarUrl": "http://xxx.cn/?id=0" // 创建者头像地址
},
"modifier": {
"id": "id1000", // 修改者 id，字符串长度小于 40
"name": "xxx", // 修改者名字
"avatarUrl": "http://xxx.cn/?id=1000" // 修改者头像地址
}
}
]
}
}
# 文档重命名
用户修改文档名称后，把新的文档名称上传到服务器保存。
API 地址：/v1/3rd/file/rename
调用方法：PUT
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
请求参数：
| 参数名 | 参数类型 | 数据类型 | 是否必须 | 备注 |
|---|---|---|---|---|
| name | body | string | 是 | 新文档名 |
请求示例：
{
"name": "rename.docx" // 文件新名称
}
响应示例:
{
"code": 200,
"message": "success",
"data": null
}
# @相关人员或文档
在文档中@提及联系人或文档的功能，结合消息通知系统，被@人员可在消息通知系统内接收消息。
API 地址：/v1/3rd/mention/userList
调用方法：GET
请求头：
| Header | 示例 | 描述 |
|---|---|---|
| token | xxxxxxx | 校验身份的 token，由文档编辑接口传入。 |
| fid | id1000 | 文件 ID |
响应示例:
{
"code": 200,
"message": "success",
"data": {
"userInfoDTOList": [
{
"uid": "xf00001",
"highLightNickname": "xf00001",
"headPhotoUrl": "",
"nickname": "xf00001",
"roleName": "所有者"
},
{
"uid": "xf00002",
"highLightNickname": "xf00002",
"headPhotoUrl": "",
"nickname": "xf00002",
"roleName": "无权限"
}
],
"fileInfoDTOList": [
{
"fid": "xxx",
"name": "讯飞文档",
"docType": "note",
"permissions": null,
"creator": 1234,
"creatorName": "xf1234",
"owner": 1234,
"ownerName": "xf1234",
"createTime": 1688634236107,
"modifyTime": 1688698474338
}
]
}
}