dingtalk-attendance

name	dingtalk-attendance
description	当用户提到'考勤'、'打卡'、'迟到'、'早退'、'补卡'、'请假'、'出勤'、'缺勤'、'考勤报表'、'考勤异常'时使用此技能。查询钉钉考勤打卡记录、考勤结果、排班信息，识别异常并生成汇总报告。
version	0.1.0
metadata	{"openclaw":{"emoji":"⏰","requires":{"env":["DINGTALK_APP_KEY","DINGTALK_APP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"DINGTALK_APP_KEY"}}

钉钉考勤操作技能

通过钉钉开放平台考勤 API，查询打卡记录、考勤结果、排班数据，并识别考勤异常。

前置条件

应用需申请权限：查询企业考勤数据权限。先获取 access_token：

ACCESS_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${DINGTALK_APP_KEY}&appsecret=${DINGTALK_APP_SECRET}" | jq -r '.access_token')

核心操作

1. 获取考勤结果（最常用）

查询员工某段日期的考勤汇总结果（正常/迟到/早退/缺卡/请假等）：

curl -s -X POST "https://oapi.dingtalk.com/attendance/listRecord?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["<userId1>", "<userId2>"],
    "checkDateFrom": "2026-03-01T00:00:00+08:00",
    "checkDateTo": "2026-03-04T23:59:59+08:00",
    "isI18n": false
  }' | jq '.recordresult'

返回值关键字段：

• checkType: OnDuty(上班) / OffDuty(下班)
• timeResult: Normal(正常) / Early(早退) / Late(迟到) / SeriousLate(严重迟到) / Absenteeism(旷工) / NotSigned(未打卡)
• userCheckTime: 实际打卡时间（毫秒时间戳）
• planCheckTime: 应打卡时间

2. 获取打卡详情

查询原始打卡流水（包括打卡地点、设备等）：

curl -s -X POST "https://oapi.dingtalk.com/attendance/list?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "workDateFrom": "2026-03-01T00:00:00+08:00",
    "workDateTo": "2026-03-04T23:59:59+08:00",
    "userIdList": ["<userId1>"],
    "offset": 0,
    "limit": 50
  }' | jq '.recordresult'

3. 获取排班信息

查询员工的排班计划（班次、上下班时间）：

curl -s -X POST "https://oapi.dingtalk.com/topapi/attendance/listschedule?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "workDate": "2026-03-04",
    "offset": 0,
    "size": 200
  }' | jq '.result.schedules'

4. 获取考勤组列表

curl -s -X POST "https://oapi.dingtalk.com/topapi/attendance/getsimplegroups?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "offset": 0,
    "size": 10
  }' | jq '.result.groups'

5. 获取部门用户列表（辅助——获取 userId）

curl -s -X POST "https://oapi.dingtalk.com/topapi/user/listsimple?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dept_id": 1,
    "cursor": 0,
    "size": 100
  }' | jq '.result.list'

dept_id=1 为根部门。用 .result.list[].userid 获取 userId 列表。

典型工作流

每日考勤异常检测：

1. 获取根部门下所有 userId
2. 调用 listRecord 查询今日考勤结果
3. 筛选 timeResult 不为 Normal 的记录
4. 按异常类型分组（迟到/早退/未打卡）
5. 生成汇总报告，推送到 HR 群
6. 对未打卡员工发送工作通知提醒补卡

注意事项

• 单次查询 userIds 最多 50 人，超出需分批
• 日期格式必须含时区：2026-03-04T00:00:00+08:00
• 考勤数据有延迟，建议查询前一天及更早的数据以确保完整
• 钉钉考勤 API 调用频率有限制，对大型企业（500+人）需分批查询并控制频率