在使用 OfficeSDK 提供的文档在线预览与编辑服务时，服务端回调是一个至关重要的部分。它允许您与 OfficeSDK 服务进行通信，并确保文档的存取、权限控制等操作能够无缝衔接到您的现有文件系统或业务逻辑中。通过服务端回调，您可以确保文档能够正确读取、编辑并保存到您自己的存储系统中。为什么需要服务端回调？#
OfficeSDK 本身不直接管理文件存储，而是通过您的服务端接口与文件系统交互。通过实现回调，您可以：自由管理文件存储：您可以选择任意存储解决方案（如本地文件系统、对象存储、云存储等），而不受 SDK 局限。
灵活的权限控制：您可以通过签发 Token 的方式自行定义文件访问权限，确保只有合适的用户能访问或编辑文档。
文档元数据的管理：服务端回调帮助 OfficeSDK 获取文档的元数据（如文件名、大小、下载地址等），确保文档能够正确加载和操作。
Token 使用概述
在 OfficeSDK 服务中，Token 是实现安全鉴权和访问控制的核心机制。通过签发和使用 Token，您能够确保只有授权的用户可以访问和操作文档内容。1.
生成 Token：Token 由您的后端系统生成，使用时需要传入用户的身份、权限以及有效期等参数；
2.
传递 Token：前端集成 Web SDK 时，将 Token 作为请求头的一部分，当鉴权凭证传 递给 OfficeSDK；
3.
验证 Token：在 OfficeSDK 向您的回调接口发起请求时，您需要在服务端对传入的 Token 校验用户身份、权限以及请求的合法性。
回调服务的要求#
回调服务必须与您部署 OfficeSDK 的服务在同一网络环境中；
控制后台的回调接口列表中，标注为“必配”的接口必须全部实现，且全部开启，否则可能导致功能异常。
回调通讯过程概览#
回调配置#
本地运行 OfficeSDK 服务后，访问控制后台的「回调配置」页面，配置您开发的回调服务与回调网关，并在线联调回调接口。OfficeSDK 在调用您的回调接口时，会附带以下请求头信息。请确保您的服务端能够正确读取并处理这些 Header，用于身份校验及请求追踪：| Header 名称 | 是否必须 | 类型 | 描述 |
|---|
| X-OfficeSDK-Token | 是 | string | 当前请求的用户鉴权 Token，接入方需校验合法性 |
| X-Request-Id | 否 | string | 请求唯一标识，可用于日志追踪 |
| X-User-Query | 否 | string | 用于传递请求 URL 中的 Query 参数部分，其值为 key=value 形式的字符串序列。如地址：/v1/api/file/page？file_id=xxx&firstname=jack&lastname=green，那么该值是file_id=xxx&firstname=jack&lastname=green |
回调返回值说明#
OfficeSDK 在调用您的回调接口时，需要根据接口返回的内容判断后续的文件处理行为。为确保联调顺利，请您按照以下规范的数据。{
"code": 0,
"message": "",
"data": {
}
}
| 字段 | 是否必须 | 类型 | 描述 |
|---|
| code | 是 | integer | 状态码，请求成功时，code 为 0，详见错误码说明 |
| message | 否 | string | 描述信息，用于辅助调试。请求成功时，该字段可以不返回 |
| data | 否 | object | 回调类型相关的业务数据内容，具体结构由不同的回调场景决定。请求失败时，该字段可以不返回 |
若返回状态码 code != 0，OfficeSDK 将视为回调失败；
data 字段中需要包含对应业务场景要求的字段（如文件下载地址、文件名等）；
返回内容需为标准 JSON 格式，避免多余空格或 BOM 头导致解析失败。
请求成功示例#
{
"code": 0,
"message": "",
"data": {
"id": "404",
"name": "Joe Doe"
}
}
请求失败示例#
{
"code": 40004,
"message": "file not exists"
}
回调接口字段规范#
为了确保 OfficeSDK 与您的服务端能够顺利通信，请按照以下规范返回回调接口字段。规范化的字段将帮助我们在不同场景中准确解析和处理数据。组成规则：文件 ID 可由 数字、字母 和 下划线 组成，但不能以下划线开头；
唯一性要求：文件 ID 在接入方系统中必须唯一，不能存在二义性；
长度要求：文件 ID 的长度要求 不超过 47 个字符，超出此长度的文件 ID 将无法校验通过。
示例：
✅ 合规的文件 ID：file_12345, document_v1
❌ 不合规的文件 ID：_file123, document@v1
组成规则：用户 ID 可由 数字、字母 和 下划线 组成，但 不能以下划线开头；
唯一性：用户 ID 在接入方系统中必须唯一，不能具有二义性；
长度要求：用户 ID 长度不得超过 48 位字符串，超出此长度将无法通过校验。
示例：
✅ 合规的用户 ID：user_001, user_name_123
❌ 不合规的用户 ID：_user123, user*123
最大值限制：历史版本号的最大值不得超过 2147483647；
递增建议：建议从 1 开始递增，每保存一个版本加一。
示例：
✅ 有效的历史版本号：1, 2, 100, 2147483647
❌ 无效的历史版本号：0 (不能为零), -1 (不能为负数), 2147483648 (超出最大值)
回调接口错误码说明#
在 OfficeSDK 的回调接口中，我们为常见的错误情况定义了标准的错误码。您可以根据返回的 code 字段值，快速识别和处理不同类型的错误。{
"code": 0,
"message": "",
"data": {}
}
返回的 code 字段 用于指示请求的处理结果。0 表示成功，非 0 表示失败；
message 字段 提供了错误的简要描述，可以帮助开发者快速定位问题。
