钉钉“待办“相关接口调研列表

钉钉"待办"相关接口调研列表

核心定义：在钉钉客户端底部"待办"Tab中显示，有截止时间，有完成状态，支持红点角标。

这是钉钉目前主推的体系，基于 RESTful 风格，必须使用 unionId。

动作	方法	接口路径 (API Path)	说明
新增	POST	`/v1.0/todo/users/{unionId}/tasks`	创建一个新待办（支持设置截止时间、执行人）
更新状态	PUT	`/v1.0/todo/users/{unionId}/tasks/{taskId}/status`	置已办。传入 `{"isDone": true}` 即可完成
修改内容	PUT	`/v1.0/todo/users/{unionId}/tasks/{taskId}`	修改标题、描述、截止时间或执行人
删除	DELETE	`/v1.0/todo/users/{unionId}/tasks/{taskId}`	物理删除。处理脏数据或撤销任务
查询详情	GET	`/v1.0/todo/users/{unionId}/tasks/{taskId}`	获取单条任务的详细信息
查询列表	GET	`/v1.0/todo/users/{unionId}/tasks`	获取某个用户名下的待办列表（支持分页）
查询数量	GET	`/v1.0/todo/users/{unionId}/tasks/count`	获取某个用户的待办总数

官方已停止维护，且需要特殊权限。

动作	方法	接口路径 (API Path)	缺陷/说明
新增	POST	`/topapi/workrecord/add`	无法进入"待办"Tab，只发一条消息
更新	POST	`/topapi/workrecord/update`	只能更新消息里的状态栏颜色
查询	POST	`/topapi/workrecord/getbyuserid`	查询用户未完成的旧版待办

核心定义：出现在"工作通知"聊天窗口中的消息。适用于纯告知、公告、报警。

虽然它是 topapi 开头，但目前依然是发送企业通知的标准接口。v1.0 中对应的是机器人接口，但对于企业内部应用（Agent），这个接口依然最稳。

动作	方法	接口路径 (API Path)	说明
发送	POST	`/topapi/message/corpconversation/asyncsend_v2`	万能接口。支持文本、卡片、OA消息、Markdown
查进度	POST	`/topapi/message/corpconversation/getsendprogress`	根据 `task_id` 查询消息发送成功了多少人
查询结果	POST	`/topapi/message/corpconversation/getsendresult`	获取详细的发送结果清单
撤回	POST	`/topapi/message/corpconversation/recall`	撤回已发送的消息（限24小时内）
更新卡片	POST	`/topapi/message/corpconversation/status_bar/update`	仅针对"OA消息"类型，更新状态栏颜色和文字

如果您希望发出的通知很酷炫（支持按钮、动态刷新），使用互动卡片。

动作	方法	接口路径 (API Path)	说明
发送	POST	`/v1.0/im/interactiveCards/send`	发送高级互动卡片
更新	PUT	`/v1.0/im/interactiveCards/instances`	动态更新卡片内容（如：投票后数字变化）

为了方便您做技术决策，我对比了这三类接口的核心维度：

维度	新版待办 (Todo v1.0)	工作通知 (AsyncSend)	旧版待办 (WorkRecord)
目前状态	🟢 推荐 (主力)	🟢 推荐 (主力)	🔴 废弃 (勿用)
入口位置	待办Tab + 侧边栏	聊天窗口	聊天窗口
用户打扰	强 (红点+强提醒)	中 (消息推送)	中 (消息推送)
完成操作	真·完成 (划掉消失)	无 (仅阅读)	伪·完成 (改颜色)
权限要求	`todo.write`	基础消息权限	`qyapi_work_record` (难申请)
ID 类型	必须 `unionId`	`userid` 列表	`userid`
适用场景	审批、任务指派、需跟进	公告、报警、工资条	考古