钉钉开发“待办“接口版本调研

钉钉开发"待办"接口版本调研

结论速览

• 旧版 (WorkRecord / OA消息)：本质是“消息”。入口在“工作通知”会话窗口中。数据孤岛，无法与钉钉主界面的“待办”Tab打通。
• 新版 (Todo 2.0)：本质是“任务”。入口在钉钉底部的“待办”Tab、日历以及侧边栏。支持设置截止时间、执行人，且UI体验是原生的。
• 推荐：强烈建议使用新版 (Todo)。旧版接口已逐渐边缘化，且无法进入用户的核心任务管理视图。

一、 接口详细对比表

二、 接口调用方式对比

1. 推送待办 (Create)

旧版 (WorkRecord)

旧版通常使用“发起待办事项”接口。

• Endpoint:POST /topapi/workrecord/add
• 特点:需要构建一个表单列表（FormItem），用户点击后跳转到第三方URL。
• 缺点:只是在“工作通知”里发了一条消息，用户如果不点进去，很容易忽略。

新版 (Todo)

新版是在用户的待办中心创建一个实体任务。

• Endpoint:POST /v1.0/todo/users/{unionId}/tasks

• Payload 示例:

  { "subject": "请审批合同文件", "description": "2024年度采购合同", "dueTime": 1703664000000, // 截止时间 "executorIds": ["user123"], // 执行人 "isOnlyShowExecutor": true, "sourceId": "unique_id_from_your_system" // 业务系统唯一ID，防重 }

• 优势:支持设置截止时间（会有强提醒），直接出现在待办清单中。

2. 置已办 (Update Status)

旧版 (WorkRecord)

旧版通过更新待办事项的状态来“置已办”。

• Endpoint:POST /topapi/workrecord/update
• 逻辑:传入record_id，将状态字段更新。
• 表现:用户聊天窗口里的那条消息，状态栏颜色变化（如从红变绿），文字变为“已完成”。

新版 (Todo)

新版通过更新任务状态接口。

• Endpoint:PUT /v1.0/todo/users/{unionId}/tasks/{taskId}/status

• Payload:

  JSON

  { "isDone": true }

• 表现:该任务自动从用户的“待办”列表中移动到“已完成”列表，并划掉。

3. 删除待办 (Delete)

旧版 (WorkRecord)

• 接口:无直接删除接口。
• 替代方案:只有“撤回消息”的概念 (/topapi/message/corpconversation/recall)，或者将其状态更新为“取消”。这导致旧版数据清理非常麻烦。

新版 (Todo)

• Endpoint:DELETE /v1.0/todo/users/{unionId}/tasks/{taskId}
• 逻辑:物理删除。调用后，该任务从用户的任何视图中彻底消失。
• 优势:适合处理脏数据或业务回滚场景。

三、 迁移注意事项 (Pitfalls)

如果您决定从旧版迁移到新版，或者直接开发新版，请注意以下“坑”：

1. UnionId vs Userid:
   • 旧版接口大量使用userid。
   • 新版 v1.0 接口为了标准化，RESTful 路径中通常要求使用unionId。你需要先通过userid换取unionId，或者维护两者的映射关系。
2. sourceId 的重要性:
   • 在新版创建待办时，务必传入sourceId（你们业务系统的主键ID）。这样后续更新状态时，虽然标准API推荐用taskId（钉钉生成的ID），但部分SDK允许通过sourceId查找到任务，防止网络抖动导致的重复创建。
3. 应用类型:
   • 新版待办接口目前主要开放给企业内部应用（H5微应用或小程序）。如果是第三方ISV应用，权限申请流程会有所不同。
4. 点击跳转:
   • 新版待办支持配置appUrl（移动端跳转）和pcUrl（PC端跳转）。务必配置这两个参数，否则用户点击待办卡片无法跳转到你们的审批/详情页面。

四、 总结与建议

• 如果你的需求是：仅仅是发个通知提醒用户，不需要用户跟踪状态，也不需要归档。
  • -> 使用工作通知 (OA消息)接口（不是WorkRecord，是Message）。
• 如果你的需求是：真正的任务流转（如OA审批、任务指派），希望用户能有一个清单统一管理，做完一个少一个。
  • ->必须使用 新版 (Todo) 接口。