本文档由 石墨办公 提供。
整体概述
appId + appSecret，但密钥只能放在您的应用后端，您的应用前端代码中请勿存储 appSecret。一、整体架构
| 接口类型 | 实现方 | 使用方 | 典型示例 |
|---|---|---|---|
| 前端 API（JS SDK） | 石墨 | 您的应用前端 | 唤起历史侧边栏、监听标题变更 |
| 后端 API | 石墨 | 您的应用后端 | 创建协同文件、读取文档纯文本 |
| 回调接口 | 您的应用 | 石墨 | 石墨向您的应用要用户信息 / 文件元信息 |
二、分组速览
/sdk/v2/api/（少数 collab-files/* 例外），表里省略以节省宽度。| 分组 | 页面目标 | 核心接口（HTTP + 路径） |
|---|---|---|
| 用户席位管理 | 用户列表、激活、取消、批量设置状态 | GET license/usersPOST license/users/activatePOST license/users/deactivatePOST license/users/set-status |
| 协同文档管理 | 创建、复制、删除协同文件 | POST filesPOST /sdk/v2/collab-files/{fileId}/copyDELETE files/{fileId} |
| 预览文件 | 访问预览页、创建预览缓存 | GET cloud-files/{fileId}/pagePOST cloud-files/{fileId}/create |
| 文档导入 | 创建导入任务、轮询进度 | POST files/v2/importPOST files/v2/import/progress |
| 文档导出 | 创建导出任务、轮询进度 | POST files/v1/export/{fileId}POST files/v1/export/progress |
| 表格内容操作 | 读取/写入/追加/删行、新增工作表 | GET files/{fileId}/sheets/valuesPOST/PUT files/{fileId}/sheets/valuesDELETE files/{fileId}/sheets/{sheetName}/rows/{index}POST files/{fileId}/sheets |
| 文档通用操作 | 纯文本、字数统计、历史、版本、@ 人 | GET /sdk/v2/collab-files/{fileId}/plain-textPOST /sdk/v2/collab-files/{fileId}/plain-text/wcGET /sdk/v2/collab-files/{fileId}/revisionsGET /sdk/v2/collab-files/{fileId}/mention-at-list |
| 评论与历史 | 评论数量、评论列表、版本列表 | GET /sdk/v2/collab-files/{fileId}/comment-countGET /sdk/v2/collab-files/{fileId}/comment-listGET /sdk/v2/collab-files/{fileId}/doc-sidebar-info |
| 传统文档书签 | 读取和替换书签内容 | GET files/{fileId}/documentpro/bookmark_contentPUT 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） |
/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 生成类错误 | 检查参数；偶现可忽略 |
| 协同文档类 | 文件不存在、权限不足等 | 查接口文档 |
status → 再看 message，三者结合 requestId 日志去定位。3.4 任务模型（异步接口）
3.5 幂等与重试
| 接口类型 | 幂等？ | 重试策略 |
|---|---|---|
查询类（GET *） | 是 | 网络层失败可直接重试 |
| 创建协同文件、创建导入任务 | 否 | 失败重试前必须先确认是否已落库；建议用业务事件 id 做去重 |
| 删除文件、激活/停用用户 | 终态幂等 | 第二次调用通常 ok，但需要校验返回结构 |
表格写入（POST/PUT sheets/values） | 视范围而定 | 改写同范围相对安全；追加 (append) 不幂等 |
3.6 限流与日志
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。requestId、当前用户 id 必落库。
修改于 2026-08-31 04:42:41