慧企星助开放平台文档

便签与便签包接口

便签和便签包接口分别使用 notes.read、notes.write 权限。业务 Id、便签 Id、便签包 Id 可以使用 Guid；员工字段统一使用 virtualId。

POST/api/openplatform/notes

新增便签。成功时响应 data 返回新建便签 Id（Guid），后续详情、共享、修改等操作应使用该 Id。

{
  "title": "开放平台便签",
  "content": "便签内容",
  "parentId": "便签包或便签夹 Guid，可选",
  "priority": 3,
  "type": 1,
  "score": 0,
  "dueAt": "2026-08-22T17:32:50+08:00",
  "assigneeVirtualIds": ["负责人 virtualId"],
  "checkerVirtualId": "审核人 virtualId",
  "ccVirtualIds": [],
  "labelIds": [],
  "attachmentUrls": []
}

GET/api/openplatform/notes

获取当前员工可见便签列表。统一使用 page、pageSize 和 keyword 分页筛选；可选 startAt、endAt、group、noteType。

GET/api/openplatform/notes/{id}

获取便签详情。另有 /search、/shares、/records、/{id}/shareRecord 查询接口。

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

便签写操作的 action：delete、star、share、cancelShare、editPermission、lock、unlock、toPackage、singleEdit、send、setTop、uploadAttachment。所有写操作均使用当前动作资源路径。

路径中的 {id} 为便签 Id。除下表标明的参数外，动作请求体传空对象 {}。员工参数必须使用当前 API Key 下的 virtualId，不能传真实员工 Guid。

action	请求体示例	参数说明
`delete`	`{}`	无请求参数。删除当前便签。
`star`	`{}`	无请求参数。切换当前便签的关注状态。
`share`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"], "canEdit": true, "canDelete": false, "canSend": false }`	`sharedEmployeeVirtualIds` 必填；权限布尔值可选，省略时按 `false` 处理。
`cancelShare`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"] }`	`sharedEmployeeVirtualIds` 必填，要取消共享的员工列表。
`editPermission`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"], "canEdit": true, "canDelete": false, "canSend": true }`	`sharedEmployeeVirtualIds` 必填，通常传一个共享员工；三个权限字段用于修改编辑、删除、发送权限。
`lock` / `unlock`	`{}`	无请求参数。锁定或解锁当前便签。
`toPackage`	`{ "packageId": "便签包或便签夹 Guid" }`	`packageId` 必填，将当前便签移动到指定便签包。
`singleEdit`	`{ "noteType": 1, "content": "新的标题" }`	`noteType` 和 `content` 必填，具体格式见下方“单项修改 noteType”。
`send`	`{ "isRemove": false }`	`isRemove` 可选，是否发送成功后删除便签，默认 `false`。当前便签必须已有负责人。
`setTop`	`{}`	无请求参数。切换当前便签置顶状态。
`uploadAttachment`	`{ "url": "https://www.example.com/file.txt" }`	`url` 和 `resId` 至少传一个。`url` 为附件公开地址，`resId` 为附件上传接口返回的资源 Id。

singleEdit 的 noteType 参数

noteType	content 格式	说明
`1`	普通字符串	修改标题。
`2`	HTML 字符串	修改便签内容。
`3`	JSON 字符串	修改贡献点、预计工时和难度，例如 `{"score":5,"difficulty":2,"workingHoursData":{"estimated":8,"unit":1}}`。
`4`	数字字符串	修改优先级，取值 `1` 到 `5`。
`5`	带时区的 ISO 8601 时间字符串	修改截止时间。
`6`	检查项 JSON 字符串	按详情接口返回的检查项结构提交检查项变更。
`9`	能力 Id 字符串	修改能力需求。
`10`	带时区的 ISO 8601 时间字符串	修改定时发送时间。
`11`	象限值	修改所在象限，取值 `1`：重要且紧急，`2`：重要不紧急，`3`：不重要紧急，`4`：不重要不紧急。
`45`、`46`、`47`、`48`、`49`、`54`	按对应业务模型提交	分别用于自定义项新增/修改、删除自定义项、删除自定义组、切换里程碑、修改预计工时、修改难度。涉及内部自定义项结构的动作，建议先读取详情后按原结构提交。

员工字段限制：singleEdit 的负责人、参与人、审核人内部动作仍要求员工 Id 数组或 Guid。开放平台当前不公开这些未完成 virtualId 转换的单项修改类型（7、8、18），请勿直接传真实员工 Guid。

异步说明：delete、share、cancelShare、lock、unlock、send 为队列型操作，返回成功只表示请求已受理；最终结果请通过详情或 Webhook 确认。

POST/api/openplatform/notePackages

新增便签包，请求字段为 title、content、sharedEmployeeVirtualIds。成功时响应 data 返回新建便签包 Id（Guid）。便签夹使用 POST /api/openplatform/notePackages/folders，字段为 parentId、title、folderType，成功时同样返回新建便签夹 Id。

GET/api/openplatform/notePackages

获取便签包列表。其他查询包括 /{id}、/{id}/notes、/search、/tree、/tree/all、/{id}/shareRecord；/tree 的 parentId 可省略，省略时返回根节点。

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

便签包或便签夹 action：delete、deleteFolder、edit、editFolder、singleEdit、star、share、cancelShare、editPermission、toPackage、toNote、toPlan、move。

路径中的 {id} 为便签包或便签夹 Id。除下表标明的参数外，动作请求体传空对象 {}。员工参数必须使用当前 API Key 下的 virtualId。

action	请求体示例	参数说明
`delete`	`{}`	无请求参数。删除当前便签包。
`deleteFolder`	`{}`	无请求参数。删除当前便签夹。
`edit`	`{ "title": "新的包名称", "content": "新的备注" }`	`title` 必填，`content` 可选。修改便签包名称和备注。
`editFolder`	`{ "title": "新的夹名称", "noteType": 1 }`	`title` 必填；`noteType` 可选，象限取值 `1` 到 `4`。
`singleEdit`	`{ "noteType": 1, "content": "新的名称" }`	`noteType` 和 `content` 必填。`noteType=1` 修改名称，`noteType=2` 修改备注。
`star`	`{}`	无请求参数。便签包仅允许创建人切换关注状态。
`share`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"], "canEdit": true, "canDelete": false, "canSend": false }`	`sharedEmployeeVirtualIds` 必填；权限布尔值可选，省略时按 `false` 处理。
`cancelShare`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"] }`	`sharedEmployeeVirtualIds` 必填，要取消共享的员工列表。
`editPermission`	`{ "sharedEmployeeVirtualIds": ["员工 virtualId"], "canEdit": true, "canDelete": false, "canSend": true }`	`sharedEmployeeVirtualIds` 必填，通常传一个共享员工；三个权限字段用于修改共享权限。
`toPackage`	`{}`	无请求参数。将当前便签夹转换为便签包。
`toNote`	`{ "noteType": 1 }`	`noteType` 可选，目标便签象限取值 `1` 到 `4`，默认 `1`。
`toPlan`	`{ "noteType": 1, "projectId": "项目 Guid", "planTask": "[{\"groupId\":\"分组 Guid\",\"taskList\":[\"便签 Guid\"]}]" }`	`projectId` 必填；`noteType` 为 `1`：只转入选中的便签，`2`：按便签包范围校验并转入包内选中的便签；`packageId` 可选，省略时使用路径中的 `{id}`；`planTask` 为 JSON 字符串。
`move`	`{ "sourceId": "源便签包或夹 Guid", "targetId": "目标便签包或夹 Guid", "targetPosition": 1 }`	`sourceId`、`targetId` 必填；`targetPosition` 可选，象限取值 `1` 到 `4`，默认 `1`。

异步说明：delete、deleteFolder、share、cancelShare 为队列型操作，返回成功只表示请求已受理；最终结果请通过详情或 Webhook 确认。

身份字段说明：返回结果中的创建人、负责人、共享人和操作人统一使用 virtualId 或 *VirtualIds。员工对象只返回公开展示字段和 virtualId，不会返回手机号、账号、部门内部 Id 或真实员工 Guid。请求中涉及员工身份时，请使用当前 API Key 对应的 /employees 接口返回的公开标识。