接入概览
开放平台使用 API Key + HMAC-SHA256 签名鉴权。请求必须携带标准请求头，部分接口还要求通过 X-Employee-Virtual-Id 明确当前访问员工。
基础规则
- 所有接口根路径为
/api/openplatform。 - 所有返回体统一为
statusCode、msg、data结构。 - 写动作成功时
data恒为非空回执对象，与 MCP 工具同一口径：批量动作回{ids, action}；路由点名单对象的动作回{id, action}；源站不回对象标识且路由上也无对象的动作（如网盘文件入库、奖章排行榜设置）只回{action}，不会拿父资源标识冒充被操作对象；创建类接口回{id}（新对象标识由源站给出）。任务模块（含动作、字段修改、标签替换、撤销）同样适用。 - 接口只作用于当前 API Key 所属企业，不支持跨企业访问。
- 权限项由后端统一返回并在请求时强校验，空权限不会默认放行。
- 所有会写入数据的
POST、PUT、PATCH、DELETE请求必须携带X-Client-Request-Id，值为客户端生成的 UUID。同一业务重试必须使用相同 UUID，并重新生成X-Nonce、X-Timestamp和签名。
统一员工识别规则
/employees会为当前 API Key 下的每个企业成员实时返回唯一且稳定的virtualId，不需要预先分配或额外落库。- 需要识别“当前访问用户/操作人/创建人”的接口，统一通过
X-Employee-Virtual-Id传当前员工的virtualId。 - 如果接口要求当前员工身份但未传该请求头，服务端会直接返回
403。 - 绑定接口用于建立第三方账号与当前 API Key 下员工
virtualId的映射关系。
贡献单位统一说明：开放平台中的贡献单位统一为“点”。任务关联贡献和贡献点变更接口都使用“点”，不使用“分”。
写请求重试说明：请求超时或网络中断时，不要使用新的
X-Client-Request-Id 重新提交。请使用原请求标识重试；若服务端返回“执行结果待确认”，请先按该请求标识核对结果，避免重复创建业务数据。
企业套餐限制：接口受企业套餐约束，与工作台同一口径。企业套餐到期后的 30 天内仅支持只读访问（
GET 查询类接口放行，写操作返回 statusCode=2100）；到期超过 30 天后全部接口停用（返回 statusCode=2101）。任务、便签、项目、目标、贡献等业务接口还要求企业已购买对应功能模块，未购买时读写都会被拒绝（返回 statusCode=2102）。详见「错误码与排查」。
写类操作返回结构规范
全部写类接口（POST / PATCH / DELETE 动作与创建类接口）适用本规范，覆盖任务、便签、标签、项目、目标、项目任务、自动化任务、悬赏任务、汇报、福利、贡献、成就、奖章、网盘、附件各模块；REST 的 data 节点与 MCP 工具的结构化回执（structuredContent）键集完全同一条口径。键集合本身就是契约：多键少键都视为契约变更。
| 成功形态（HTTP 200 且 statusCode=100） | 适用动作 | 示例 |
|---|---|---|
{id, action} | 路由点名单对象的动作：重命名、删除、审核通过/不通过、撤销、置状态等 | {"id":"1a2b…","action":"rename"} |
{ids, action} | 请求体携带对象集合的批量动作：网盘删除/转移/复制 | {"ids":["1a2b…"],"action":"copy"} |
{action} | 源站不回对象标识、路由上也无对象标识的动作：网盘文件入库（upload）、奖章排行设置（setRankMedal） | {"action":"upload"} |
{id} | 创建类接口：新对象标识由源站生成并回传 | {"id":"1a2b…"} |
action是公开动作名，取值以各资源文档的响应示例为准；它表示「已受理该动作」，队列受理型动作不代表业务终态，终态请用对应查询接口确认。- 不允许拿父资源标识冒充被操作对象：路由上没有对象标识且源站不回 Id 时，回执只含
action。 - 创建类接口（如新增便签、新增标签、新增文件夹）回执只含新对象
id，不带 action。
| 失败形态（HTTP 非 200） | 说明 |
|---|---|
{statusCode, msg, data:null} | msg 为可读原因并点名具体参数或资源（如「个人标签颜色必须是预置色板之一：…」「备注和附件必须填写一项！」）；HTTP 状态与 statusCode 的对照见「错误码与排查」。 |
| 网关侧参数校验失败 | 与业务失败同形：一律 400 + 点名原因（如 color 不在色板、缺 X-Client-Request-Id、团队标签传入 color），不静默吞参数、不返回空对象，且校验失败不会向源站发起写入。 |
| MCP 工具失败 | 返回 isError 结构，文本与结构化内容给出与 REST 同源的可读原因；参数级错误在调用源站前即被拦截。 |
成功与失败的判别口径：HTTP 200 且 statusCode=100 即成功，data 保证为非空回执对象；其余一律视为失败，以 msg 为准。调用方不需要也不应该通过二次回读来判断一次写操作的结果。