DingTalk API 技能

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

前置要求

• - 已设置环境变量 DINGTALKAPPKEY 和 DINGTALKAPPSECRET
• 钉钉应用已创建并拥有相应 API 权限

环境变量配置

bash
export DINGTALKAPPKEY=
export DINGTALKAPPSECRET=

功能列表

1. 搜索用户 (search-user)

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

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

输出：

json
{
success: true,
keyword: 张三,
totalCount: 3,
hasMore: false,
userIds: [123456789, 987654321]
}

2. 搜索部门 (search-department)

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

bash
npx ts-node scripts/search-department.ts <搜索关键词> [--debug]

输出：

json
{
success: true,
keyword: 技术部,
totalCount: 2,
hasMore: false,
departmentIds: [12345, 67890]
}

3. 获取部门详情 (get-department)

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

bash
npx ts-node scripts/get-department.ts [--debug]

输出：

json
{
success: true,
department: {
deptId: 12345,
name: 技术部,
parentId: 1
}
}

4. 获取子部门列表 (list-sub-departments)

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

bash
npx ts-node scripts/list-sub-departments.ts [--debug]

输出：

json
{
success: true,
deptId: 1,
subDepartmentIds: [12345, 67890, 11111]
}

5. 获取部门用户列表 (list-department-users)

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

bash
npx ts-node scripts/list-department-users.ts [--debug]

输出：

json
{
success: true,
deptId: 12345,
users: [
{ userId: user001, name: 张三 },
{ userId: user002, name: 李四 }
]
}

6. 发送单聊消息 (send-user-message)

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

bash
npx ts-node scripts/send-user-message.ts <消息内容> [--debug]

输出：

json
{
success: true,
userId: 123456,
robotCode: robot_code,
processQueryKey: query_key,
flowControlledStaffIdList: [],
invalidStaffIdList: [],
message: 消息内容
}

7. 发送群聊消息 (send-group-message)

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

bash
npx ts-node scripts/send-group-message.ts <消息内容> [--debug]

输出：

json
{
success: true,
openConversationId: cid,
robotCode: robot_code,
processQueryKey: query_key,
message: 消息内容
}

8. 获取群内机器人列表 (get-bot-list)

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

bash
npx ts-node scripts/get-bot-list.ts [--debug]

输出：

json
{
success: true,
openConversationId: cid,
botList: [
{
robotCode: code,
robotName: name,
robotAvatar: url,
openRobotType: 1
}
]
}

9. 查询用户详情 (get-user)

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

bash
npx ts-node scripts/get-user.ts [--debug]

输出：

json
{
success: true,
user: {
userid: user001,
name: 张三,
mobile: 1381234,
email: zhangsan@example.com,
deptidlist: [12345, 67890]
}
}

10. 获取用户父部门列表 (list-user-parent-departments)

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

bash
npx ts-node scripts/list-user-parent-departments.ts [--debug]

输出：

json
{
success: true,
userId: user001,
parentIdList: [12345, 67890, 1]
}

11. 获取部门父部门列表 (list-department-parents)

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

bash
npx ts-node scripts/list-department-parents.ts [--debug]

输出：

json
{
success: true,
deptId: 12345,
parentIdList: [12345, 67890, 1]
}

12. 获取部门用户ID列表 (list-department-user-ids)

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

bash
npx ts-node scripts/list-department-user-ids.ts [--debug]

输出：

json
{
success: true,
deptId: 12345,
userIds: [user001, user002, user003]
}

13. 获取部门用户详情分页版 (list-department-user-details)

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

bash
npx ts-node scripts/list-department-user-details.ts [--cursor ] [--size ] [--debug]

输出：

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

14. 获取员工人数 (get-user-count)

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

bash
npx ts-node scripts/get-user-count.ts [--onlyActive] [--debug]

输出：

json
{
success: true,
onlyActive: false,
count: 150
}

15. 根据手机号查询用户 (get-user-by-mobile)

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

bash
npx ts-node scripts/get-user-by-mobile.ts [--debug]

输出：

json
{
success: true,
mobile: 13800138000,
userId: user001
}

16. 根据 unionid 查询用户 (get-user-by-unionid)

根据 unionid 获取用户 userid。

bash
npx ts-node scripts/get-user-by-unionid.ts [--debug]

输出：

json
{
success: true,
unionid: xxxxx,
userId: user001
}

17. 获取未登录用户列表 (list-inactive-users)

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

bash
npx ts-node scripts/list-inactive-users.ts [--deptIds id1,id2] [--offset ] [--size ] [--debug]

输出：

json
{
success: true,
queryDate: 20240115,
userIds: [user001, user002],
hasMore: false
}

18. 查询离职记录列表 (list-resigned-users)

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

bash
npx ts-node scripts/list-resigned-users.ts <