整体概述

后端 API 是你的应用后端主动调用石墨的接口集合。前端 JS SDK 是"在浏览器里把石墨编辑器嵌进来"的入口；后端 API 则是"在浏览器之外创建、复制、导入、导出、读写文件"的入口。两条链路共用同一对 appId + appSecret，但密钥只能放在你的应用后端，你的应用前端代码中请勿存储 appSecret。

一、整体架构

三类接口的角色对比（出自接口文档概览）：

接口类型	实现方	使用方	典型示例
前端 API（JS SDK）	石墨	你的应用前端	唤起历史侧边栏、监听标题变更
后端 API	石墨	你的应用后端	创建协同文件、读取文档纯文本
回调接口	你的应用	石墨	石墨向你的应用要用户信息 / 文件元信息

二、分组速览

后端 API 总共拆成 10 个分组，下表给出每组的页面目标和核心接口入口。所有路径前缀均为 /sdk/v2/api/（少数 collab-files/* 例外），表里省略以节省宽度。

分组	页面目标	核心接口（HTTP + 路径）
应用管理	获取应用详情、更新应用回调地址	`GET license/apps/{appId}` `PUT license/apps/{appId}/endpoint-url`
用户席位管理	用户列表、激活、取消、批量设置状态	`GET license/users` `POST license/users/activate` `POST license/users/deactivate` `POST license/users/set-status`
协同文档管理	创建、复制、删除协同文件	`POST files` `POST /sdk/v2/collab-files/{fileId}/copy` `DELETE files/{fileId}`
预览文件	访问预览页、创建预览缓存	`GET cloud-files/{fileId}/page` `POST cloud-files/{fileId}/create`
文档导入	创建导入任务、轮询进度	`POST files/v2/import` `POST files/v2/import/progress`
文档导出	创建导出任务、轮询进度	`POST files/v1/export/{fileId}` `POST files/v1/export/progress`
表格内容操作	读取/写入/追加/删行、新增工作表	`GET files/{fileId}/sheets/values` `POST/PUT files/{fileId}/sheets/values` `DELETE files/{fileId}/sheets/{sheetName}/rows/{index}` `POST files/{fileId}/sheets`
文档通用操作	纯文本、字数统计、历史、版本、@ 人	`GET /sdk/v2/collab-files/{fileId}/plain-text` `POST /sdk/v2/collab-files/{fileId}/plain-text/wc` `GET /sdk/v2/collab-files/{fileId}/revisions` `GET /sdk/v2/collab-files/{fileId}/mention-at-list`
评论与历史	评论数量、评论列表、版本列表	`GET /sdk/v2/collab-files/{fileId}/comment-count` `GET /sdk/v2/collab-files/{fileId}/comment-list` `GET /sdk/v2/collab-files/{fileId}/doc-sidebar-info`
传统文档书签	读取和替换书签内容	`GET files/{fileId}/documentpro/bookmark_content` `PUT files/{fileId}/documentpro/bookmark_content`

各分组的字段语义、错误码、可选参数详见原 co18-08-0X-*.md 系列文档，这里只列入口。

三、通用规范

3.1 请求基础

项目	取值
URL 前缀	`/sdk/v2/api/`（少数走 `/sdk/v2/collab-files/`）
域名	由石墨按环境派发，联调和生产不同，不要混用
协议	HTTP/HTTPS，Body 与响应均 `application/json`（导入文件 multipart 例外）
URL 占位符	`{fileId}`、`{appId}` 等需在调用时替换为真实值

3.2 鉴权凭证 Signature 和 Token

Header	何时必填	作用
`X-WebOffice-Signature`	绝大多数后端 API 必填	应用级身份凭证，HS256 签名的 JWT，详见 Signature 指南
`X-WebOffice-Token`	与用户上下文相关的接口（创建文件、读写内容、导入导出等）必填	业务会话凭证，由你的应用自行签发并解析，详见 Token 指南
`X-WebOffice-Credential-Type`	回调侧识别使用	`0` = 用户触发（带 Token），`3` = 系统触发（仅 Signature）

特殊场景：

License / /admin 类接口（应用管理、用户席位管理、部分系统级接口）：签发 Signature 时必须带 scope: "license"，且 exp ≤ 4 分钟。

某些预览接口（如 POST cloud-files/{fileId}/create）Signature / Token 不强制——按各接口文档为准。

3.3 错误处理

返回总是 { status, message, data } 结构，status != 0 即异常。常见错误码族（详见原错误码说明）：

错误码段	含义族	典型动作
`10001 ~ 10015`	接入方对接错误（回调实现问题、JSON 不合法、网络不通）	检查你的应用回调接口实现
`20001 ~ 20005`	应用管理类错误	检查 `appId`、参数
`30001 ~ 30008`	账号 / Token 生成类错误	检查参数；偶现可忽略
协同文档类	文件不存在、权限不足等	查接口文档

排查顺序：先看 HTTP 状态码 → 再看 status → 再看 message，三者结合 requestId 日志去定位。

3.4 任务模型（异步接口）

导入、导出、预览缓存都是异步任务：

创建接口成功 ≠ 任务成功，只代表石墨收到请求并开始处理。

任务最长执行时间通常为 10 分钟（导出）。

轮询间隔建议 1～3 秒指数退避，避免风暴。

3.5 幂等与重试

接口类型	幂等？	重试策略
查询类（`GET *`）	是	网络层失败可直接重试
创建协同文件、创建导入任务	否	失败重试前必须先确认是否已落库；建议用业务事件 id 做去重
删除文件、激活/停用用户	终态幂等	第二次调用通常 ok，但需要校验返回结构
表格写入（`POST/PUT sheets/values`）	视范围而定	改写同范围相对安全；追加 (`append`) 不幂等

3.6 限流与日志

石墨侧对接入应用有 QPS 限制（具体限额按环境配置），高频写入接口（导入、写表格）尤其要控并发。

日志至少落：URL、参数摘要、HTTP 状态、status、message、requestId、耗时、当前用户 id。失败时把请求体和响应体一并落，便于事后排查。

四、调用示例（cURL）

下面四条链路覆盖了"接入第一周最常打到的接口"，以供参考。{ENDPOINT} 是石墨给的环境域名；{SIG}、{TOKEN} 是按 Signature 指南 / Token 指南生成的字符串。

4.1 获取应用详情（验证联调环境）

返回里能看到 appName、availableFileTypes、memberLimit、validUntil、endpointUrl——拿到这个就证明你的 appId / secret / endpoint 三件套对得上。

4.2 创建协同文件

type 可选：document / documentPro / spreadsheet / presentation / table。fileId 是你的业务侧文件 id——石墨用它来回调你拿元信息和权限。

4.3 创建导入任务 + 轮询

progress = 100 且 status = 0 即导入完成，响应里会带回石墨侧的新 fileId。详细链路见导入导出指南。

4.4 创建导出任务 + 下载

4.5 用户席位激活

status 字段约定：1 已激活 / 0 禁用 / -1 未启用。批量操作建议用 POST license/users/set-status 直接指定目标状态。

五、接入建议

把 appId + appSecret 存储在你的应用后端，不要进代码仓库或者前端代码中存储 appSecret。

实现最小回调集（GET /files/{fileId} 协同文档元信息 + GET /users/current/info），否则会频繁出现 10002 / 10003。

用 Signature 在线工具先把 Signature 跑通；用 §4.1 调用一次"获取应用详情"作为冒烟测试。

建立调用日志规范：URL、状态码、requestId、当前用户 id 必落库。

异步任务（导入、导出、预览缓存）做幂等键和最长轮询时长保护。

上线前把所有用到的后端接口加入联调清单，跑一遍最小链路验证。

一、整体架构#

二、分组速览#

三、通用规范#

3.1 请求基础#

3.2 鉴权凭证 Signature 和 Token#

3.3 错误处理#

3.4 任务模型（异步接口）#

3.5 幂等与重试#

3.6 限流与日志#

四、调用示例（cURL）#

4.1 获取应用详情（验证联调环境）#

4.2 创建协同文件#

4.3 创建导入任务 + 轮询#

4.4 创建导出任务 + 下载#

4.5 用户席位激活#

五、接入建议#