慧企星助 开放平台文档

慧企星助 开放平台面向企业三方系统提供标准 HTTP API，支持员工、绑定关系、项目、目标与目标复盘、任务、通知、便签、标签、贡献点和附件上传能力。 所有接口默认只作用于当前 API Key 所属企业，权限由后端统一控制并在请求时强校验。

显示全部接口

任务接口

任务接口支持列表、详情和创建。创建任务时必须通过 X-Employee-Virtual-Id 统一指定当前创建人。

当前员工要求：创建任务时如果未提供 X-Employee-Virtual-Id，会直接返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前企业下的创建人”。
GET /api/openplatform/tasks

查询任务列表。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403，错误信息为"请通过 X-Employee-Virtual-Id 指定当前访问用户"。
参数类型必填说明
pageint否页码，默认 1。
pageSizeint否每页条数，默认 20，最大 100。
statusint否任务状态过滤。
keywordstring否任务标题关键字。
 
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 1,
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "完成季度复盘",
        "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "dueAt": "2026-06-19T00:00:00+08:00",
        "priority": 3,
        "status": 2,
        "createdAt": "2026-06-17T18:40:00+08:00"
      }
    ]
  }
}
GET /api/openplatform/tasks/{id}

查询任务详情。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403，错误信息为"请通过 X-Employee-Virtual-Id 指定当前访问用户"。
{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "完成季度复盘",
    "content": "
整理经营数据并输出总结
",
    "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "dueAt": "2026-06-18T00:00:00+08:00",
    "priority": 3,
    "status": 2,
    "createdAt": "2026-06-17T16:00:00+08:00",
    "apiKeyName": "我的三方应用",
    "checkItems": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "name": "整理经营数据",
        "isFinish": false
      }
    ]
  }
}
字段说明：apiKeyName 表示创建该任务的三方应用名称，非开放平台创建的任务该字段为空字符串；checkItems 为任务检查项列表，每项包含公开 id、name 和是否完成的 isFinish。
POST /api/openplatform/tasks

创建任务。

参数类型必填说明
titlestring是任务标题。
contentstring否编码后的富文本内容。请按 URL 编码口径提交；开放平台接收后会先做 URL 解码，再做 HTML 解码，最终按原始富文本存储。
assigneeVirtualIdsstring[]条件必填负责人 virtualId 列表。正式发送任务时至少 1 个；保存草稿时可不传。
checkerVirtualIdstring否考核人 virtualId。
ccVirtualIdsstring[]否抄送人 virtualId 列表。
priorityint否优先级，默认 3。
dueAtstring条件必填截止时间。正式发送任务时必填；保存草稿时可不传。传值时必须显式带时区信息，例如 2026-06-18T00:00:00+08:00 或 2026-06-17T16:00:00Z。
scoredecimal否关联贡献点，单位为“点”。
labelIdsguid[]否标签 ID 列表。
projectIdguid否所属项目 ID。不传时请直接省略该字段，或显式传 null；不要传空字符串 ""。
isDraftbool否是否保存草稿。
sendAtstring否发送时间，ISO 8601 标准时间字符串，且必须显式带时区信息，例如 2026-06-17T19:00:00+08:00 或 2026-06-17T11:00:00Z。
completeAttachmentbool否完成任务时是否必须上传附件。
checkItemsstring[]否检查项列表。
attachmentUrlsstring[]否已上传附件 URL 列表。
 
{
  "title": "完成季度复盘",
  "content": "%3Cp%3E%E6%95%B4%E7%90%86%E7%BB%8F%E8%90%A5%E6%95%B0%E6%8D%AE%E5%B9%B6%E8%BE%93%E5%87%BA%3Cstrong%3E%E6%80%BB%E7%BB%93%3C%2Fstrong%3E%3C%2Fp%3E",
  "assigneeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "priority": 3,
  "dueAt": "2026-06-18T00:00:00+08:00",
  "score": 5
}
富文本约定：content 必须传已做 URL 编码的富文本字符串，例如先把 <p>...</p> 执行 encodeURIComponent 后再提交。开放平台会先做 URL 解码，再补做 HTML 解码，最终按富文本原文存储。
请求体约定：可选的 guid 字段（如 projectId）如果没有值，请直接省略或传 null；不要传空字符串 ""。dueAt、sendAt 传值时必须使用带时区信息的 ISO 8601 标准时间字符串，例如 2026-06-18T00:00:00+08:00 或 2026-06-17T16:00:00Z；不接受没有时区的裸时间字符串。score、isDraft、completeAttachment 建议按标准 JSON 数字/布尔值传递，不要全部转成字符串。
草稿规则：当 isDraft=true 时，当前开放平台只强制要求 title；assigneeVirtualIds、dueAt、checkerVirtualId、ccVirtualIds、score、labelIds、projectId、sendAt、completeAttachment、checkItems、attachmentUrls 都可省略。正式发送任务时，仍至少需要负责人和截止时间。
{
  "statusCode": 100,
  "msg": "创建成功",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "完成季度复盘",
    "createdAt": "2026-06-17T16:00:00+08:00"
  }
}
兼容性提示：score 支持按数字提交，也兼容数字字符串；但仍建议三方按标准 JSON 数字传值，避免不同语言序列化差异。
DELETE /api/openplatform/tasks/{id}

撤销任务。只有任务创建人才能撤销，且任务状态必须为进行中、待开始、暂停、待审批、草稿、拒收、新任务、审批不通过、转发中、挂起申请之一。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。
DELETE /api/openplatform/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Host: your-domain.com
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

路径参数：

参数类型必填说明
idguid是任务 ID。
 
{
  "statusCode": 100,
  "msg": "撤销成功"
}
注意事项：撤销任务是不可逆操作，请谨慎调用。如果任务有子任务，必须先撤销所有子任务。撤销成功后会触发 task.canceled Webhook 事件。
PATCH /api/openplatform/tasks/{id}

修改任务。请求体必须且只能包含一个可修改字段。

必填请求头：必须提供 X-Employee-Virtual-Id。未传时返回 403。
PATCH /api/openplatform/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Host: your-domain.com
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

路径参数：

参数类型必填说明
idguid是任务 ID。

请求体参数：

字段类型必填说明
titlestring否任务标题。
contentstring否任务内容。
scoredecimal否任务贡献点，单位为“点”。
priorityint否任务优先级。
dueAtstring否截止时间，ISO 8601。
assigneeVirtualIdstring否负责人 virtualId。
checkerVirtualIdstring否检查人 virtualId。
ccVirtualIdsstring[]否抄送人 virtualId 列表。
reasonstring否修改原因，建议填写以便追溯

请求示例 1：修改标题

{
  "title": "修改后的任务标题",
  "reason": "标题描述不准确"
}

请求示例 2：修改截止时间

{
  "dueAt": "2026-06-20T18:00:00+08:00",
  "reason": "项目延期"
}

请求示例 3：修改负责人

{
  "assigneeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"
}

响应示例：

{
  "statusCode": 100,
  "msg": "修改成功"
}
字段格式说明：
  • title：字符串，如 "新任务标题"
  • content：URL 编码后的富文本字符串，需先 encodeURIComponent("<p>内容</p>")
  • score：数值，如 5.5
  • priority：整数(1-5)，如 3(1最高，5最低)
  • dueAt：ISO 8601 时间字符串(必须带时区)，如 "2026-06-18T00:00:00+08:00"
  • assigneeVirtualId：单个负责人 virtualId，如 "emp_xxx"
  • ccVirtualIds：virtualId 数组，如 ["emp_xxx1"]
  • checkerVirtualId：单个检查人 virtualId，如 "emp_xxx"
注意事项：修改操作异步处理，返回成功表示请求已接受。修改内容时，content 必须先做 URL 编码；修改截止时间时，dueAt 必须带时区信息。修改成功后会触发 task.changed Webhook 事件。
Webhook 异步触发说明：task.changed 事件是异步触发的。接口返回成功仅表示修改请求已提交到消息队列，实际修改操作由后台异步处理。第三方应用应在收到 task.changed Webhook 事件后，通过事件负载中的最新数据更新本地缓存，不要依赖接口返回立即查询任务详情，因为此时修改可能尚未完成。
© 2026 郑州星云互联 开放平台