DingTalk API

DingTalk API 技能

用于调用钉钉开放平台 API 的技能，支持用户搜索/详情/查询、部门管理（搜索/详情/子部门/用户列表/父部门）、机器人消息发送、群内机器人查询、离职记录查询、OA审批管理（查询/发起/审批/转交/评论）等功能。

前置要求 已设置环境变量 DINGTALK_应用_KEY 和 DINGTALK_应用_SECRET 钉钉应用已创建并拥有相应 API 权限 环境变量配置 导出 DINGTALK_应用_KEY="" 导出 DINGTALK_应用_SECRET=""

功能列表

• 搜索用户 (搜索-user)

根据姓名搜索用户，返回匹配的 UserId 列表。

npx ts-node scripts/搜索-user.ts "<搜索关键词>"

输出：

{ "成功": true, "keyword": "张三", "totalCount": 3, "hasMore": false, "userIds": ["123456789", "987654321"] }

• 搜索部门 (搜索-department)

根据名称搜索部门，返回匹配的部门 ID 列表。

npx ts-node scripts/搜索-department.ts "<搜索关键词>" [--调试]

输出：

{ "成功": true, "keyword": "技术部", "totalCount": 2, "hasMore": false, "departmentIds": [12345, 67890] }

• 获取部门详情 (获取-department)

获取指定部门的详细信息。

npx ts-node scripts/获取-department.ts [--调试]

输出：

{ "成功": true, "department": { "deptId": 12345, "name": "技术部", "parentId": 1 } }

• 获取子部门列表 (列出-sub-departments)

获取指定部门下的子部门 ID 列表。根部门 deptId 为 1。

npx ts-node scripts/列出-sub-departments.ts [--调试]

输出：

{ "成功": true, "deptId": 1, "subDepartmentIds": [12345, 67890, 11111] }

• 获取部门用户列表 (列出-department-users)

获取指定部门下的用户列表（userId + 姓名），自动分页获取全部用户。

npx ts-node scripts/列出-department-users.ts [--调试]

输出：

{ "成功": true, "deptId": 12345, "users": [ { "userId": "user001", "name": "张三" }, { "userId": "user002", "name": "李四" } ] }

• 发送单聊消息 (发送-user-message)

通过机器人向指定用户发送单聊消息。

npx ts-node scripts/发送-user-message.ts "" "" "<消息内容>" [--调试]

输出：

{ "成功": true, "userId": "123456", "ro机器人Code": "ro机器人_code", "process查询Key": "查询_key", "flowControlledStaffId列出": [], "invalidStaffId列出": [], "message": "消息内容" }

• 发送群聊消息 (发送-group-message)

通过机器人向指定群会话发送消息。

npx ts-node scripts/发送-group-message.ts "" "" "<消息内容>" [--调试]

输出：

{ "成功": true, "openConversationId": "cid", "ro机器人Code": "ro机器人_code", "process查询Key": "查询_key", "message": "消息内容" }

• 获取群内机器人列表 (获取-机器人-列出)

查询群内已配置的机器人列表。

npx ts-node scripts/获取-机器人-列出.ts "" [--调试]

输出：

{ "成功": true, "openConversationId": "cid", "机器人列出": [ { "ro机器人Code": "code", "ro机器人Name": "name", "ro机器人Avatar": "url", "openRo机器人Type": 1 } ] }

• 查询用户详情 (获取-user)

获取指定用户的详细信息，包括姓名、手机号、邮箱、部门列表等。

npx ts-node scripts/获取-user.ts "" [--调试]

输出：

{ "成功": true, "user": { "userid": "user001", "name": "张三", "移动": "138****1234", "emAIl": "zhangsan@example.com", "dept_id_列出": [12345, 67890] } }

• 获取用户父部门列表 (列出-user-parent-departments)

获取指定用户所属的所有父部门列表，从直接部门到根部门。

npx ts-node scripts/列出-user-parent-departments.ts "" [--调试]

输出：

{ "成功": true, "userId": "user001", "parentId列出": [12345, 67890, 1] }

• 获取部门父部门列表 (列出-department-parents)

获取指定部门的所有父部门列表，第一个是自身，最后一个是根部门。

npx ts-node scripts/列出-department-parents.ts [--调试]

输出：

{ "成功": true, "deptId": 12345, "parentId列出": [12345, 67890, 1] }

• 获取部门用户ID列表 (列出-department-user-ids)

获取指定部门下所有用户的 userid 列表。

npx ts-node scripts/列出-department-user-ids.ts [--调试]

输出：

{ "成功": true, "deptId": 12345, "userIds": ["user001", "user002", "user003"] }

• 获取部门用户详情分页版 (列出-department-user-detAIls)

分页获取部门用户详细信息，支持自定义 cursor 和 size。

npx ts-node scripts/列出-department-user-detAIls.ts [--cursor ] [--size ] [--调试]

输出：

{ "成功": true, "deptId": 12345, "users": [ { "userid": "user001", "name": "张三" }, { "userid": "user002", "name": "李四" } ], "hasMore": true, "nextCursor": 100 }

• 获取员工人数 (获取-user-count)

获取企业员工总数，可选择是否仅统计已激活员工。

npx ts-node scripts/获取-user-count.ts [--onlyActive] [--调试]

输出：

{ "成功": true, "onlyActive": false, "count": 150 }

• 根据手机号查询用户 (获取-user-by-移动)

根据手机号查询用户 userid。仅企业内部应用可用，只能查询在职员工。

npx ts-node scripts/获取-user-by-移动.ts "<移动>" [--调试]

输出：

{ "成功": true, "移动": "13800138000", "userId": "user001" }

• 根据 unionid 查询用户 (获取-user-by-unionid)

根据 unionid 获取用户 userid。

npx ts-node scripts/获取-user-by-unionid.ts "" [--调试]

输出：

{ "成功": true, "unionid": "xxxxx", "userId": "user001" }

• 获取未登录用户列表 (列出-inactive-users)

获取指定日期未登录钉钉的员工列表。只能查询一个月内数据，每天9点后调用才能确保获取前一天数据。

npx ts-node scripts/列出-inactive-users.ts "<查询Date>" [--deptIds "id1,id2"] [--off设置 ] [--size ] [--调试]

输出：

{ "成功": true, "查询Date": "20240115", "userIds": ["user001", "user002"], "hasMore": false }

• 查询离职记录列表 (列出-re签名ed-users)

查询指定时间范围内的离职员工记录。仅企业内部应用可用。

npx ts-node scripts/列出-re签名ed-users.ts "<启动Time>" [""] [--next令牌 <令牌>] [--max结果s ] [--调试]

输出：

{ "成功": true, "启动Time": "2024-01-01T00:00:00+08:00