获取审批实例ID列表新版SDK
更新于 2025-03-06
特别提醒
当前接口针对OA高级版客户可支持查询最多5年内的实例数据（即startTime时间距当前时间不能超过5年），升级OA高级版可用，可满足更高级的开发需求，响应个性化的业务场景。查看全部专享OpenAPI
接口调用流程
-
可以调用本接口获取审批流对应的审批实例ID。
-
调用获取单个审批实例详情接口，获取审批实例详情信息。
接口调用说明
-
如果只传入startTime参数，要求时间距离当前时间不能超过120天，endTime不传则默认取当前时间。
-
如果传入startTime参数和endTime参数，要求时间范围不能超过120天，同时startTime时间距当前时间不能超过365天。
-
批量获取的实例ID个数（循环获取），最多不能超过10000个。
权限
要调用此API，需要以下权限之一。
应用类型 | 是否支持 | 权限 | API Explorer调试 |
|---|---|---|---|
| 企业内部应用 | 支持 | 工作流实例读权限 | API Explorer |
| 第三方企业应用 | 暂不支持 | 暂不支持 | 暂不支持 |
| 第三方个人应用 | 暂不支持 | 暂不支持 | 暂不支持 |
请求方法
Header参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
x-acs-dingtalk-access-token | String | 是 | 调用该接口的访问凭证。
|
Body参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
processCode | String | 是 | 审批流的唯一码。
|
startTime | Long | 是 | 审批实例开始时间，Unix时间戳，单位毫秒。 说明
例如，获取审批单发起时间在2020.4.10-2020.4.14之间，该值传2020.4.10 00:00:00对应的时间戳1586448000000。 |
endTime | Long | 否 | 审批实例结束时间，Unix时间戳，单位毫秒。 说明
例如，获取审批单发起时间在2020.4.10-2020.4.14之间，该值传2020.4.14 23:59:59对应的时间戳1586879999000。 |
nextToken | Long | 是 | 分页游标。
|
maxResults | Long | 是 | 分页参数，每页大小，最多传20。 |
userIds | Array of String | 否 | 发起人userId列表，最大列表长度为10。 |
statuses | Array of String | 否 | 流程实例状态：
说明
未传值代表查询所有状态的实例ID列表。 |
返回参数
名称 | 类型 | 描述 |
|---|---|---|
result | Object | 返回结果。 |
list | Array of String | 审批实例ID。 |
nextToken | String | 分页游标。 说明
不为空表示有更多数据。 |
success | Boolean | 接口请求是否成功。
|
示例
请求示例
返回示例
错误码
HttpCode | 错误码 | 错误信息 | 说明 |
|---|---|---|---|
400 | invalidProcessCode | 审批模版processCode不能为空 | 审批模版processCode不能为空 |
400 | invalidInstanceListIdsStartTime | 获取审批实例ID列表，审批实例开始时间不能为空 | 获取审批实例ID列表，审批实例开始时间不能为空 |
400 | invalidNextToken | 获取审批实例ID列表，分页查询的游标不能为空 | 获取审批实例ID列表，分页查询的游标不能为空 |
400 | invalidMaxResults | 获取审批实例ID列表，分页参数非法，每页大小，最多传20。 | 获取审批实例ID列表，分页参数非法，每页大小，最多传20。 |
400 | invalidEndTime | 获取审批实例ID列表，审批实例结束时间不能小于开始时间；且查询时间范围不能超过120天。 | 获取审批实例ID列表，审批实例结束时间不能小于开始时间；且查询时间范围不能超过120天。 |
400 | invalidUserIds | 获取审批实例ID列表，发起userid列表参数非法，最大列表长度为10。 | 获取审批实例ID列表，发起userid列表参数非法，最大列表长度为10。 |
400 | internalError | %s | 系统内部异常 |
500 | systemError | 系统异常 | 系统异常 |
