调用接口返回 405 Method Not Allowed 怎么办？

通常是 openapi 静态页使用相对路径，请求发到了静态服务端口。请在环境配置中显式配置后端服务地址。

调用接口返回 401 Unauthorized 怎么办？

端到端导入等接口需要 Token，请确认访问 Token 有效且未过期。

提示无权限访问文档怎么办？

确认新文档权限为 edit 或 Token 对应文档 owner，同时确认编辑器链接里的 api 参数指向同一个后端。

测试结果闪现后消失是什么原因？

Live Server 可能监听后端写入文件并刷新页面，页面会用 localStorage 自动恢复上次结果。

JitWord OpenAPI 文档 — DOCX 导入导出 · 模板批量合成

快速开始

从上传 DOCX 到打开在线编辑器，推荐按以下步骤完成首次联调。

1. 获取 Token使用系统登录接口或已有登录态获取 JWT。

2. 配置地址填写后端 API 地址和编辑器访问地址。

3. 上传导入调用端到端导入接口生成 documentId。

4. 打开编辑器通过返回链接进入在线文档编辑页面。

环境配置

配置项会保存到浏览器 localStorage，便于重复测试。独立静态服务运行在 5500 端口时，必须显式配置后端地址。

后端服务地址

用于拼接 /api/v1 接口请求。

编辑器地址

用于生成文档编辑器访问链接。

访问 Token

端到端导入和私有文档访问需要 Token。

导入文档权限

企业生产环境建议使用 private，测试体验建议使用 edit。

当前编辑器链接会自动携带 token 和 api 参数，确保编辑器访问与导入接口使用同一个后端。

鉴权说明

需要用户身份的接口应在请求头中携带 JWT，服务端会使用 token 绑定文档 owner。

位置	格式	说明
Header	`Authorization: Bearer <token>`	导入、导出、文档列表、文档信息、开放文档数据、版本管理列表、修订记录和批注数据接口需要。
登录白名单	`IP / CIDR / Domain`	管理员可在入口页“开放接入”限制注册/登录来源；关闭或规则为空时默认放行。
同域登录态	`localStorage.jwt_token`	本文档页与编辑器同源部署时，若未手动填写 Token，会自动复用编辑器登录态，无需重复粘贴。
编辑器链接	`?token=<token>&api=<apiBase>`	编辑器打开后会写入本地登录态，并清理 URL 参数。

注册与登录

开放认证接口复用系统现有用户体系，登录成功后返回 JWT，后续接口使用同一 Token。

POST

接口	请求体	说明
/api/v1/user/register	`{ "username": "demo", "password": "123456" }`	注册成功即返回 token，可能受登录白名单限制。
/api/v1/user/login	`{ "username": "demo", "password": "123456" }`	登录成功返回 `data.token`。

用户名

密码

curl -X POST "http://localhost:3002/api/v1/user/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}'

curl -X POST "http://localhost:3002/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}'

我的文档列表

获取当前登录用户拥有的文档列表，普通用户默认只能查询自己的文档。

GET

/api/v1/documents?filter=active&scope=mine

curl -X GET "http://localhost:3002/api/v1/documents?filter=active&scope=mine" \
  -H "Authorization: Bearer <token>"

DOCX 导入并创建文档

推荐接入接口。上传 DOCX 后，服务端完成解析、创建文档、写入内容、落库批注，并返回 documentId。

POST

/api/v1/parse/docx-v2-import

业务价值

适用场景

一键导入 Word

合同、公文、方案、知识库文档迁移。

输出结果

在线文档 ID

可直接拼接编辑器地址打开。

权限策略

Token 绑定 owner

支持 private/read/edit 三类访问权限。

请求参数

字段	类型	必填	说明
file	file	是	DOCX 文件，字段名固定为 file。
publicPermission	string	否	private/read/edit。测试页默认使用 edit。
name	string	否	文档名称，不传时使用文件名。

选择 DOCX 文件

点击选择或拖拽文件到此区域

DOCX

文档创建成功

在编辑器中打开文档

curl -X POST "http://localhost:3002/api/v1/parse/docx-v2-import" \
  -H "Authorization: Bearer <token>" \
  -F "file=@demo.docx" \
  -F "publicPermission=edit"

Excel 导入并创建表格

上传 XLSX 后，服务端解析为表格快照、创建 sheet 类型文档，并返回可直接打开的 Excel 编辑器链接。

POST

/api/v1/parse/excel-v2-import

业务价值

适用场景

一键导入 Excel

表格资料、统计报表、台账迁移。

输出结果

表格文档 ID

自动进入 /sheet/{documentId} 编辑页面。

数据格式

Univer 快照

复用现有表格编辑、保存和协作链路。

请求参数

字段	类型	必填	说明
file	file	是	Excel 文件，字段名固定为 file，推荐 .xlsx。
publicPermission	string	否	private/read/edit。测试页默认使用 edit。
name	string	否	表格名称，不传时使用文件名。

选择 Excel 文件

点击选择或拖拽 .xlsx 文件到此区域

Excel

表格创建成功

在 Excel 编辑器中打开表格

curl -X POST "http://localhost:3002/api/v1/parse/excel-v2-import" \
  -H "Authorization: Bearer <token>" \
  -F "file=@demo.xlsx" \
  -F "publicPermission=edit"

DOCX 高保真解析

只解析不创建文档，返回 JitWord JSON、解析摘要、诊断报告和 Word 批注信息。

POST

/api/v1/parse/docx-v2

能力	说明
结构解析	正文、标题、表格、列表、制表位、样式等。
公式解析	支持 OMML 公式转换。
适用方式	适合调用方自行保存文档内容或做解析质量检查。

DOCX 转 HTML

基础 HTML 解析能力，适合轻量预览或兼容旧接入方式。

POST

接口	说明	鉴权
/api/v1/parse/doc2html	返回完整 HTML。	免登录
/api/v1/parse/doc2html2	分页 HTML 解析，返回 docId 和页数。	免登录

按文档 ID 导出 DOCX

根据已经存在的在线文档 ID 导出 Word 文件。

GET

/api/v1/export/docx/{docId}

选择我的文档

会根据当前 Token 查询当前用户的文档列表。

文档 ID

按 JSON 内容导出 DOCX

调用方直接提交编辑器 JSON 内容，服务端生成并返回 Word 文件。

POST

/api/v1/export/docx

{
  "content": { "type": "doc", "content": [] },
  "filename": "demo.docx",
  "documentId": "可选，用于加载批注"
}

该接口更适合系统到系统集成。在线测试建议先使用“按文档 ID 导出”。

按文档 ID 导出 PDF

根据已经存在的在线文档 ID，在服务端渲染并导出 PDF 文件。

GET

/api/v1/export/pdf/{docId}

要点	说明
返回内容	`application/pdf` 字节流，`Content-Disposition` 携带以文档名命名的文件名。
渲染机制	服务端无头浏览器复用编辑器打印管线，产物与前端「打印 → 另存为 PDF」一致。
耗时	同步渲染返回，常规数秒，大文档最长约 90 秒；依赖渲染服务（browser-service）在线，经网关接入时读超时建议 ≥120 秒。
常见错误	404 文档不存在｜ 403 无权限｜ 429 导出繁忙｜ 503 渲染服务未启动｜ 504 渲染超时。

选择我的文档

会根据当前 Token 查询当前用户的文档列表。

文档 ID

curl -X GET "http://localhost:3002/api/v1/export/pdf/<documentId>" \
  -H "Authorization: Bearer <token>" \
  -o export.pdf

指定文档信息

根据文档 ID 获取文档元信息、页眉页脚、内容存在状态和当前 Token 对该文档的权限信息。

GET

/api/v1/documents/{documentId}

字段	说明
id / name / type	文档唯一 ID、名称和类型，普通文档默认 type 可为空或 doc。
ownerId / ownerName	文档所有者信息，用于业务系统做归属映射。
publicPermission	`private`、`read` 或 `edit`。
headerFooter	页眉页脚配置数据；没有配置时为 `null`。
hasContent	服务端是否已存储真实正文内容。
_userPermission	当前 Token 对文档的访问、编辑、批注权限。

文档 ID

curl -X GET "http://localhost:3002/api/v1/documents/<documentId>" \
  -H "Authorization: Bearer <token>"

指定文档数据

统一读取普通文档、表格、思维导图的数据正文，服务端会复用现有文档权限判断。

GET

/api/v1/open/documents/{documentId}/data

字段	说明
document	裁剪后的文档元信息，包含 id、name、type、owner、权限和时间。
permission	当前 Token 对此文档的访问权限。
contentType	`doc`、`sheet` 或 `mindmap`。
content	正文数据；暂无内容时为 `null` 并返回明确 message。

文档 ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/data" \
  -H "Authorization: Bearer <token>"

版本管理列表

获取指定文档的历史版本列表（只返回版本元数据，不包含正文），服务端复用现有文档权限判断。

GET

/api/v1/open/documents/{documentId}/versions?page=1&limit=20

字段	说明
document	裁剪后的文档元信息（id、name、type、owner、权限和时间）。
permission	当前 Token 对此文档的访问权限。
versions	当页版本列表，每条包含 id、title、description、isAutoSave、author、createdAt、size 等元数据；不含版本正文 content。
total / page / limit	总条数与分页参数。

版本正文内容不在此接口返回。私有文档仅所有者和管理员可访问。

文档 ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/versions?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

修订记录与批注数据

读取指定文档的审阅相关数据：修订接口返回正文中的修订标记（插入/删除/格式修改，与编辑器审阅面板同口径），批注接口返回划词评论数据；在线测试会并行请求两个接口并合并展示。

GET

/api/v1/open/documents/{documentId}/revisions

/api/v1/comments?documentId={documentId}

接口	参数	说明
`/api/v1/open/documents/{documentId}/revisions`	无	获取修订记录（tracked changes）：同一修订的多段文本归并为一条，含类型、作者、时间、文本片段及汇总统计。注意与「版本管理列表」、编辑历史是不同的数据。
`/api/v1/comments`	`documentId`	获取该文档批注与回复数据，包含批注内容、引用文本、作者和扩展字段。

说明：修订记录接口与开放文档数据接口权限一致（可访问文档即可读取）；私有文档仅所有者/管理员可读。仅 doc 类型文档支持修订。

文档 ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/revisions" \
  -H "Authorization: Bearer <token>"

curl -X GET "http://localhost:3002/api/v1/comments?documentId=<documentId>" \
  -H "Authorization: Bearer <token>"

创建文档

创建一篇新文档，可选携带初始正文内容（ProseMirror JSON）。创建成功后返回文档 ID，可用于后续保存、导出、删除等操作。

POST

/api/v1/open/documents

请求参数（JSON Body）

字段	类型	必填	说明
`name`	string	是	文档名称
`type`	string	否	文档类型：`doc`（默认）/ `sheet` / `mindmap`
`content`	object	否	初始正文（ProseMirror JSON，仅 type=doc 时生效），形如 `{"type":"doc","content":[...]}`
`publicPermission`	string	否	文档权限：`private`（默认，私有）/ `read`（公开只读）/ `edit`（公开可编辑）

创建成功后可用 GET /api/v1/open/documents/{id}/data 读取完整正文，或用 PUT /api/v1/open/documents/{id}/content 更新正文。

文档名称

文档类型

curl -X POST "http://localhost:3002/api/v1/open/documents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"开放平台测试文档","type":"doc"}'

保存文档内容

通过 REST 接口直接写入文档正文（ProseMirror JSON）。适用于程序化生成文档内容、批量导入等场景。

PUT

/api/v1/open/documents/{documentId}/content

请求参数（JSON Body）

字段	类型	必填	说明
`content`	object	是	标准 ProseMirror JSON，顶层 type 必须为 `"doc"`，content 为节点数组

重要：若文档正在被在线编辑器打开（存在活跃协同连接），接口将返回 409 Conflict 拒绝写入，以避免覆盖用户实时编辑。请确保无用户在线编辑时再调用此接口。

文档 ID

正文 JSON

curl -X PUT "http://localhost:3002/api/v1/open/documents/<documentId>/content" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}]}}'

设置文档权限

修改指定文档的公开权限。支持三级权限：私有（仅所有者/管理员可见）、公开只读、公开可编辑。仅文档所有者或管理员可操作。

PUT

/api/v1/open/documents/{documentId}/permission

请求参数（JSON Body）

字段	类型	必填	说明
`publicPermission`	string	是	目标权限：`private`（私有）/ `read`（公开只读）/ `edit`（公开可编辑）

权限说明

权限值	效果
`private`	仅文档所有者和管理员可见、可编辑
`read`	任何已登录用户可查看，仅所有者/管理员可编辑
`edit`	任何已登录用户可查看并编辑

也可在创建文档时通过 publicPermission 参数直接指定初始权限，无需额外调用此接口。

文档 ID

目标权限

curl -X PUT "http://localhost:3002/api/v1/open/documents/<documentId>/permission" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"publicPermission":"edit"}'

删除文档

软删除指定文档（移入回收站）。仅文档所有者或管理员可操作，模板文档不允许通过此接口删除。

DELETE

/api/v1/open/documents/{documentId}

路径参数

字段	类型	说明
`documentId`	string	要删除的文档 ID

删除为软删除（移入回收站），文档数据不会立即清除。仅文档所有者或管理员可删除；公共文档仅管理员可删。

文档 ID

curl -X DELETE "http://localhost:3002/api/v1/open/documents/<documentId>" \
  -H "Authorization: Bearer <token>"

模板批量合成 · 能力概览

用「一个模板 + 一组变量数据」批量生成合同、通知书、证书、报告等文档。鉴权复用现有 JWT，无需额外接入成本。

需要 Token

适用场景

文档批量生产

合同、录用/通知书、证书、报告等标准化文档批量出稿。

两种产物

在线文档 / JSON

output=doc 落库并返回 docId 与编辑器链接；output=json 直接返回合成后的 ProseMirror JSON，不落库。

可用模板范围

公开 + 本人

公开模板任何登录用户可用；私有模板仅创建者或管理员可用。

联调流程

1. 拉取模板GET /open/templates 获取可合成模板列表。

2. 读取变量选择模板后查看其变量结构（字段/类型/必填）。

3. 填写数据按变量结构填写一行或多行数据。

4. 合成文档单篇或批量合成，得到 docId 与编辑器链接。

所有模板接口均挂在 /api/v1/open/templates 命名空间下，自动受 JWT 保护。请先在「环境配置」中填写后端地址与访问 Token（可在「注册与登录」中一键获取）。

模板列表

列出当前 Token 可用于合成的模板。可按 scope 过滤，并可附带变量结构。

GET

/api/v1/open/templates?scope=official&withVariables=1

请求参数

参数	类型	必填	说明
scope	string	否	不传=全部可见模板；`official`=公开模板；`mine`=本人创建的模板。
withVariables	string	否	传 `1` 时每项附带完整 variables 变量结构，便于直接生成填写骨架。

返回字段

字段	说明
id / title / category / desc	模板 ID、标题、分类与描述。
variableCount / hasVariables	变量数量与是否含变量。
public	是否为公开模板。
updatedAt / variablesUpdatedAt	模板与变量的更新时间。

模板范围 scope

将根据当前 Token 拉取可合成模板，并自动填入下方各测试面板。

curl -X GET "http://localhost:3002/api/v1/open/templates?withVariables=1" \
  -H "Authorization: Bearer <token>"

模板变量结构

查看指定模板的变量定义（字段名、类型、是否必填、枚举），据此组织合成数据。

GET

/api/v1/open/templates/{templateId}/variables

字段	说明
templateId / title	模板 ID 与标题。
variables	变量定义数组，每项含 key、label、type、required、defaultValue、options 等（扁平，向后兼容）。
schema	结构化变量描述：`scalars`（顶层标量变量）、`tables`（循环表格，按 `tableId` 分组，含列清单与示例行）、`example`（可直接提交的 values 骨架）。
variablesUpdatedAt	变量结构最近更新时间。

变量 type 取值：text、number、date、select、image、signature、seal、tableColumn。

循环表格变量（tableColumn）不是字符串，也不作为 values 顶层字段；它以所在表格的 tableId 为 key，值为「行对象数组」——每行一个对象，字段名对应列 key。请直接参考 schema.example / schema.tables 组织数据。

选择模板

curl -X GET "http://localhost:3002/api/v1/open/templates/<templateId>/variables" \
  -H "Authorization: Bearer <token>"

单篇合成

用一组变量数据合成一份文档。默认创建在线文档并返回 docId 与编辑器链接；也可只返回合成后的 JSON。

POST

/api/v1/open/templates/{templateId}/generate

请求参数

字段	类型	必填	说明
values	object	是	变量键值对。标量变量直接用变量 key；循环表格变量以 `tableId` 为 key，值为行对象数组（见变量结构的 schema.example）。
unfilledStrategy	string	否	未填变量处理：`default`（默认值）、`empty`（留空）、`keepPlaceholder`（保留占位符）。
name	string	否	生成文档名称，不传时使用模板标题。
output	string	否	`doc`（默认，落库并计入配额）或 `json`（仅返回内容，不落库、不计配额）。

output=doc 会占用当前用户的文档配额（管理员豁免）；仅需内容用于服务端渲染/导出时建议使用 output=json。

模板 ID

变量数据 values（JSON 对象）

未填策略

产物 output

文档名称（可选）

合成成功

curl -X POST "http://localhost:3002/api/v1/open/templates/<templateId>/generate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"values":{},"output":"doc"}'

批量合成

用一个模板 + 一组行数据批量生成多篇文档。单次最多 200 条，单条失败不影响其它条。

POST

/api/v1/open/templates/{templateId}/batch-generate

请求参数

字段	类型	必填	说明
items	array	是	数据行数组，每项 `{ name?, values, unfilledStrategy? }`，最多 200 条。
output	string	否	`doc`（默认）或 `json`。
stopOnError	boolean	否	为 `true` 时首个失败即停止后续；默认 false（尽力全部处理）。

返回结构

字段	说明
summary	`{ total, success, failed }` 统计。
results	逐条结果：`{ index, status, docId?, name?, url?, content?, message? }`。

案例：用一个「通知书 / 合同」模板 + 多行数据一次生成多篇文档，results 中每条成功项都带 docId 与编辑器链接。

模板 ID

数据行 items（JSON 数组）

产物 output

遇到失败立即停止（stopOnError）

JS fetch 示例

const res = await fetch(`${API}/api/v1/open/templates/${templateId}/batch-generate`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    output: 'doc',
    items: [
      { name: '张三-录用通知书', values: { 姓名: '张三' } },
      { name: '李四-录用通知书', values: { 姓名: '李四' } },
    ],
  }),
});
const { data } = await res.json();
console.log(data.summary, data.results);

curl -X POST "http://localhost:3002/api/v1/open/templates/<templateId>/batch-generate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"output":"doc","items":[{"values":{}}]}'

核心字段

接入时最常用的数据字段说明。

字段	含义	建议
documentId	在线文档唯一 ID。	保存到业务系统，用于打开、导出、协作。
publicPermission	访问权限：private/read/edit。	生产建议 private；演示测试可用 edit。
ownerId	文档所有者用户 ID。	应与导入 Token 中的 id 一致。
api	编辑器运行时 API 地址。	跨域/独立部署时必须保持与上传后端一致。

常见问题

联调中最常见的错误与排查方式。

405 Method Not Allowed

通常是 openapi 静态页使用相对路径，请求发到了 5500 端口。请配置后端地址。

401 Unauthorized

端到端导入需要 Token，请确认访问 Token 有效且未过期。

提示无权限访问文档

确认新文档权限为 edit 或 token 对应 owner；同时确认编辑器链接里的 api 指向同一个后端。

结果闪现后消失

Live Server 可能监听后端写入文件并刷新页面。当前页面会用 localStorage 恢复上次结果。

JitWord 文档处理开放接口

快速开始

环境配置

鉴权说明

注册与登录

我的文档列表

DOCX 导入并创建文档

Excel 导入并创建表格

DOCX 高保真解析

DOCX 转 HTML

按文档 ID 导出 DOCX

按 JSON 内容导出 DOCX

按文档 ID 导出 PDF

指定文档信息

指定文档数据

版本管理列表

修订记录与批注数据

创建文档

保存文档内容

设置文档权限

删除文档

模板批量合成 · 能力概览

模板列表

模板变量结构

单篇合成

批量合成

核心字段

常见问题