整体概述

导入用于把外部 Office 文件转换成石墨协同文件；导出用于把石墨协同文件输出为 docx / xlsx / pdf 等格式。两者都是异步任务：接口请求成功只代表任务已经被石墨接收，实际成败必须靠轮询进度接口。本文按"先理解任务模型、再画完整流程、最后讲异常和迁移"的顺序，把这套接口讲清楚。

一、整体架构

导入和导出有三个共同特征：

异步任务模型。创建任务的接口立刻返回 taskId，业务侧拿着 taskId 轮询进度接口直到 progress == 100（或 status != 0 失败）。

格式有强约束。每种石墨文件类型 (document / documentPro / spreadsheet / presentation / table) 都有自己支持的导入 / 导出格式表，进去之前先对照表确认。

超时是硬上限。任务最长执行时间 10 分钟、导出下载链接有效期 5 分钟、进度长时间不变（≥30 分钟）视为失败。这三条线决定了你的轮询和重试策略。

业务库写入与石墨接口调用要按顺序编排：业务侧先建任务记录，再调石墨，最后落终态。

失败时保留任务上下文（taskId、源文件、目标类型、错误码），便于排查和重试。

二、导入文件

2.1 接口定义

POST /sdk/v2/api/files/v2/import
Header:        X-Shimo-Signature, X-Shimo-Token
Content-Type:  multipart/form-data
Body fields:
  fileId         必填  你的应用文件唯一 ID
  type           必填  目标石墨文件类型
  fileUrl        必填  源文件下载地址（石墨服务端可访问）
  fileName       必填  文件名
  importFontType 否    1 = 把"等线"字体转为默认字体

成功响应：

{ "status": 0, "message": "", "data": { "taskId": "..." } }

status != 0 表示创建失败，按 message 排查。

导入支持的格式：

石墨文件类型	支持导入
document	.docx, .doc, .md, .txt
documentPro	.docx, .doc, .wps
spreadsheet	.xlsx, .xls, .csv, .xlsm
presentation	.pptx, .ppt

注意点：

不支持 0kb 文件。请求前业务侧先校验 fileUrl 的内容长度。

fileUrl 必须公网或同网络可达。石墨服务端要去拉取，不可达就直接失败。

fileId 不可复用。同一个 fileId 不能被两次导入覆盖；要重新导入，请用新的 fileId。

2.2 查询进度

POST /sdk/v2/api/files/v2/import/progress
Body: { "taskId": "<上一步返回的 taskId>" }

响应字段：

字段	含义
`status`	任务状态，`0` 正常，非 0 表示失败（`data` 此时为 null）
`data.progress`	进度百分比，`100` 表示完成
`message`	异常时的提示

2.3 完整流程

要点：

业务库先建一条 importing 记录，再调石墨。失败时业务库有明确的中间态可以查、可以补偿。

导入完成前不要让用户打开新 fileId，否则用户会看到空文档。前端应在 status='ready' 时再开放访问。

轮询用同一个 taskId，间隔不少于 3 秒，配合指数退避；总超时建议 10–15 分钟（不超过石墨 10 分钟硬上限太多）。

2.4 cURL 示例

2.5 与模板功能的关系

把外部模板（docx / xlsx / pptx）一次性导入为石墨协同文件并标记为"模板"后，后续业务实例可以通过复制接口套用模板。"导入 → 模板入库 → 复制"是模板功能的完整链路，参见文档模板功能。

三、导出文件

3.1 接口定义

POST /sdk/v2/api/files/v1/export/{fileId}
Header:        X-Shimo-Signature, X-Shimo-Token
Content-Type:  application/json
Body:
  type           必填  目标导出格式
  exportSheetId  否    已废弃，导出 spreadsheet 为 csv 时曾用

成功响应：

{ 
  "status": 0, 
  "message": "", 
  "data": { 
    "taskId": "3oo4vnBJgcG5HxMm:1:603:docx"
  }
}

导出支持的格式：

石墨文件类型	默认导出	支持导出
document	docx	docx, md, jpg, pdf
documentPro	docx	docx, pdf, wps
spreadsheet	xlsx	xlsx
presentation	pptx	pptx, pdf
table	xlsx	xlsx

注意点：

同一文件可并发导出为多种格式。例如同时导出 PDF 和 docx 各一份，互不干扰。

任务最长 10 分钟。超过这个时间任务被服务端终止。

不要在 taskId 里包含敏感语义。taskId 由石墨生成，用作幂等键即可。

3.2 查询进度

POST /sdk/v2/api/files/v1/export/progress
Body: { "taskId": "<上一步返回的 taskId>" }

响应字段：

字段	含义
`status`	任务状态，`0` 正常，非 0 失败
`data.progress`	进度，`100` 完成
`data.downloadUrl`	文件下载地址（完成后才有）

两条硬性约束：

downloadUrl 有效期 5 分钟。超过后失效，需要再次调用进度接口拿新地址（同一 taskId 仍有效）。

进度 ≥30 分钟未变化 视为任务失败。停止轮询、记录失败原因、用新的请求重建任务。

3.3 完整流程

要点：

拿到 downloadUrl 后要在 5 分钟内消费掉。常见做法：后端立即转存到对象存储，再把对象存储链接返回前端，避免把临时下载链接直接暴露给用户。

导出任务幂等性靠 taskId。重复调用 /export/{fileId} 同一 type 会得到不同 taskId，业务侧需要自己去重（例如基于 fileId + type + 触发时间窗）。

3.4 cURL 示例

四、异常与重试

4.1 导出任务状态机

4.2 上线检查项

轮询有总超时（建议导入 ≤15 分钟、导出 ≤30 分钟），不要无限循环。

批量场景有并发上限，避免把任务队列打爆。

失败日志记录 taskId / fileId / type / 文件大小 / message，便于事后排查。

导出归档统一存到对象存储，不把 downloadUrl 直接暴露给前端（链接 5 分钟过期且无防盗链能力）。

一、整体架构#

二、导入文件#

2.1 接口定义#

2.2 查询进度#

2.3 完整流程#

2.4 cURL 示例#

2.5 与模板功能的关系#

三、导出文件#

3.1 接口定义#

3.2 查询进度#

3.3 完整流程#

3.4 cURL 示例#

四、异常与重试#

4.1 导出任务状态机#

4.2 上线检查项#