钉钉开发“待办“接口版本调研-编程实验室

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

结论速览

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

一、接口详细对比表

特性	旧版 (WorkRecord / OA消息)	新版 (Todo / 统一待办)
核心逻辑	发送一条带有状态栏的消息	创建一个原生的任务对象
用户入口	聊天列表 -> 工作通知	钉钉客户端底部“待办”Tab/ 聊天侧边栏 / 日历
API 版本	OAPI (Old style)	Open API v1.0 (RESTful)
权限要求	基础的消息发送权限	需申请`todo.write`等特定权限
交互体验	消息流形式，容易被刷走	列表形式，长期驻留，直到完成
删除功能	仅支持更新状态，很难物理删除	支持物理删除
文档地址	已标记为不推荐或旧版	钉钉待办任务文档

二、接口调用方式对比

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)

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

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

四、总结与建议

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