概述

在不托管文件系统的情况下，WebOffice 集群提供了通用的文件在线预览/编辑/协同的能力。回调服务内的接口可以理解为文件系统的接口抽象，需要接入方提供文件元信息，文件下载地址，文件权限，文件保存等接口，用于打通在线编辑系统与文件系统。当然，接入方可以通过签发凭证(Token)的方式，自行管理文件系统的权限。

提示

Token 的流转：

接入业务方根据自身的鉴权需要自定义 Token。Token 在前端初始化 SDK时传入, WebOffice 将会在回调接入业务方接口时通过 Header 的 X-Weboffice-Token 字段回传，业务方可在其所实现的接口上检查当前用户的 Token，用于鉴权。

回调服务的要求

拥有已经通过审核的 WebOffice 应用。
回调接口需要接入方自行实现，所有接口都需实现，若只实现部分接口，可能会导致部分功能异常。
接入方实现的回调接口必须部署在公网。（需要保证能被 WebOffice 服务器访问到）

通讯过程

以下是接入方通过 WebOffice-SDK 接入 WebOffice 在线预览/编辑服务的通讯全过程。回调服务对应于WebOffice-服务端 以及 接入方-服务端 间的通讯。

回调配置

回调配置是我们开发者后台应用详情中一个重要的配置项，与在线预览编辑服务紧密相关，您开发的回调服务必须通过回调配置才能与应用进行绑定。在回调配置界面，可以对您的接口进行在线调试，根据返回的错误信息一步一步完善接口。当调试无误后，便可以通过左侧的开关开启此项接口，WebOffice 服务的对应的功能便会自动开启。

回调请求签名

WebOffice 服务集群发出的回调请求，全部经过 WPS-2 签名算法签名。签名需要用到申请应用时拿到的 AppId 和 AppSecret。签名实现如下：

签名相关请求头(HTTP Header)	说明
Date	请求发生时间。以时间格式的当前时间RFC1123
Content-Type	请求中 `Body` 内容的 mime 类型
Content-Md5	请求中 `Body` 内容的 `md5` 值十六进制表示方式, 小写。如果 `Body` 为空，改用 `URI` 计算, 例如: 原始请求为 GET `https://foo.bar.com/baz/v3/3rd/files/123` 则取 `/baz/v3/3rd/files/123` 计算
Authorization	格式为：`WPS-2:AppId:SHA1值` 其中 `SHA1值` 的计算方式为 `SHA1( AppSecret + Content-Md5 + Content-Type + Date)` 十六进制表示方式, 小写

提示

Get请求 Content-Type 使用空字符串来计算相关讨论：社区-签名算法

业务数据请求头

除签名头外，回调请求会携带如下四个业务数据头：

请求头	必须	类型	说明
X-App-Id	是	string	当前请求所属的 `AppId` 与 URl 上的 `_w_appid` 值相同
X-WebOffice-Token	是	string	当前请求的用户凭证，即通过传递的`token`值初始化参数
X-Request-Id	否	string	本次请求 `ID`，方便定位问题
X-User-Query	否	string	URL 中的 query 部分，包含一些基础参数和 WebOffice SDK 时通过`customArgs`传递的参数，例如`customArgs`的值为`{"firstname":"jack","lastname":"green"}`，那么该请求头的内容为`_w_appid=xxx&_w_tokentype=xxx&file_id=xxx&firstname=jack&lastname=green`初始化

info

tip 提示上述提到的 URL 指的是接入方前端通过 WebOffice SDK 打开文档的 iframe 的链接。

接入方返回值格式

接入方应统一返回 application/json 格式的数据，相关字段和说明请参照下表。

字段	必须	类型	说明
code	是	integer	错误码，详见后续，请求成功时，`code` 为 `0`错误码
message	否	string	错误说明，请求成功时，该字段可以不返回
data	否	object	具体数据，请求失败时，该字段可以不返回

请求成功示例

json

{
  "code": 0,
  "message": "",
  "data": {
    //这里的具体数据，根据回调接口不同，返回不同的scheme
    "id": "404",
    "name": "Joe Doe"
  }
}

请求失败示例

json

{
  "code": 40004,
  "message": "file not exists"
}

返回字段规范

文件 ID

文件 ID 可由数字、字母和下划线组成，但不能以下划线开头。文件 ID 在接入方系统中不能具有二义性（保持唯一）。文件 ID 长度要求不超过 47 位字符串，超出规定长度的将无法校验通过。

用户 ID

用户 ID 可由数字、字母和下划线组成，但不能以下划线开头。用户 ID 在接入方系统中不能具有二义性（保持唯一）。用户 ID 长度要求不超过 48 位字符串，超出规定长度的将无法校验通过。

历史版本号

历史版本号只能为正数，且逐步递增，最大不超过 2147483647。建议从 1 开始递增，每保存一个版本加一。