整体概述

回调接口是你的应用后端需要实现、由石墨主动来调的一组 HTTP 接口。石墨文档中台采用无状态架构——它不存你的用户表、文件表、权限表；用户每次打开、编辑、预览、搜索、@ 时，石墨实时向你的应用回调要这些信息。事件类回调则反过来：当编辑器内发生评论、@ 人、内容更新时，石墨主动推送给你的应用。

一、为什么必须有回调接口

石墨之所以把"回调"做成强约束，主要原因如下：

保护你的核心数据不外流：用户表、文件表、权限表都留在你的应用里，石墨只在每次请求时按需取一次。

权限实时获取实时更新：用户被停用、文件被改权限，下一次回调返回新结果，编辑器立即跟随，不存在"缓存了旧权限"的问题。

你的应用掌握主权：你随时可以下线一个文件、回收一个用户的访问，无需通知石墨。

二、回调接口实现优先级

回调接口数量看似多，但是重要的必须实现的接口就几个，这里列出了相关接口的实现优先级，可以根据你的实际业务场景酌情实现，

必须实现： 缺失会导致核心功能不可用。
建议实现： 影响 UI 体验，但不阻塞核心流程。
酌情实现： 仅在对应业务场景启用时需要。

说明	接口	不做的后果	是否建议实现	不需要场景
[重要] 获取当前用户信息	`GET /users/current/info`	用户身份取不到，无法预览本地文档、也无法创建协同文档	必须实现	任何场景都需要此接口
[重要] 获取预览文件元信息	`GET /files/{fileId}` (预览文件)	无法预览本地文档	必须实现	预览文档场景需要此接口
[重要] 获取协同文件元信息	`GET /files/{fileId}` (协同文件)	无法创建协同文档	必须实现	协同文档编辑、导入、导出等场景需要此接口
获取指定用户信息	`GET /users/{userId}`	标题栏、历史记录里他人头像缺失	建议实现	如果不需要显示标题栏、历史记录，则无需实现此接口
批量获取用户信息	`POST /users/batch/get`	多人协作侧栏空白	建议实现	如果不需要在多人协作侧栏显示其他协作头像，则无需实现此接口
获取文件协作者列表	`GET /files/{fileId}/collaborators`	评论通知、协作者列表异常	根据你实际业务需求酌情实现	如果不需要获取写作者列表，则无需实现此接口
以管理员身份获取文件元信息	`GET /admin/files/{fileId}`	跨表格引用、应用表格联动失败	根据你实际业务需求酌情实现	如果未启用跨表格引用功能，则无需实现此接口
事件推送接口	`POST /events`	业务系统拿不到评论/更新通知	根据你实际业务需求酌情实现	如果不需要接收来自石墨的事件通知，则无需实现此接口
按关键字搜索文件和用户列表	`/search/*`	@ 用户下拉列表为空，但不影响打开	根据你实际业务需求酌情实现	如果不需要在文件中 @ 其他客户，则无需实现此接口
获取团队、部门信息	`/teams/` / `/departments/`	团队场景不可用，但单文件不受影响	根据你实际业务需求酌情实现	如果不需要在表格单元格锁定中指定团队、部门，则无需实现此接口
获取当前用户水印设置	`/users/{userId}/watermark` 等水印接口	水印不展示	根据你实际业务需求酌情实现	如果不需要开启文件水印功能，则无需实现此接口

注：不在此列表中的回调接口均不是必须实现接口。

三、整体机制

回调链路分两类——石墨被动回调（用户触发）和石墨主动推送（系统/事件触发）：

要点：

被动回调触发自用户动作（打开、编辑、预览、@、评论），多数带 X-WebOffice-Token，目的是验证当前用户身份。

主动推送由编辑器内的协同事件触发（评论、@ 人、内容更新、版本变化），通过 POST /events 推到你的应用。

系统回调由石墨后台任务发起（跨表格引用、应用表格联动、表单订阅等），与具体用户无关，用 X-WebOffice-Signature 验证。

四、回调接口请求凭证

回调请求头里固定带 X-WebOffice-Credential-Type，标识本次回调是哪一类——你的应用据此选择校验 Token 还是校验 Signature：

Credential-Type	触发方	携带凭证	校验方式	典型场景
`0`	用户操作	`X-WebOffice-Token`	由你的应用自行签发与校验	打开文档、编辑、评论、@、预览、搜索
`3`	石墨系统	`X-WebOffice-Signature`	用 `appSecret` 校验 JWT (HS256)	跨表格引用、应用表格联动、定时任务、表单订阅

系统回调的 URL 上通常带 /admin/ 前缀（如 GET /admin/files/{fileId}）——这是它"与具体用户无关"的体现。

4.1 场景一：用户操作触发

你的应用要做的事：

解析 Token，取出用户 id 与会话上下文（具体格式由你设计——JSON / JWT / AES-256-GCM，详见 Token 指南）。

校验过期时间、签名（或解密）。

用 Token 内的用户 id 决定本次回调要返回哪个用户的视角——文件权限、协作者列表都跟着用户走。

4.2 场景二：石墨系统触发

你的应用要做的事：

用 appSecret 校验 JWT 签名（HS256）。

检查 exp 是否过期。

系统回调没有用户上下文——/admin/files/{fileId} 这类接口要返回文件本身的元信息和权限，不要试图按当前用户过滤。

五、你的应用如何校验凭证

Signature 校验逻辑在每个 Type 3 回调里都一样，下面给三语言示例。Token 因为格式由你的应用自己定，这里不重复——见 Token 指南。

5.1 Java（com.auth0:java-jwt）

<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>java-jwt</artifactId>
  <version>4.4.0</version>
</dependency>

5.2 Go（golang-jwt/jwt）

5.3 Python（PyJWT）

完整的 Signature 字段语义（appId / userId / fileId / scope / exp）见 Signature 指南。

六、回调接口清单

按业务用途分成 5 组，下面给出每组的页面目标和核心接口。接口前缀都是你在 更新应用回调地址 接口里配置的 endpoint_url，下表省略此前缀。

6.1 文件相关

接口	用途	凭证
`GET /files/{fileId}`	获取协同文档元信息（名称、类型、权限、创建者）	Token
`GET /files/{fileId}`	获取预览文件元信息（名称、下载地址）	Token
`GET /files`	当前用户的文件列表（用于跨表格公式选择文件等场景）	Token
`GET /files/{fileId}/collaborators`	协作者列表（用于评论同步、协作通知）	Token
`POST /files/{fileId}/url`	把石墨 SDK 跳转地址翻译回你的应用 URL	Token
`GET /admin/files/{fileId}`	文件元信息（系统任务，无用户上下文）	Signature
`GET /admin/files/{fileId}/by-user-id`	按指定用户查文件元信息（跨表格引用、表单订阅等）	Signature

permissions 字段非常关键——直接决定编辑器是否可读 / 可写 / 可评论 / 可导出 / 可管理。详见协同文档权限指南。

6.2 用户与水印

接口	用途	凭证
`GET /users/current/info`	当前用户信息（id、名称、头像）	Token
`GET /users/current/team`	当前用户所在团队	Token
`GET /users/{userId}`	指定用户信息	Token
`GET /users/{userId}/watermark`	用户水印字段（可返回空）	Token
`GET /users/{userId}/department-paths`	用户部门路径（可返回空）	Token
`POST /users/batch/get`	批量获取用户信息（多人协作侧栏）	Token
`POST /admin/users/batch/get`	批量获取用户信息（应用表格、表单等系统场景）	Signature

6.3 团队与部门

接口	用途	凭证
`GET /teams/{teamId}/members`	团队成员分页列表	Token
`GET /departments/{departmentId}`	部门信息	Token
`GET /departments/{departmentId}/children`	下级部门节点	Token
`GET /departments/{departmentId}/members`	部门成员分页列表	Token

如果你的业务里没有团队/部门概念，这一组可以返回空数组或 404——但要确保实现存在并返回合法 JSON，否则会触发 10011 错误。

6.4 搜索与 @ 补全

接口	用途	凭证
`GET /search/users/recent`	@ 人时的下拉候选（按文件维度推荐）	Token
`GET /search/users`	全局搜索用户	Token
`GET /search/files/recent`	跨表格引用时的文件候选	Token

6.5 事件推送

接口	用途	凭证
`POST /events`	评论、@、内容更新、协作状态、版本变化等事件	Token

事件类型由 Header X-WebOffice-Sdk-Event 区分（如 comment / mention_at / file_updated / collaborator_changed / revision_created）。详见事件推送回调。

七、设计与运维要点

7.1 返回约定

HTTP 状态码：只认 200。其他状态都会被判定为接入方实现异常（10010）。

Content-Type：所有请求与响应都是 application/json。

JSON 必须严格合法——多余字段会被忽略，但缺字段、类型错（如 views 写成字符串）会触发 10011 / 10012。

permissions 字段建议至少给文件创建者 manageable: true，否则后续删除、版本管理等接口会拒绝。

7.2 网络要求

回调地址必须石墨集群能访问——内网地址、需要 VPN 才能通的地址会触发 10001 / 10015。

地址通过 PUT /sdk/v2/api/license/apps/{appId}/endpoint-url 配置（详见后端 API · 概述）。

联调阶段如果只有内网地址，可以走本地开发与 Mock 回调里的内网穿透方案。

7.3 幂等与重试

事件推送（POST /events）可能因网络抖动或石墨侧重试出现重复——务必按事件 id 做幂等。

数据获取类回调（GET）天然幂等，但要注意：石墨会高频调用，响应耗时直接放大用户感知延迟——目标 P99 < 200ms。

长耗时操作放异步队列，回调本身只做"取数 + 返回"。

7.4 日志规范

每次回调至少落以下字段，便于和后端 API 调用串联：

请求时间、路径、HTTP 状态码、响应耗时

X-WebOffice-Credential-Type、当前用户 id、fileId

requestId（石墨在 Header 里带）

失败时把请求体、响应体一并落

八、常见误区

误区	实际影响	正确做法
把回调返回缓存到接入方侧	用户权限被回收后仍能编辑/预览	实时从业务库计算，回调里不要内置 TTL
`/admin/*` 接口按"当前用户"过滤数据	跨表格引用拉不到对方文件	系统回调与具体用户无关，按文件维度返回
用同一个 Token 校验逻辑同时处理 Type 0 / Type 3	Type 3 永远校验失败	先看 `X-WebOffice-Credential-Type`，再分支
团队/部门接口直接 404	触发 `10005`，编辑器侧栏白屏	返回空数组 `[]`，结构合法即可
`permissions` 全部默认 `true`	文档可被任意人删除/导出	按业务真实权限返回，至少给创建者 `manageable: true`
事件推送同步处理重业务	石墨侧超时重试，事件被重复处理	先 200 OK 入队，重业务异步消费
回调地址用了 HTTP（非 HTTPS）	生产环境被拦截或泄露 Token	生产环境必须 HTTPS
不校验 Signature 直接信任	任何人构造请求都能伪装石墨调用	Type 3 必须校验签名和 `exp`
Token 过期不清晰报错	编辑器卡在加载态	过期返回 401 + 明确 message，便于前端刷凭证重连

一、为什么必须有回调接口#

二、回调接口实现优先级#

三、整体机制#

四、回调接口请求凭证#

4.1 场景一：用户操作触发#

4.2 场景二：石墨系统触发#

五、你的应用如何校验凭证#

5.1 Java（com.auth0:java-jwt）#

5.2 Go（golang-jwt/jwt）#

5.3 Python（PyJWT）#

六、回调接口清单#

6.1 文件相关#

6.2 用户与水印#

6.3 团队与部门#

6.4 搜索与 @ 补全#

6.5 事件推送#

七、设计与运维要点#

7.1 返回约定#

7.2 网络要求#

7.3 幂等与重试#

7.4 日志规范#

八、常见误区#