文档内容操作

💡 调用API，需要认证。认证参考【接口认证】

API接口

POST {apiPrefix}/content/update

提交文档内容操作任务

任务添加失败，同步返回失败原因
任务添加成功，同步返回任务ID。第三方可以配置任务回调通知获取任务状态。

请求体

Content-Type为application/json

参数名	类型	说明	是否必须
fileUrl	string	文件下载地址	是
filename	string	包含后缀的文件名，目前源文件类型支持doc/docx/wps/pdf	是
tokenType	string	三方token类型，值为cookie或者header	否
tokenValue	string	三方token值，zOffice下载文件或回调通知时回传	否
callback	string	回调地址。任务结束后zOffice回调通知状态	是
ops	数组	对文档内容操作的有序操作数组，数组对象见下方op说明。支持的操作列表见【操作列表](#操作列表)】	是

fileUrl/tokenType/tokenValue/callback说明见本文档【通用字段说明】

请求体示例

{
    "fileUrl": "http://{{thirdparty-demo}}/v2/context/local-PublicAPI-contentUpdate-clearDoc/content",
    "filename": "demo-docx.docx",
    "tokenType":"cookie",
    "tokenValue":"zdocs_access_token={{zdocs_access_token}}",
    "callback": "http://{{thirdparty-demo}}/v2/context/convert/callback",
    "ops": [ {
        "actId": "ClearDoc",
        "options": {
            "args": ["acceptAllTrack", "removeAllComment"]
        }
    }]
    
}

正常返回：

{
    "taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
    "code": "Ok",
    "detail": {
        "taskStatus": "IN_QUEUE"
    }
}

错误返回：

{
    "taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
    "code": "TaskQueueCongestion",
    "detail": {
        "taskStatus": "FAIL"
    }
}

操作列表

清稿

{
	"actId": "ClearDoc",
	"options": {
		"args": ["acceptAllTrack", "removeAllComment"]
	}
}

args数组表示清除文档对应的具体操作

acceptAllTrack表示接受所有修订记录
removeAllComment表示移除所有评论

支持docx/wps/doc，源文件最大300m，docx格式600m，最多1000页

args为空表示执行上述所有操作

书签内容替换

使用限制

不允许ops中有多个UpdateBookmarkRef
UpdateBookmarkRef不允许和其他操作在同一次文档内容操作请求中传递
支持格式doc/docx/wps，所有文件（包括源文件和引用文件）总和最大300m

使用说明

模板文件下载地址在请求体fileUrl中传递
模板文件名在请求体filename中传递，文件名需要带后缀
书签替换内容在请求体ops中传递，结构如下

{
    "actId": "UpdateBookmarkRef",
    "options": {
        "args": [
            {
                "bookname": "书签名",
                "dataType": "书签引用类型",
                "dataRef": "书签引用内容",
                "refName": "书签引用内容名称"
            }
        ]
    }
}

options说明

选项名	选项类型	是否必须	说明
args	`BookmarkRef`数组	是	`BookmarkRef` 对象包含四个属性： * bookname * dataType * dataRef * refName

bookname: 书签名。书签名不存在时，对应替换会被忽略，但不会影响其他书签替换。
dataType: 书签引用类型。可选值TEXT，DOC，PIC。分别对应引用内容为字符串，文档，图片。
dataRef: 书签引用内容。
- dataType为TEXT时，该值为字符串；
- dataType为DOC或PIC时，该值为下载对应文件的URL。
  - 请求URL要求返回对应的文件流，其他无限制。
  - zOffice请求URL时，采用与tokenType/tokenValue中说明认证方式。
refName: 书签引用名称。
- dataType为TEXT时，该值可以省略；
- dataType为DOC或PIC时，该值为dataRef对应带后缀的文件名，请确保文件后缀名正确，否则会导致套红结果不符预期。支持的格式：png/jpeg/doc/wps/docx

例子 - 多个书签替换

{
    "actId": "UpdateBookmarkRef",
    "options": {
        "args": [
            {
                "bookname": "文件标题",
                "dataType": "TEXT",
                "dataRef": "zOffice PublicAPI 书签套用"
            },
            {
                "bookname": "签名部门",
                "dataType": "PIC",
                "dataRef": "http://{{thirdparty-demo}}/v2/context/local-PublicAPI-contentUpdate-updateBkRef-pic/content",
                "refName": "sign.png"
            },
            {
                "bookname": "正文",
                "dataType": "DOC",
                "dataRef": "http://{{thirdparty-demo}}/v2/context/local-PublicAPI-contentUpdate-updateBkRef-body/content",
                "refName": "body.docx"
            },
            {
                "bookname": "尾注",
                "dataType": "TEXT",
                "dataRef": "科技改变生活",
                "refName": ""
            }
        ]
    }
}

文档加位置文本水印

{
    "actId": "ApplyWatermark",
    "options": {
        "text": "watermark for test",
        "fontcolor": "#DC134C",
        "fontsize": "70",
        "font": "黑体",
        "rotation": 315,
        "transparent": 20,
        "position": "BOTTOM_RIGHT"
    }
}

支持类型：

源文件类型	限制
docx/wps/doc/pdf/ofd	源文件最大300m，docx格式600m，最多1000页；其中在v8.2版本开始支持PDF

options说明 见位置文本水印

文档加位置图片水印

word 文件

{
    "actId": "ApplyPicWatermark",
    "options": {
        "picUrl": "http://{{thirdparty-demo}}/v2/context/local-pic/content",
        "picName": "pic.png",
        "isErosion": false,
        "rotation": 0,
        "position": "CENTER",
        "picScale": 100
    }
}

pdf、ofd文件

不传入缩放比例的参数：picScale , 水印图片自适应页面

 {
    "actId": "ApplyPicWatermark",
    "options": {
         "picUrl": "http://{{thirdparty-demo}}/v2/context/local-logo/content",
         "picName": "local-logo.png",
         "picScale": 100,
         "transparent": 78,
         "rotation": 0,
         "position": "CENTER"
     }
}

支持类型：

源文件类型	限制
docx/wps/doc	源文件最大300m，docx格式600m，最多1000页，水印图片最大支持50m
pdf/ofd	源文件最大200m、最多1000页，水印图片最大支持50m

options说明 见位置图片水印

文档加平铺文本水印

{
    "actId": "ApplyWatermarkForFixed",
    "options": {
        "line1": "watermark for test",
        "withDate": true,
        "font": "黑体",
        "fontcolor": "#DC134C",
        "fontsize": "70",
        "transparent": 70,
        "rotation": 315,
        "spacing": 50
    }
}

支持类型：

源文件类型	限制
docx/wps/doc/pdf/ofd	源文件最大200m，最多1000页；其中在v8.2版本开始支持docx/wps/doc

options说明 见平铺文本水印

文档加平铺图片水印

{
    "actId": "ApplyTiledImgWatermarkForFixed",
    "options": {
        "picUrl": "http://{{thirdparty-demo}}/v2/context/local-png/content",
        "picName": "filez.png",
        "picScale": 100,
        "rotation": 315,
        "transparent": 70,
        "spacing": 80
    }
}

支持类型：

源文件类型	限制
docx/wps/doc/pdf/ofd	源文件最大200m，最多1000页；其中在v8.2版本开始支持docx/wps/doc/PDF

options说明 见平铺图片水印

表格数据设置

使用限制

仅支持 docx/wps/doc 格式
插入表格时，列数不得超过 30 列
args 数组中的操作按顺序依次执行

使用说明

通过 bookname（书签名）或 tablename（表格名）定位目标表格
支持在书签位置插入新表格、向已有表格插入行、删除表格等操作

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "书签名",
                "tablename": "表格名",
                "type": "操作类型",
                "target": "操作目标",
                "actDetail": {}
            }
        ]
    }
}

options说明

选项名	选项类型	是否必须	说明
args	`TableOp`数组	是	表格操作数组，按顺序依次执行

TableOp 对象属性

属性名	类型	是否必须	说明
bookname	string	否	书签名，用于定位表格位置。插入表格时必须提供
tablename	string	否	表格名，用于定位已有表格。与 bookname 配合使用
type	string	是	操作类型，可选值：`insert`（插入）、`delete`（删除）
target	string	是	操作目标，可选值：`table`（表格）、`row`（行）
actDetail	object	否	操作详细参数，不同的 type + target 组合对应不同的参数结构，见下方说明。删除表格操作时可省略

插入表格（type: insert, target: table）

在指定书签位置插入一个新表格。

actDetail 参数

属性名	类型	是否必须	说明
clear	boolean	否	是否清除书签内已有内容后再插入，默认 false
tableData	string[][]	是	二维数组，表示表格内容。外层数组为行，内层数组为单元格文本。列数不得超过 30

合并单元格说明

tableData 支持通过稀疏数组实现单元格合并：

横向合并：有文字的单元格后面紧跟的空值（null/undefined）单元格会被合并
纵向合并：某行中一组单元格全为空值，且与上方单元格列跨度一致时，会纵向合并

例子 - 在书签位置插入表格

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "数据表格",
                "type": "insert",
                "target": "table",
                "actDetail": {
                    "clear": true,
                    "tableData": [
                        ["姓名", "部门", "职位"],
                        ["张三", "技术部", "工程师"],
                        ["李四", "产品部", "产品经理"]
                    ]
                }
            }
        ]
    }
}

例子 - 插入带合并单元格的表格

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "报表",
                "type": "insert",
                "target": "table",
                "actDetail": {
                    "tableData": [
                        ["季度汇总", null, null],
                        ["Q1", "收入", "100万"],
                        ["Q1", "支出", "60万"]
                    ]
                }
            }
        ]
    }
}

上述示例中，第一行 "季度汇总" 后跟两个 null，表示该单元格横向合并 3 列。

插入行（type: insert, target: row）

向已有表格中插入新行。

actDetail 参数

属性名	类型	是否必须	说明
insertBefore	boolean	否	是否在目标行前面插入，默认 false（在目标行后面插入）
position	object	否	插入位置，包含 rowIdx 属性（从 1 开始的行索引）。不指定时，insertBefore=true 取首行，否则取末行
tableData	string[][]	是	二维数组，表示要插入的行数据。外层数组的每个元素为一行

例子 - 在表格第2行前插入2行数据

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "bmk1",
                "type": "insert",
                "target": "row",
                "actDetail": {
                    "insertBefore": true,
                    "position": { "rowIdx": 2 },
                    "tableData": [
                        ["5", "6", "8"],
                        ["9", "10", "11"]
                    ]
                }
            }
        ]
    }
}

删除表格（type: delete, target: table）

删除书签名对应书签下的第一个表格，或表格名对应的表格。

例子 - 通过书签名删除表格

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "数据表格",
                "type": "delete",
                "target": "table"
            }
        ]
    }
}

例子 - 通过表格名删除表格

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "tablename": "Table1",
                "type": "delete",
                "target": "table"
            }
        ]
    }
}

组合操作示例

一次请求中可包含多个表格操作，按数组顺序依次执行。

例子 - 替换一个书签表格并向另一个书签表格追加行

{
    "actId": "SetTableData",
    "options": {
        "args": [
            {
                "bookname": "摘要表格",
                "type": "insert",
                "target": "table",
                "actDetail": {
                    "clear": true,
                    "tableData": [
                        ["项目", "金额"],
                        ["收入", "500万"],
                        ["支出", "300万"]
                    ]
                }
            },
            {
                "bookname": "明细表格",
                "type": "insert",
                "target": "row",
                "actDetail": {
                    "tableData": [
                        ["2026-03", "办公用品", "1200"]
                    ]
                }
            }
        ]
    }
}

API接口​

操作列表​

清稿​

书签内容替换​

文档加位置文本水印​

文档加位置图片水印​

文档加平铺文本水印​

文档加平铺图片水印​

表格数据设置​

插入表格（type: insert, target: table）​

插入行（type: insert, target: row）​

删除表格（type: delete, target: table）​

组合操作示例​

API接口

操作列表

清稿

书签内容替换

文档加位置文本水印

文档加位置图片水印

文档加平铺文本水印

文档加平铺图片水印

表格数据设置

插入表格（type: insert, target: table）

插入行（type: insert, target: row）

删除表格（type: delete, target: table）

组合操作示例