跳到主要内容

文档拆分

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

POST {apiPrefix}/split

提交文档拆分任务

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

文字文档拆分​

支持文字文档（doc, docx, wps）按标题、分节符或关键字进行拆分。

请求体：

Content-Type为application/json

参数名类型说明是否必须
fileUrlstring文件下载链接是
filenamestring包含后缀的文件名(支持文字（doc,docx,wps）)是
tokenTypestring三方token类型，值为cookie或者header否
tokenValuestring三方token值，zOffice下载文件或回调通知时回传否
callbackstring回调地址。任务结束后zOffice回调通知状态是
typestring拆分类型，枚举: WORDHEADING: 根据标题拆分，SECTBREAK: 根据分节符拆分，TEXT：根据关键字拆分是
keywordstringtype为TEXT时必填，根据该文字拆分文档（该关键字指的是标题里的文字，所包含的标题不分等级）否
  • tokenType/tokenValue/callback说明见本文档【通用字段说明】
  • 文字文件大小不能超过300m。

请求示例：

{
    "fileUrl": "https://example.com/files/document.docx",
    "filename": "document.docx",
    "callback": "https://example.com/callback",
    "type": "WORDHEADING"
}

正常返回：

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

错误返回：

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

PDF拆分​

v8.3 开始支持

支持PDF文件拆分，提供三种拆分模式，可将一个PDF文件拆分为多个PDF文件。

请求体：

Content-Type为application/json

参数名类型说明是否必须
fileUrlstring文件下载链接是
filenamestring包含后缀的文件名（仅支持pdf）是
tokenTypestring三方token类型，值为cookie或者header否
tokenValuestring三方token值，zOffice下载文件或回调通知时回传否
callbackstring回调地址。任务结束后zOffice回调通知状态是
typestring拆分模式，枚举值：PAGERANGE / FIXEDPAGES / FILECOUNT是
rangesstring页码范围，type为PAGERANGE时必填条件必填
fixedPagesnumber每份固定页数，type为FIXEDPAGES时必填。正整数，最小值为1条件必填
fileCountnumber拆分份数，type为FILECOUNT时必填。整数，范围为2~50条件必填
outputstring输出模式，可选值：singleFile / array。默认array。仅type为PAGERANGE时生效否
  • tokenType/tokenValue/callback说明见本文档【通用字段说明】
  • PDF文件大小不能超过200m。
  • 拆分产生的文件数量最多不超过50个。

拆分模式说明​

type值说明
PAGERANGE按页码范围拆分。需指定ranges参数，每个范围产生一个子PDF文件（ranges段数不超过50）。支持output参数控制输出模式
FIXEDPAGES按固定页数拆分。需指定fixedPages参数，每份文件包含固定页数（末尾不足则取实际剩余页数）。拆分结果不超过50个文件
FILECOUNT按份数均分拆分。需指定fileCount参数（最大值50），将PDF均分为指定份数（页数不整除时前面各份多分一页）

ranges参数格式​

ranges为字符串，使用英文逗号分隔多个页码段，每段可以是单个页码或用短横线连接的起止页码范围。

  • 格式：页码或范围,页码或范围,...
  • 页码从1开始，起始页必须小于等于结束页
  • 支持单页码：3 表示仅提取第3页
  • 支持页码范围：1-5 表示提取第1~5页
  • 混合使用：1-3,5,7-10 表示拆分为三个文件（第1~3页、第5页、第7~10页）
  • 各段的页码范围允许重叠，如 1-5,3-8 会产生两个子PDF（分别包含1~5页和3~8页）

output参数说明​

output值说明
array默认值。每个ranges段拆分为独立文件，下载结果为ZIP压缩包
singleFile将ranges指定的所有页码范围合并提取为单个PDF输出。仅type为PAGERANGE时生效，其他拆分模式下此参数被忽略

请求示例​

示例1：按页码范围拆分为多个文件（PAGERANGE）

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "1-3,4-6,7-10"
}

示例2：提取指定页码合并为单个文件（output=singleFile）

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "1-3,7-10",
    "output": "singleFile"
}

示例3：提取单页（PAGERANGE 单页码格式）

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "3"
}

示例4：按固定页数拆分（FIXEDPAGES），每3页拆分为一个文件

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "FIXEDPAGES",
    "fixedPages": 3
}

示例5：按份数均分拆分（FILECOUNT），拆分为4份

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "FILECOUNT",
    "fileCount": 4
}

正常返回：

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

错误返回：

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

错误码说明​

错误码HTTP状态码说明
PdfSplitInvalidType412type参数无效，不是合法的拆分模式枚举值（PAGERANGE/FIXEDPAGES/FILECOUNT）
PdfSplitRangesRequired412type为PAGERANGE时未提供ranges参数
PdfSplitInvalidRangesFormat412ranges格式错误，应为逗号分隔的页码或页码范围（如 1-5,10,12-15）
PdfSplitInvalidFixedPages412fixedPages无效，必须为正整数（>= 1）
PdfSplitInvalidFileCount412fileCount无效，必须为整数且 >= 2
PdfSplitInvalidOutputValue412output参数值无效，仅支持 singleFile 或 array

回调通知​

拆分任务完成后，zOffice会通过callback地址通知任务结果。

成功通知（output=array 默认模式）：

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskSuccessNotify",
    "detail": {
        "taskStatus": "SUCCESS",
        "defaultDownloadPath": "/docs/publicapi/v1/download",
        "contentId": "640eeac02a9baf5dbc69d426",
        "filename": "document_split.zip"
    }
}

成功通知（output=singleFile 模式）：

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskSuccessNotify",
    "detail": {
        "taskStatus": "SUCCESS",
        "defaultDownloadPath": "/docs/publicapi/v1/download",
        "contentId": "640eeac02a9baf5dbc69d426",
        "filename": "document_split.pdf"
    }
}

失败通知：

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskFailNotify",
    "detail": {
        "taskStatus": "FAIL",
        "msg": "split failed"
    }
}
说明
  • 当output为array（默认）时，拆分成功后下载的结果文件为ZIP格式的压缩包，包含拆分后的多个PDF文件。子文件命名格式为 {原文件名}_{序号}.pdf（如 document_001.pdf、document_002.pdf）。
  • 当output为singleFile时（仅PAGERANGE模式），下载结果为单个PDF文件，包含ranges指定的所有页面。
最后于 更新