慧企星助开放平台文档

悬赏任务接口

悬赏任务接口提供本人创建任务与当前可领取任务的查询，以及创建、单字段修改、领取、撤销、标记已读和附件操作，需要 rewardTasks.read（查询）与 rewardTasks.write（创建与所有写操作）权限。查询范围使用字符串枚举 view：mine 我创建的、available 我可领取的；排序字段使用 sort：time 按时间、score 按贡献点、duration 按时长。所有接口都只访问当前企业且继续由源站校验当前操作人的业务权限。

必填请求头：悬赏任务全部接口（含查询）都必须通过 X-Employee-Virtual-Id 指定当前操作人，接口只返回该员工可见范围内的数据。未传或无效时返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”。

写请求约定：所有 POST、PATCH 请求还需携带 UUID 格式的 X-Client-Request-Id；同一业务重试必须复用同一请求标识，并重新生成 X-Nonce、X-Timestamp 与签名。

标识字段约定：员工字段一律使用 virtualId 传入与返回，接口不会返回员工内部 Guid；labelIds、templateId、fromId、resourceId 是业务对象 Id，与员工身份无关；rewardDepartmentIds 是部门 Id，其中 0 表示全企业。

GET /api/openplatform/rewardTasks

分页查询悬赏任务，需要 rewardTasks.read 权限。

参数	类型	必填	说明
`view`	string	否	查询范围，字符串枚举：`mine` 我创建的、`available` 我可领取的，默认 `mine`；传其它值返回 `400`，错误信息为“view 必须为 mine 或 available”。
`sort`	string	否	排序字段，字符串枚举：`time` 按时间、`score` 按贡献点、`duration` 按时长，默认 `time`；传其它值返回 `400`，错误信息为“sort 必须为 time、score 或 duration”。
`descending`	bool	否	是否降序，默认 `true`；`false` 为升序。
`page`	int	否	页码，从 `1` 开始，默认 `1`。
`pageSize`	int	否	每页条数，默认 `20`，最大 `100`；超过上限返回 `400`。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 6,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "3f5a7b90-1c2d-4e6f-8a9b-0c1d2e3f4a5b",
        "name": "整理客户资料",
        "content": "按要求完成资料整理",
        "score": 5,
        "priority": 3,
        "rewardCount": 1,
        "peopleNumber": 1,
        "receivedCount": 0,
        "duration": 24,
        "cycleType": 1,
        "participants": [
          { "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz", "name": "张三" }
        ],
        "canceledAt": "2026-09-16T18:00:00+08:00",
        "createdAt": "2026-09-15T10:00:00+08:00"
      }
    ]
  }
}

POST /api/openplatform/rewardTasks

创建悬赏任务，需要 rewardTasks.write 权限，并必须传 X-Employee-Virtual-Id。名称 name 不能为空；rewardDepartmentIds 至少需要一个有效部门 Id，rewardCount 与 peopleNumber 必须大于 0。

参数	类型	必填	说明
`name`	string	是	任务名称，不能为空，否则返回 `400`“悬赏任务名称不能为空”。
`content`	string	否	任务内容说明。
`participantVirtualIds`	string[]	否	参与人 `virtualId` 数组。
`labelIds`	guid[]	否	标签 Id 数组（业务对象 Id，非员工 Id）。
`score`	decimal	否	悬赏贡献点，默认 `0`。
`auditScore`	decimal	否	审批贡献点，默认 `0`。
`priority`	int	否	优先级，取值 `1`-`5`，默认 `3`。
`sendHour`	int	否	发送时间的小时，取值 `0`-`23`。
`sendMinute`	int	否	发送时间的分钟，取值 `0`-`59`。
`checkItems`	string[]	否	检查项名称数组。
`attachmentUrls`	string[]	否	附件地址数组，地址先通过附件上传接口取得。
`requiresCompletionAttachment`	bool	否	完成时是否必须上传附件，默认 `false`。
`checkerVirtualId`	string	否	考核人 `virtualId`；不传表示不指定考核人。
`checkerType`	int	否	考核人类型。
`setCheckerType`	int	否	考核人设置方式，`1` 或 `2`。
`rewardDepartmentIds`	int[]	是	可领取部门 Id 数组，`0` 表示全企业。至少传一个且不能为负数，否则返回 `400`“rewardDepartmentIds 至少需要一个有效的部门 Id”。
`rewardCount`	int	否	每人最多领取次数，默认 `1`，必须大于 `0`。
`peopleNumber`	int	否	最多领取人数，默认 `1`，必须大于 `0`。
`isCycle`	bool	否	是否为周期任务，默认 `false`。
`isAllDay`	bool	否	是否全天任务，默认 `false`。
`cycleType`	string	否	周期类型，字符串枚举：`daily`、`weekly`、`monthly`，默认 `daily`；传其它值返回 `400`“cycleType 必须为 daily、weekly 或 monthly”。
`cycle`	string	否	周期取值，逗号分隔的序号串，含义由 `cycleType` 决定。
`canceledAt`	string	否	悬赏截止时间文案。
`duration`	int	否	任务时长（小时）。不传 `dueAt` 时，源站按该时长换算默认截止时间。
`templateId`	guid	否	关联任务模板 Id。
`fromId`	guid	否	来源任务 Id。
`customItem`	string	否	自定义字段内容。
`workingHoursData`	object	否	预计工时数据，含 `estimated`（预计工时）、`unit`（`1` 小时、`2` 天）、`convertRatio`（换算比例）。
`endCondition`	int	否	结束条件：`0` 不限、`1` 按次数、`2` 按日期，默认 `0`。
`startAt`	datetime	否	任务生效开始时间，ISO 8601 格式；不传按当前时间。
`endAt`	datetime	否	任务结束时间，`endCondition=2` 时使用；不传表示不限结束时间。
`intervalNum`	int	否	间隔数，默认 `1`。
`maxExecutions`	int	否	最大执行次数，`endCondition=1` 时使用。
`skipHolidays`	bool	否	是否跳过节假日，默认 `false`。
`skipSaturdays`	bool	否	是否跳过周六，默认 `false`。
`skipSundays`	bool	否	是否跳过周日，默认 `false`。
`difficulty`	int	否	任务难度，取值 `1`-`5`，默认 `2`。
`sendAt`	datetime	否	发送时间，ISO 8601 格式；不传按当前时间。
`dueAt`	datetime	否	截止时间，ISO 8601 格式；不传按 `duration` 小时数换算。

{
  "name": "整理客户资料",
  "content": "按要求完成资料整理",
  "participantVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "labelIds": [],
  "score": 5,
  "auditScore": 0,
  "priority": 3,
  "rewardDepartmentIds": [0],
  "rewardCount": 1,
  "peopleNumber": 1,
  "isCycle": false,
  "isAllDay": false,
  "cycleType": "daily",
  "duration": 24,
  "checkItems": ["资料完整"],
  "attachmentUrls": [],
  "requiresCompletionAttachment": false,
  "difficulty": 2,
  "endCondition": 2,
  "intervalNum": 1,
  "startAt": "2026-09-15T09:00:00+08:00",
  "endAt": "2026-09-20T18:00:00+08:00",
  "sendAt": "2026-09-15T09:00:00+08:00",
  "dueAt": "2026-09-16T18:00:00+08:00",
  "skipHolidays": true,
  "skipSaturdays": false,
  "skipSundays": false
}

事件通知：创建成功会推送 rewardTask.created 事件。

GET /api/openplatform/rewardTasks/{id}

获取悬赏任务详情。任务 Id 为任务资源标识；员工字段统一返回 virtualId，不会返回员工内部 Guid。

PATCH /api/openplatform/rewardTasks/{id}

单字段修改，需要 rewardTasks.write 权限。请求体使用 field 指定要修改的字段名，并传对应字段值；一次只能修改一个字段。

参数	类型	必填	说明
`field`	string	是	要修改的字段名，支持 `name`、`content`、`priority`、`score`、`duration`、`participants`、`checker`。传其它值返回 `400`“不支持的悬赏任务修改字段”。
`name`	string	否	`field=name` 时使用，新名称。
`content`	string	否	`field=content` 时使用，新内容。
`priority`	int	否	`field=priority` 时使用，取值 `1`-`5`。
`score`	decimal	条件必填	`field=score` 时必须提供，新贡献点；只传 `field=score` 而不给值时返回 `400`“修改贡献点必须提供 score”（显式传 `0` 表示把贡献点归零，是合法值）。
`difficulty`	int	否	`field=score` 时使用，任务难度，取值 `1`-`5`；不传沿用任务当前难度。
`estimatedHours`	decimal	否	`field=score` 时使用，预计工时数值，不能为负数；不传沿用任务当前预计工时。
`estimatedHoursUnit`	int	否	`field=score` 时使用，预计工时单位：`1` 小时、`2` 天；不传沿用任务当前单位。
`duration`	int	否	`field=duration` 时使用，新任务时长。
`participantVirtualIds`	string[]	否	`field=participants` 时使用，整体替换参与人列表。
`checkerVirtualId`	string	否	`field=checker` 时使用，新的考核人 `virtualId`；传空表示清空考核人。

{
  "field": "priority",
  "priority": 4
}

贡献点修改语义：源站贡献点修改接口按「贡献点 + 任务难度 + 预计工时」整体覆盖任务属性，因此修改 field=score 时可同时传 difficulty（1-5）、estimatedHours、estimatedHoursUnit（1 小时、2 天）。难度与工时不可回读且未显式传入时，接口会返回 400 拒绝本次修改，不会改写为默认值；score 本身未提供时同样直接拒绝，避免字段缺失把贡献点静默归零。

POST /api/openplatform/rewardTasks/{id}/actions/{action}

执行悬赏任务操作，需要 rewardTasks.write 权限。action 支持以下取值（大小写不敏感）：

action	说明	额外参数
`get`	领取悬赏任务。异步处理，返回“已受理”后请重新查询详情确认结果。	-
`cancel`	撤销悬赏任务。异步处理，返回“已受理”后请重新查询详情确认结果。	-
`setRead`	把悬赏任务标记为已读。	-
`addAttachment`	追加附件，需传附件地址；如需定位已有资源可一并传 `resourceId`。	`url`、可选 `resourceId`

{
  "action": "addAttachment",
  "url": "https://file.example.com/tmp/9f8e7d6c5b4a"
}

事件通知：员工领取悬赏任务成功会推送 rewardTask.received 事件。由定时作业自动触发、无法确定来源 API Key 的领取不推送事件。

调用约束：cancel 会关闭悬赏、影响其他成员领取；get 是当前操作人实际领取任务并占用名额。调用前请向用户确认目标任务与影响范围。队列类操作返回“已受理”只代表消息已投递，最终状态请重新查询详情。

MCP 工具 reward_task_query

悬赏任务查询工具，需要 rewardTasks.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：list 分页列表、detail 任务详情。

{
  "queryType": "list",
  "view": "available",
  "sort": "score",
  "descending": true,
  "page": 1,
  "pageSize": 20
}

参数映射：queryType=detail 必须提供 taskId，对应 REST 路径 {id}；view、sort、descending、page、pageSize 与 REST 语义一致。taskId 为任务资源 Id，不是员工 Id。

MCP 工具 reward_task_action

悬赏任务写操作工具，需要 rewardTasks.write 权限。action 取值：create、update、get、cancel、setRead、addAttachment。

{
  "action": "get",
  "taskId": "3f5a7b90-1c2d-4e6f-8a9b-0c1d2e3f4a5b"
}

参数说明：create 与 update 之外的写操作必须提供 taskId；update 必须提供 field（name/content/priority/score/duration/participants/checker）及对应字段；field=score 时可同时传 difficulty、estimatedHours、estimatedHoursUnit，不传会沿用任务当前值；addAttachment 使用 url 与可选 resourceId。创建参数与 REST 创建请求一致，其中 rewardDepartmentIds 至少传一个有效部门 Id。

调用约束：MCP 写操作直接生效，不经过工作台草稿确认。领取会实际占用名额并计入当前操作人，撤销会影响其他成员领取，调用前必须把任务名称、悬赏贡献点、部门范围与关键参数完整展示给用户并取得明确确认。