慧企星助开放平台文档

任务操作接口

以下接口对应任务接收、执行、审核、审批、转发、挂起和历史任务处理等操作。所有接口都必须携带 X-Employee-Virtual-Id，接口中的员工标识统一使用当前 API Key 下的 virtualId。

权限与处理方式：查询类接口使用 tasks.read，操作类接口使用 tasks.write。除查询接口外，任务操作均通过后台队列异步处理，返回 statusCode=100 只表示操作已受理，不表示任务状态已经完成变更；请通过任务详情或 Webhook 事件确认最终状态。

任务操作初始化接口

执行需要填写原因、附件、检查项或业务选项的任务操作前，建议先调用对应的 Init 接口获取当前任务状态下可用的参数和提示信息。Init 接口使用 tasks.read 权限，返回的员工标识统一为 virtualId 或以 VirtualId 结尾的字段，不暴露内部员工 Guid。

方法	路径	说明	常用查询参数
GET	`/api/openplatform/tasks/{id}/actions/decompose/metadata`	分解任务初始化。	`checkItemId` 可选。
GET	`/api/openplatform/tasks/{id}/actions/receive/metadata`	接收任务初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/refuse/metadata`	拒绝接收任务初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/pause/metadata`	暂停任务初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/auditNoPass/metadata`	审核不通过任务初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/confirmReject/metadata`	确认审核驳回初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/appeal/metadata`	申诉任务初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/complete/metadata`	完成任务初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/approveNoPass/metadata`	审批不通过任务初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/cancelApply/metadata`	申请撤销任务初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/activate/metadata`	历史任务变为执行中初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/forceActivate/metadata`	历史任务强制激活初始化。	无。
GET	`/api/openplatform/tasks/{id}/actions/applyStart/metadata`	挂起任务申请启动初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/applySuspend/metadata`	进行中任务申请挂起初始化。	`isEdit` 可选。
GET	`/api/openplatform/tasks/{id}/actions/executorEdit/metadata`	负责人修改任务初始化。	`actionType` 为修改类型，`isEdit` 可选。
GET	`/api/openplatform/tasks/creationMetadata`	创建任务初始化。	`actionType`、`projectId` 可选。
GET	`/api/openplatform/tasks/actions/judge/metadata`	任务评定初始化。	`taskId` 可选。

调用约定：isEdit=true 表示读取当前操作人上一次提交的原因和附件，用于编辑已有申请；checkItemId、taskId、projectId 使用任务或项目的公开标识。Init 成功只表示初始化数据读取成功，随后仍需按对应操作接口的请求体提交动作。

查询与记录

方法	路径	说明
GET	`/api/openplatform/tasks/{id}/operationRecords`	获取任务操作记录。查询参数：`recordType` 默认 0、`page` 默认 1、`pageSize` 默认 20，最大 100。
GET	`/api/openplatform/tasks/{id}/checkerOperationRecords`	获取任务检查人、结果审核人的操作记录，返回分页数据。
GET	`/api/openplatform/tasks/owned`	获取当前员工负责的任务列表。
GET	`/api/openplatform/tasks/involved`	获取当前员工参与的任务列表。
GET	`/api/openplatform/tasks/pending`	获取当前员工待操作任务列表，支持优先级、截止时间类型、状态、标签和关键字筛选。

列表请求参数：列表接口统一支持 page、pageSize、keyword、sortField、sortOrder。任务列表还可使用 priority、status、labelIds、dueAtType、creatorVirtualId、assigneeVirtualId、checkerVirtualId、createdAtFrom、createdAtTo、judgeTimeFrom、judgeTimeTo、dueAtFrom、dueAtTo、taskType 等筛选字段；具体可用字段以各接口说明为准。返回结构统一为 {"statusCode":100,"msg":"获取成功","data":{"total":0,"items":[]}}。

任务执行、审核与审批

方法	路径	说明
POST	`/api/openplatform/tasks/{id}/attachments`	给任务添加附件。
POST	`/api/openplatform/tasks/{id}/actions/decompose`	分解任务，创建子任务；请求体中的负责人和审核人使用 `assigneeVirtualId`、`checkerVirtualId`。
POST	`/api/openplatform/tasks/{id}/actions/receive`	负责人接收任务。
POST	`/api/openplatform/tasks/{id}/actions/start`	启动任务。
POST	`/api/openplatform/tasks/{id}/actions/pause`	暂停任务。
POST	`/api/openplatform/tasks/{id}/actions/refuse`	拒绝接收任务。
POST	`/api/openplatform/tasks/{id}/actions/auditPass`	发起人或其他需要确认任务完成的角色审核通过。
POST	`/api/openplatform/tasks/{id}/actions/auditNoPass`	发起人或其他需要确认任务完成的角色审核不通过任务。
POST	`/api/openplatform/tasks/{id}/actions/confirmReject`	负责人确认审核驳回结果。
POST	`/api/openplatform/tasks/{id}/actions/appeal`	负责人对审核不通过发起申诉。
POST	`/api/openplatform/tasks/{id}/actions/rejectAppeal`	驳回任务申诉。
POST	`/api/openplatform/tasks/{id}/actions/complete`	负责人完成任务并提交结果。
POST	`/api/openplatform/tasks/{id}/actions/approveNoPass`	审批不通过任务。
POST	`/api/openplatform/tasks/{id}/actions/approvePass`	审批通过任务。
POST	`/api/openplatform/tasks/{id}/actions/sendDraft`	发送草稿任务。
POST	`/api/openplatform/tasks/{id}/actions/resend`	重发任务，可传新的截止时间、原因和附件。
POST	`/api/openplatform/tasks/{id}/actions/confirmChange`	确认变更任务。
POST	`/api/openplatform/tasks/{id}/actions/changeCheckItem`	变更检查项，使用 `checkItemId` 指定检查项。
POST	`/api/openplatform/tasks/{id}/actions/checkItemToNote`	将检查项转为便签。

转发与转发审批

方法	路径	说明
POST	`/api/openplatform/tasks/{id}/actions/forward`	转发任务，请求体使用 `assigneeVirtualId` 指定新的负责人。
POST	`/api/openplatform/tasks/{id}/actions/forwardApprove`	转发审批通过。
POST	`/api/openplatform/tasks/{id}/actions/forwardReject`	转发审批不通过。
POST	`/api/openplatform/tasks/{id}/actions/forwardCancel`	转发人撤回转发。
POST	`/api/openplatform/tasks/{id}/actions/forwardReceive`	接收转发任务。
POST	`/api/openplatform/tasks/{id}/actions/forwardRefuse`	拒绝接收转发任务。

撤销、激活与关注

方法	路径	说明
POST	`/api/openplatform/tasks/{id}/actions/cancelApply`	进行中任务申请撤销。
POST	`/api/openplatform/tasks/{id}/actions/passCancelApply`	通过取消任务申请。
POST	`/api/openplatform/tasks/{id}/actions/rejectCancelApply`	不通过取消任务申请。
POST	`/api/openplatform/tasks/{id}/actions/forceCancel`	强制撤销任务。
POST	`/api/openplatform/tasks/{id}/actions/directDelete`	直接删除任务。该操作不可逆，请谨慎调用。
POST	`/api/openplatform/tasks/{id}/actions/activate`	历史任务变为执行中。
POST	`/api/openplatform/tasks/{id}/actions/confirmActivate`	负责人确认历史任务变为执行中。
POST	`/api/openplatform/tasks/{id}/actions/activateAppeal`	历史任务变为执行中申诉。
POST	`/api/openplatform/tasks/{id}/actions/confirmActivateAppeal`	确认历史任务变为执行中的申诉。
POST	`/api/openplatform/tasks/{id}/actions/forceActivate`	历史任务强制激活，请求体传 `dueAt`、`score`、`reason` 和可选 `attachmentUrls`。
POST	`/api/openplatform/tasks/{id}/actions/cancelActivate`	历史任务变为执行中取消，即取消激活并重新处理。
POST	`/api/openplatform/tasks/{id}/actions/follow`	关注或取消关注任务，由业务状态决定本次操作结果。
POST	`/api/openplatform/tasks/{id}/actions/approveToInProgress`	待审核任务变为进行中。
POST	`/api/openplatform/tasks/{id}/actions/responsibleCancelToInProgress`	负责人申请撤销任务变为进行中。
POST	`/api/openplatform/tasks/{id}/actions/creatorCancelToInProgress`	发起人、审核人或负责人申请撤销任务变为进行中。

挂起与启动申请

方法	路径	说明
POST	`/api/openplatform/tasks/{id}/actions/applyStart`	挂起任务申请启动。
POST	`/api/openplatform/tasks/{id}/actions/withdrawStart`	撤回申请启动。
POST	`/api/openplatform/tasks/{id}/actions/approveStart`	同意启动申请。
POST	`/api/openplatform/tasks/{id}/actions/rejectStart`	申请启动不通过。
POST	`/api/openplatform/tasks/{id}/actions/applySuspend`	进行中任务申请挂起。
POST	`/api/openplatform/tasks/{id}/actions/cancelSuspend`	取消挂起任务申请。
POST	`/api/openplatform/tasks/{id}/actions/approveSuspend`	同意挂起任务申请。
POST	`/api/openplatform/tasks/{id}/actions/rejectSuspend`	不同意挂起申请。
POST	`/api/openplatform/tasks/{id}/actions/resume`	挂起状态恢复执行。

负责人修改与催办

方法	路径	说明
POST	`/api/openplatform/tasks/{id}/actions/executorEdit`	负责人修改任务。
POST	`/api/openplatform/tasks/{id}/actions/executorCancelEdit`	负责人取消修改任务。
POST	`/api/openplatform/tasks/{id}/actions/executorEditReject`	负责人修改任务审批不通过。
POST	`/api/openplatform/tasks/{id}/actions/executorEditApprove`	负责人修改任务审批通过。
POST	`/api/openplatform/tasks/{id}/actions/urge`	催办任务，可通过 `requiresReceipt` 指定是否需要催办回执。
GET	`/api/openplatform/tasks/{id}/actions/urgeReceipt`	获取催办回执状态。

共用请求体字段

字段	类型	适用接口	说明
`reason`	string	拒收、审核、审批、申诉、撤销、挂起、激活等	操作原因。提交前按 URL 编码规则处理，未填写时可省略或传空字符串。
`attachmentUrls`	string[]	添加附件、审核、审批、申诉、拒收、挂起、完成等	附件访问 URL 列表，不传资源内部 Guid。
`assigneeVirtualId`	string	分解、转发	当前 API Key 下目标负责人的员工 `virtualId`。
`assigneeVirtualIds`	string[]	分解	分解任务时的负责人 `virtualId` 列表。
`checkerVirtualId`	string	分解、任务修改	当前 API Key 下检查人或结果审核人的员工 `virtualId`。
`ccVirtualIds`	string[]	分解、任务修改	抄送或参与员工的 `virtualId` 列表。
`checkItemId`	string	分解、变更检查项、负责人修改	开放平台任务检查项标识，使用任务详情返回的公开值，不直接传内部模型 Guid。
`content`	string	分解、负责人修改	任务内容或修改内容，富文本按 URL 编码提交。
`dueAt`	string	分解、重发、激活、负责人修改	带时区的 ISO 8601 时间字符串。
`score`	decimal	分解、激活	贡献点数量，单位为“点”。
`actionType`	int	负责人修改	负责人修改类型，以负责人修改初始化接口返回的类型值为准。
`requiresReceipt`	bool	催办	是否需要催办回执。
`value`	string	负责人修改	修改后的值；数组字段按 JSON 字符串提交，员工标识使用 `virtualId`。
`isEdit`	bool	负责人修改、拒收、申诉等	是否按编辑场景处理。
`title`	string	分解、重发	子任务或重发任务标题。
`priority`	int	分解、重发	任务优先级。
`sendAt`	string	分解、重发	发送时间，使用 ISO 8601 格式。
`completeAttachment`	bool	分解、完成	完成任务是否要求上传附件。
`checkItems`	object[]	分解、审核不通过	检查项数组。每项可传 `id`、`name`、`reason`、`attachmentUrls`；审核驳回时按检查项记录不通过原因。
`customItem`	object[]	完成	按任务自定义项模型传递完成结果。

负责人修改截止时间：当 actionType=5 时必须传 dueAt，使用带时区的 ISO 8601 时间字符串；开放平台会将该字段提交为截止时间修改值。

操作响应

{
  "statusCode": 100,
  "msg": "操作已受理",
  "data": null
}

最终状态确认：任务操作返回成功只代表网关已受理请求。请再次调用任务详情、操作记录或订阅对应的 task.* Webhook 事件确认最终状态。