接入概览
开放平台使用 API Key + HMAC-SHA256 签名鉴权。请求必须携带标准请求头，部分接口还要求通过 X-Employee-Virtual-Id 明确当前访问员工。
基础规则
- 所有接口根路径为
/api/openplatform。 - 所有返回体统一为
statusCode、msg、data结构。 - 接口只作用于当前 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 重新提交。请使用原请求标识重试；若服务端返回“执行结果待确认”，请先按该请求标识核对结果，避免重复创建业务数据。