文档解析服务 API文档

本文档描述了文档解析服务的对外API接口，支持PPT、Word、Excel、PDF等格式的文档解析。

服务概述

文档解析服务提供异步文档解析能力，支持多种文档格式转换为标准格式。服务采用异步处理模式，通过回调机制通知解析结果。

基础信息

服务地址: https://www.plaso.cn/dataentry/document

Content-Type: application/json

字符编码: UTF-8

认证方式: AppId + SecretKey 签名示例

API接口

1. 创建文档解析任务

提交文档解析任务，系统会异步处理并在完成后通过回调通知结果。

接口地址: POST /parser

请求参数:

参数名	类型	必填	说明
appId	string	是	应用ID，用于标识调用方及其配置
sourcePath	string	是	源文件的存储路径（OSS路径格式：oss://bucket/file）
taskType	number	是	任务类型，详见任务类型说明
callbackUrl	string	是	任务处理完成后用于通知结果的回调URL
validBegin	number	是	请求开始时间戳（秒）
validTime	number	是	请求有效时长（秒），建议300秒
signature	string	是	签名，用于请求验证
exportBoard	boolean	否	是否生成用于导出板书的文件，需要导出课堂板书的话，需要传true

任务类型 (taskType):

类型	值	说明
EXTERNAL_PPT	4	PPT文档
EXTERNAL_DOC	5	Word/Excel文档
EXTERNAL_PDF	8	PDF文档

导出课堂板书需要在伯索云配置回调接口（getFileAddr），用于获取解析后文件信息。

需要配置OSS AK/SK用于保存解析后的课件（需要putobject，setacl权限）

请求示例:

{
  "appId": "your-app-id",
  "sourcePath": "oss://your-bucket/path/to/document.pptx",
  "taskType": 4,
  "callbackUrl": "https://your-callback-url.com/api/callback/document",
  "validBegin": 1703123456,
  "validTime": 300,
  "signature": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0"
}

解析后文件保存路径:

解析完成后，文件将保存在源文件路径后附加 _i 的目录中，即 ${sourcePath}_i/。

回调信息中的 targetPath 字段会返回此目录路径 (OSS Key)。

例如，如果 sourcePath 是 oss://bucket/docs/file.pptx，则 targetPath 将是 docs/file.pptx_i/。

具体的解析后文件（如图片）需要将此 targetPath 与文件名（如 1.jpg）拼接后获取。

成功响应:

{
  "code": 0,
  "msg": "success",
  "obj": {
    "taskId": "654e1c9a7b8d9e001a2b3c4d"
  }
}

错误响应:

{
  "code": 1001,
  "msg": "源文件路径不存在"
}

cURL示例:

回调机制

解析结果回调

文档解析完成后，服务会调用您提供的回调URL通知解析结果。

回调地址: 您在创建任务时提供的 callbackUrl

调用方: 文档解析服务

请求参数:

参数名	类型	必填	说明
taskId	string	是	任务ID
taskStatus	number	是	任务状态，详见状态值说明
targetPath	string	是	解析后保存的路径
convertPages	number	否	WORD,PDF解析成功时返回，表示成功转换的页数

状态值说明:

状态值	状态名称	说明
100	DONE	解析成功
101	FAILED	解析失败

回调重试机制

服务会按照以下策略重试回调：

重试策略:

首次回调失败后，等待5秒重试

最多重试3次

重试间隔递增：5秒、10秒、20秒

3次重试后仍失败，任务标记为回调失败

重试条件:

HTTP状态码 >= 500

网络超时

连接失败

错误码说明

错误码	错误类型	说明
0	SUCCESS	成功
4	INPUT_DATA_ERROR	输入数据错误（例如，`sourcePath` 未提供）
7	INADEQUATE_PRIVILEGE	权限不足（例如，机构未开通服务或OSS配置不存在）
270000	NOT_SUPPORT	不支持的文件解析
270001	TASK_HAS_FULL	任务队列已满

接入参考Demo

https://github.com/PlasoOpenPlatform/DocParseDemo

以下流程图和说明描述了如何完整地集成和使用文档解析服务，并展示了本Demo中的后端实现逻辑。

文档解析接口

文档解析服务 API文档#

服务概述#

基础信息#

API接口#

1. 创建文档解析任务#

回调机制#

解析结果回调#

回调重试机制#

错误码说明#

接入参考Demo#

文档解析服务 API文档

服务概述

基础信息

API接口

1. 创建文档解析任务

回调机制

解析结果回调

回调重试机制

错误码说明

接入参考Demo