退回审批任务新版SDK
更新于 2025-06-20
特别提醒
当前接口为OA高级版专享接口，升级OA高级版可用，可满足更高级的开发需求，响应个性化的业务场景。查看全部专享OpenAPI
接口功能介绍
调用本接口，当前审批人可对审批任务进行退回操作，退回方式支持退回到发起人节点、退回到指定审批人节点等。接口调用成功后，实现效果如下图所示。
以下情况不支持退回： 1. 当前流程在第一个审批节点，不支持退回至审批人。 2. 表单中含有业务套件, 不支持退回至发起人。
- 退回到发起人/审批人
权限
要调用此API，需要以下权限之一。
应用类型 | 是否支持 | 权限 | API Explorer调试 |
|---|---|---|---|
| 企业内部应用 | 支持 | OA审批工作流读写权限（OA高级版专享） | API Explorer |
| 第三方企业应用 | 暂不支持 | 暂不支持 | 暂不支持 |
| 第三方个人应用 | 暂不支持 | 暂不支持 | 暂不支持 |
请求方法
Header参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
x-acs-dingtalk-access-token | String | 是 | 调用该接口的访问凭证：
|
Body参数
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
taskId | Long | 是 | 审批任务ID。可通过调用获取单个审批实例详情接口获取 |
processInstanceId | String | 是 | 审批实例ID：
|
operateUserId | String | 是 | 操作人的用户ID，需要跟任务的当前执行人保持一致，否则无法通过校验。 |
targetActivityId | String | 是 | 退回到的节点ID。
|
revertAction | String | 是 | 退回方式：
|
remark | String | 否 | 备注信息。 |
返回参数
名称 | 类型 | 描述 |
|---|---|---|
result | Boolean | 是否退回成功。 |
示例
请求示例
返回示例
错误码
HttpCode | 错误码 | 错误信息 | 说明 |
|---|---|---|---|
400 | param.blank | %s参数不能为空 | 请参照接口文档检查必填项taskId、processInstanceId、operateUserId、targetActivityId、revertAction、targetActivityActioners等 |
400 | param.illegal | 不合法的参数%s | 不合法的参数taskId |
400 | task.status.error | 当前任务状态不是运行中不支持退回操作 | 请检查taskId，任务状态是否为RUNNING |
400 | instance.status.error | 当前流程实例状态不是运行中不支持退回操作 | 请检查processInstanceId参数，当前审批单状态是否为RUNNING |
400 | param.illegal.operator | 操作人的userId必须为当前任务的审批人 | 请检查operateUserId参数 |
400 | internalError | %s | 系统内部异常 |
400 | oaplus.query.limit | 请求过于频繁，稍后重试 | 企业访问并发超过限制 |
400 | benefit.status.invalid | 权益校验失败，未开通或过期 | 权益校验 |
400 | benefit.query.error | 权益查询失败 | 权益系统查询失败 |
400 | isvAuth.check.error | 当前isv没有该审批模板的操作权限，请检查企业是否授权了该审批模板给isv | 当前isv没有该审批模板的操作权限，请检查企业是否授权了该审批模板给isv |
400 | user.not.exist | 用户ID不存在，请检查operateUserId、targetActivityActioners中的用户ID是否正确 | 用户ID不存在，请检查operateUserId、targetActivityActioners中的用户ID是否正确 |
500 | system.error | 系统错误 | 系统错误 |
500 | revertTask.hsfIntegration.error | 退回任务系统执行失败，请稍后重试或联系钉钉客服处理 | 退回任务系统执行失败，请稍后重试或联系钉钉客服处理 |
