乾策立方 开放平台文档

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

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

获取当前员工可见便签列表。统一使用 page、pageSize 和 keyword 分页筛选；可选 startAt、endAt、group、noteType、includeSummary（默认 true，传 false 时列表项不含 summary）。

列表响应字段

Note 通用字段

GET /api/openplatform/notes、/notes/search、/notes/shares、/notePackages/{id}/notes 的 items 单项，以及 GET /api/openplatform/notes/{id} 的详情，均使用以下公开资源字段。

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

响应字段：返回一个完整 Note 对象，字段、类型和含义见上方“Note 通用字段”。

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

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

singleEdit 的 noteType 参数

全量替换便签标签：以请求中的标签 Id 集合为最终状态，需要新增与移除的标签由平台自动补差完成，与工作台标签维护同链路（操作人需有便签权限）。同步处理，返回成功即已生效。

请求示例：

PUT /api/openplatform/notes/a1b2c3d4-e5f6-7890-abcd-ef1234567890/labels
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

{
  "labelIds": [
    "2f6e8a10-3c4b-4d5e-9f80-a1b2c3d4e5f6"
  ]
}

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

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

列表和详情响应字段

新增便签夹。权限 notes.write，必须带 X-Employee-Virtual-Id。成功响应 data 为 {id}（新建便签夹标识）。

失败情况：同名（同企业、同创建人、同父级）返回 400 且 statusCode=103，错误信息为“新增便签夹名称不能重复”；写入事务回滚时返回 400 且 statusCode=103，错误信息为“新增失败”。

获取便签包详情。权限 notes.read，必须带 X-Employee-Virtual-Id。data 为单个 NotePackage 对象（字段见上方“列表和详情响应字段”），另含 shareUser、isPermitEdit、isPermitDelete、isPermitSend、remark、operateBtns。

失败情况：包不存在返回 400 且 statusCode=101，错误信息为“便签包不存在”；无查看权限返回 400 且 statusCode=102，错误信息为“您没有权限查看该便签包”。

获取便签包内的便签与便签夹。权限 notes.read，必须带 X-Employee-Virtual-Id。

data 为分页结构 {total, page, pageSize, items}，其中 total 是源站统计的真总数。

跨便签包搜索便签。权限 notes.read，必须带 X-Employee-Virtual-Id。查询参数与 /{id}/notes 同形。

includeSummary 仅对 GET /api/openplatform/notes 生效，本接口不透传、也不会返回摘要字段。

获取便签包树的一层节点。权限 notes.read，必须带 X-Employee-Virtual-Id。data 为数组（非分页结构）。

节点字段：本接口填 label（节点名称）、id、type、hasChildren，其中 name 为 null。

一次性获取当前操作人的完整便签包树（便签包 + 递归便签夹）。权限 notes.read，必须带 X-Employee-Virtual-Id。无查询参数，data 为数组，子级在 children 里。

获取便签包共享记录。权限 notes.read，必须带 X-Employee-Virtual-Id。无查询参数。

data 为对象 {shareRecordList, shareUser}：shareRecordList 是共享操作流水；shareUser 首项恒为当前操作人且 isCreater=true、三项权限为 true，其余成员来自共享授权表，字段为 {id, img, trueName, isPermitEdit, isPermitDelete, isPermitSend, isCreater, time}。

失败情况：包不存在 400 且 statusCode=101“便签包不存在”；无权限 400 且 statusCode=102“您没有权限查看”。只读，不写数据、不排队。

获取便签共享记录。{id} 为便签 Id，权限 notes.read，必须带 X-Employee-Virtual-Id。响应结构与便签包的同名接口一致：{shareRecordList, shareUser}，人员标识按当前 Key 归一为 virtualId。

失败情况：便签不存在返回 400 且 statusCode=101，错误信息为“便签不存在”。本接口只校验存在性、不校验读权限，与便签详情接口的权限口径不同。只读，不写数据、不排队。

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

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