慧企星助开放平台文档

任务操作接口

以下接口对应任务接收、执行、审核、审批、转发、挂起和历史任务处理等操作。所有接口都必须携带 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`	任务列表统一入口：待我操作、我负责的、我参与的、历史任务通过 `view` 范围参数传入（`pendingActions` 待我操作 / `ownedByMe` 我负责的 / `involvedByMe` 我参与的 / `history` 历史任务），不传为全部可见。原 `/tasks/owned`、`/tasks/involved`、`/tasks/pending` 三个专用端点已下线，请迁移到统一入口。

列表请求参数：任务列表统一使用 GET /api/openplatform/tasks，除 page、pageSize 外支持 keyword、view（范围：待我操作/我负责的/我参与的/历史任务）、statuses（业务状态集合，含 completed 已完成、forwarding 转发中）、labelIds、creatorVirtualId、assigneeVirtualId、priority、dueAtFrom、dueAtTo、receivedAtFrom、receivedAtTo、healthDegree、taskType、projectStatus 等筛选字段，除 view=history 外均可自由组合叠加；状态筛选只通过 statuses 业务分组表达，无单值精确状态参数。返回结构统一为 {"statusCode":100,"msg":"获取成功","data":{"total":0,"page":1,"pageSize":20,"items":[]}}；items 单项使用任务接口“TaskListItem 字段”表定义的字段和类型。

任务执行、审核与审批

方法	路径	说明
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`	获取催办回执状态。

REST 动作与 MCP 动作名对照

口径说明：REST 的动作由路径段区分（如 /actions/auditPass），MCP 的 task_execute_action 由 action 参数传内网动作名（PascalCase），二者提交到同一内网动作，对照见下表。metadata_describe_action 的 action 使用本页 Init 表中的小写初始化名，与动作名是两个维度。暂停（Pause）后的恢复用 Start；挂起（Hang）后的恢复用 RecoveryExecute，二者不可混用。

REST 路径段	MCP action	REST 路径段	MCP action
`decompose`	`Decompose`	`receive`	`Receive`
`start`	`Start`	`pause`	`Pause`
`refuse`	`Refuse`	`auditPass`	`AuditComplete`
`auditNoPass`	`Overrule`	`confirmReject`	`ConfirmOverrule`
`appeal`	`Complain`	`rejectAppeal`	`RejectComplain`
`forward`	`Relay`	`forwardApprove`	`RelayExamPass`
`forwardReject`	`RelayExamNoPass`	`forwardCancel`	`CancelRelay`
`forwardReceive`	`RelayReceive`	`forwardRefuse`	`RelayRefuse`
`resend`	`Repeat`	`confirmChange`	`Confirm`
`changeCheckItem`	`ChangeCheckItem`	`complete`	`Complete`
`approveNoPass`（审批）	`Rebut`	`approvePass`	`Pass`
`sendDraft`	`SendDraft`	`checkItemToNote`	`CheckItemToNote`
`cancelApply`	`CancelTaskApply`	`passCancelApply`	`PassCancelTaskApply`
`rejectCancelApply`	`NoPassCancelTaskApply`	`forceCancel`	`MustCancelTask`
`directDelete`	`Delete`	`activate`	`ChangeToIng`
`confirmActivate`	`ConfirmToIng`	`activateAppeal`	`RebutToIng`
`confirmActivateAppeal`	`CreConfirmRebut`	`forceActivate`	`MustToDo`
`cancelActivate`	`CancelToIng`	`follow`	`StarTask`
`approveToInProgress`	`ExamToIng`	`responsibleCancelToInProgress`	`ExeCancelApplyToIng`
`creatorCancelToInProgress`	`CreCancelApplyToIng`	`applyStart`	`FiringApply`
`withdrawStart`	`CancelFiringApply`	`approveStart`	`FiringApplyPass`
`rejectStart`	`FiringApplyNoPass`	`applySuspend`	`Hang`
`cancelSuspend`	`CancelHangApply`	`approveSuspend`	`PassHang`
`rejectSuspend`	`NoPassHang`	`resume`	`RecoveryExecute`
`executorEdit`	`ExeSingleEdit`	`executorCancelEdit`	`ExeCancelSingleEdit`
`executorEditReject`	`ExeEditNoPass`	`executorEditApprove`	`ExeEditPass`
`urge`	`Urge`

字段级修改（task_update / PATCH）

通道说明：除上述「负责人申请修改确认」流程外，开放平台还提供直接发起的字段级修改通道：REST 用 PATCH /api/openplatform/tasks/{id}（见「任务」页），MCP 用独立工具 task_update。二者提交到同一内网 task/update 通道，经工作台既有校验与操作记录留痕（记录带来源应用标识），支持的字段一致：

字段（MCP field / REST 请求体字段）	值格式	说明
`name`	string	任务名称。
`content`	string	任务内容，URL 编码后的富文本。
`score`	decimal	贡献点，单位「点」，受企业贡献点规则约束。
`priority`	int	优先级 1-5。
`dueAt / dueAt`	string	截止时间，ISO 8601 带时区。
`project / projectId`	guid	任务挂靠项目；空串/空字符串表示移出项目。
`alignTarget / alignTargetId`	guid	对齐的目标；空串表示解除对齐。
`keyResults / keyResultIds`	guid[]	关联的关键结果；空数组表示解除全部关联，需先对齐目标。

MCP task_update 示例：{ "taskId": "<任务Id>", "field": "priority", "value": "4", "reason": "批量调整" }。一次只修改一个字段；修改记录可在 task_get_progress_records 中查看，并带 sourceFrom/sourceAppText 来源标识。

共用请求体字段

字段	类型	适用接口	说明
`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	负责人修改、拒收、申诉等	是否按编辑场景处理。
`name`	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 事件确认最终状态。