整体概述

业务系统里点击"新建 / 编辑文档"，到石墨编辑器在 iframe 里完整加载出来，中间会经过四个角色（用户、你的应用前端、你的应用后端、石墨文档中台）和若干次回调。本文把这条完整链路一次性讲清楚，给你的应用做集成时的"主线参照"。

一、整体架构

整个协同编辑接入跨越三个网络区域：用户、你的应用、石墨文档中台。三者之间只有特定的几条通信路径，箭头方向就是请求发起方向。

注意：

你的应用需要至少实现（/users/current/info 和 /files/{fileId}）这两个回调接口。

你的应用后端也需要能访问石墨文档中台接口。

你的应用前端 SPA、业务后端、石墨 iframe 需要支持用户浏览器访问。

这张图和下文第二节的时序图是同一件事的两种画法 —— 这里强调"经过哪些组件"，第二节强调"按时间发生的顺序"。

二、你的应用和石墨文档中台业务边界

协同编辑接入解决的是这样一件事：业务系统继续管文件入口、用户身份、业务权限；石墨提供编辑器、协同保存、评论、版本等文档能力。两边的边界很清晰：

你的应用负责	石墨负责
文件 `fileId` 的生成与持久化	编辑器 UI 与协同引擎
用户身份（当前用户回调）	多人协同冲突合并
业务权限（元信息回调返回的 `permissions`）	自动保存、历史版本、评论、@提醒
短期 `signature` 与 `token` 的签发	文档导出、模板等增值能力
前端 iframe 容器、JSSDK 初始化	iframe 内的全部交互

用图来表达就是这样：左半边的盒子是你的应用需要自己实现的，右半边是石墨已经提供的能力，中间三条线是两边交互的方式。

三、完整时序图

下图覆盖了"新建一个协同文档并打开"的全流程；如果是"打开已有文档"，第 4 步可以跳过。

下面按时序图的 5 个阶段逐步拆解。

3.1. 阶段 ①：业务后端准备 fileId 与凭证

fileId 由你的应用完全自决，要求是全局唯一且稳定。推荐做法：

普通业务文档：直接用业务系统的文档主键，例如 38291。或者使用 uuid 算法生成。

与预览共用 ID 的场景：注意预览缓存策略，详见预热预览缓存指南。

后端在这一步要落库的至少包括：

字段	用途
`fileId`	全链路串联标识
`name`	文档标题，回调时返回
`type`	`document` / `documentPro` / `spreadsheet` / `presentation` / `table` / `form`
创建者 ID	`获取文件元信息-协同文档` 回调接口返回，参与权限判断
业务权限	决定回调里 `permissions` 各字段如何返回

凭证部分会在阶段 ③ 详细讲；这里前端拿到的就是 fileId + signature + token 三件套。

3.2.阶段 ②：创建新文件

POST /sdk/v2/api/files 用于在石墨侧"登记"一个新的协同文档。只有新建时调用，打开已存在的文档不需要重复调用。

type 取值参考官方接口文档：

值	含义
`document`	轻文档
`documentPro`	传统文档（接近 Word）
`spreadsheet`	表格
`presentation`	幻灯片
`table`	应用表格
`form`	表单

成功响应是 HTTP 204 空响应体，幂等不严格保证 —— 业务侧需要确保同一个 fileId 不会被重复创建（推荐用数据库唯一索引或"创建前先查"）。

3.3.阶段 ③：签发 signature 和 token

这两个凭证职责完全不同，容易混。

signature：用 App ID + App Secret 生成的 JWT，石墨用它验证你的应用身份。结构：

// Header
{ "alg": "HS256", "typ": "JWT", "kid": "YOUR_APP_ID" }

// Payload
{ "exp": 1716800000 }   // 秒级时间戳，过期时间

Java 示例（官方文档中有完整代码）：

token：由你的应用自定义、自解析；你的应用用它识别"这次请求是哪个用户发起的"。石墨拿到后原封不动放到回调请求的 X-Shimo-Token Header 里转回来。

格式不限，推荐方案（详见官方 Token 文档）：

方案	安全性	适用
JSON 明文（含 `uid`）	低	仅开发 / 测试
JWT 签名（推荐）	中高	生产环境主力方案，注意 secret 与 signature 的不同
AES-256-GCM 加密	高	合规要求严苛的场景

Token 里必须包含足够定位用户的信息（最常用是 uid），其它字段可以作为"透传载荷"使用，例如 traceId 用来串联日志。

两个凭证都建议短期、按需签发：每次前端打开编辑器都向后端要一次，不要在前端长期缓存。

下图把两者的流向并排放在一起 —— signature 在石墨那一侧被消费、不再外传；token 则会被石墨原封不动转给你的应用自己的回调接口。

记忆口诀：signature 给石墨看，token 给自己看。

3.4. 阶段 ④：石墨回调你的接口

前端 connect 后，石墨文档中台会先回调你应用的接口获取必要的数据。这两个接口你的应用必须实现并对石墨服务端可达，否则编辑器加载会直接失败。

回调 [获取当前用户] 接口

GET {endpoint_url}/users/current/info
Header: X-Shimo-Token: <前端传入的 token>

你的应用根据 token 解出用户 ID，返回：

{
  "id": "userid123",
  "name": "张三",
  "avatar": "https://example.com/user-123.png",
  "email": "user123@example.com",
  "teamGuid": "123"
}

回调 [获取文件信息（协同）] 接口

GET {endpoint_url}/files/{fileId}
Header: X-Shimo-Token: <前端传入的 token>

你的应用根据 token（识别用户）+ fileId 查业务库，返回：

{
  "id": "doc_38291",
  "name": "Q3 战略规划",
  "type": "documentPro",
  "permissions": {
    "readable": true,
    "editable": true,
    "commentable": true,
    "copyable": true,
    "exportable": true,
    "manageable": false
  },
  "creatorId": "userid123",
  "createdAt": "2026-04-01T08:00:00Z",
  "updatedAt": "2026-04-02T09:30:00Z",
  "teamGuid": "123"
}

关于 permissions 字段的几个要点：

editable: true 时 copyable 必须为 true。

文档创建者建议给 manageable: true，影响删除、版本管理、表格锁定等行为，详见获取文件元信息-协同文档。

协同文档的元信息回调和预览文档共用同一个 URL，需要按 type 字段区分返回逻辑（type: file 走预览分支，其它走协同分支）。

四、新建协同文件 vs 打开已有协同文件

两条路径只在第 ② 步有差异，其余完全一致。拆成两个独立流程看会更清楚：

新建协同文件

打开已有协同文件

一、整体架构#

二、 你的应用和石墨文档中台业务边界#

三、完整时序图#

3.1. 阶段 ①：业务后端准备 fileId 与凭证#

3.2.阶段 ②：创建新文件#

3.3.阶段 ③：签发 signature 和 token#

3.4. 阶段 ④：石墨回调你的接口#

回调 [获取当前用户] 接口#

回调 [获取文件信息（协同）] 接口#

四、新建协同文件 vs 打开已有协同文件#