​

补卡自动同步：审批通过实时更新钉钉考勤状态

​

概述

​

方案背景

​

核心价值

• 跨系统自动同步：自有假勤系统审批通过后，自动调用钉钉API同步补卡信息，无需员工二次操作。
• 状态精准映射：根据审批结果（通过/撤销）自动更新钉钉考勤状态为”补卡通过”或恢复原打卡状态。
• 排班智能匹配：同步前自动查询员工对应日期的排班打卡时间点，确保补卡信息准确关联。
• 审批流解耦：补卡同步不产生钉钉补卡审批单，避免重复审批，保持自有系统审批流程独立性。

​

适用场景

• 自有OA系统补卡同步：员工在自有OA系统提交补卡申请并审批通过后，自动同步到钉钉考勤。
• 第三方假勤平台对接：使用第三方假勤管理系统时，审批结果实时同步至钉钉考勤应用。
• 批量补卡处理：HR批量导入历史补卡记录时，自动同步到钉钉考勤系统。
• 补卡撤销同步：员工撤销自有系统补卡申请后，自动恢复钉钉考勤原始打卡状态。

​

典型业务场景

​

场景一：自有OA系统补卡审批通过后同步钉钉

​

痛点分析

​

价值验证

• 自动化流程

• 关键优势
  • 全自动触发：自有OA系统审批通过后自动调用钉钉API同步补卡信息，员工零感知。
  • 精准匹配：同步前自动查询员工对应日期排班打卡时间点，确保补卡信息准确关联。
  • 实时生效：补卡信息同步后立即生效，钉钉考勤状态从”缺卡”变更为”补卡通过”。
  • 审批流解耦：补卡同步不产生钉钉补卡审批单，避免重复审批，保持自有系统审批独立性。

​

场景二：补卡申请撤销后恢复原始打卡状态

​

痛点分析

​

价值验证

• 自动化流程
• 关键优势
  • 状态自动回滚：自有系统撤销补卡申请后，自动调用钉钉API恢复原始打卡状态。
  • 数据一致性保障：确保钉钉考勤状态与自有OA系统审批结果始终保持一致。
  • 审计留痕：每次同步/撤销操作记录操作人、时间戳、审批单ID，满足合规要求。
  • 异常可追溯：同步失败时记录详细错误日志，便于问题排查与修复。

​

实施指南

​

技术架构

• 身份鉴权层：通过 Client ID / Client Secret 获取 access_token，确保接口调用安全性。
• 考勤组管理层：提供考勤组创建、查询、更新、删除等完整API能力，支持固定班制与排班制考勤组。
• 班次管理层：提供班次创建、查询等API能力，作为考勤组的前置依赖资源。
• 错误处理层：完善的错误码体系，便于快速定位和解决问题。

​

前置条件

• 应用准备：完成企业内部应用的创建与配置，参考应用创建与配置。
• 权限要求：拥有钉钉企业管理员或子管理员权限，并申请以下接口权限：
  • qyapi_attendance_group_manage（考勤组管理权限）
  • qyapi_attendance_group_read（考勤组查询权限）
• 开发环境：已安装Java开发环境(JDK1.6及以上)及Maven构建工具。
• SDK准备：下载钉钉服务端SDK，详情参见服务端SDK下载，支持Java/Python/Go等多语言。

​

代码实现

1. 员工在自有考勤系统提交补卡申请时，根据员工选择的补卡日期调用服务端API-查询成员排班信息接口，获取对应日期该员工的排班打卡时间点。
2. 员工使用自有假勤系统发起补卡审批单，审批结果不同，触发的操作不同。
   • 如果审批通过，调用服务端API-通知补卡通过接口，提交的补卡信息会同步到钉钉考勤应用，考勤状态从缺卡修改为补卡通过。

​

说明

• 如果员工撤销了补卡申请，可以调用服务端API-通知审批撤销接口，撤销已同步到钉钉的补卡审申请，考勤状态恢复到修改之前的打卡状态。

​

实施步骤

​

步骤一：获取应用凭证

1. 登录钉钉开发者后台。
2. 选择目标应用，进入应用详情页。
3. 单击基础信息 > 凭证与基础信息。
4. 记录应用的Client ID和Client Secret。

​

说明

​

步骤二：添加接口权限

1. 在应用详情页，单击权限管理。
2. 在权限搜索框中输入以下权限标识并申请：
   • qyapi_attendance_group_manage（考勤组管理权限）— 用于同步补卡信息、撤销补卡。
   • qyapi_attendance_group_read（考勤组查询权限）— 用于查询员工排班信息。

​

步骤三：获取访问凭证（access_token）

public void getAccessToken() throws ApiException {
  DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/gettoken");
  OapiGettokenRequest req = new OapiGettokenRequest();
  req.setAppkey("dingxxxxxxxxxhgn");
  req.setAppsecret("9G_xxxxxxxxxxxxxxx1JDf0Qq3nexxxxxxxxGIO");
  req.setHttpMethod("GET");
  OapiGettokenResponse rsp = client.execute(req);
  System.out.println(rsp.getBody());
}

• 缓存策略：access_token有效期为2小时，建议在内存或Redis中缓存，过期前5分钟主动刷新。
• 并发控制：避免多个线程同时刷新token导致冲突，可使用分布式锁机制。
• 异常重试：网络波动时自动重试，最多3次，间隔递增（1s → 2s → 4s）。

​

步骤四：核心API调用

1. 查询成员排班信息：员工在自有考勤系统提交补卡申请时，根据员工选择的补卡日期调用服务端API-查询成员排班信息接口，获取对应日期该员工的排班打卡时间点。
   public void scheduleInfo() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/schedule/listbyday");
       OapiAttendanceScheduleListbydayRequest req = new OapiAttendanceScheduleListbydayRequest();
       req.setOpUserId("ma******75");
       req.setUserId("014*********041");
       req.setDateTime(166*******00L);
       OapiAttendanceScheduleListbydayResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   
2. 通知补卡通过：员工使用自有假勤系统发起补卡审批单，如果审批通过，调用服务端API-通知补卡通过接口，提交的补卡信息会同步到钉钉考勤应用，考勤状态从缺卡修改为补卡通过。

​

说明

public void approveCheck() throws ApiException {
    DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/check");
    OapiAttendanceApproveCheckRequest req = new OapiAttendanceApproveCheckRequest();
    req.setUserid("ma****75");
    req.setWorkDate("2022-10-10 09:00:00");
    req.setPunchId(1006170802L);
    req.setPunchCheckTime("2022-10-10 09:00:00");
    req.setUserCheckTime("2022-10-10 08:00:00");
    req.setApproveId("dingTalk10001");
    req.setJumpUrl("https://www.dingtalk.io");
    req.setTagName("补卡");
    OapiAttendanceApproveCheckResponse rsp = client.execute(req, "access_token");
    System.out.println(rsp.getBody());
}

​

参数说明：

3. 通知审批撤销：如果员工撤销了补卡申请，可以调用服务端API-通知审批撤销接口，撤销已同步到钉钉的补卡审申请，考勤状态恢复到修改之前的打卡状态。
   public void approveCancel() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/cancel");
       OapiAttendanceApproveCancelRequest req = new OapiAttendanceApproveCancelRequest();
       req.setUserid("ma****75");
       req.setApproveId("dingTalk10001");
       OapiAttendanceApproveCancelResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• ✅ 所有API调用均返回成功状态码（errcode=0）。
• ✅ 补卡同步后调用查询排班接口验证打卡时间点正确。
• ✅ 撤销操作后验证考勤状态已恢复为原始状态。
• ✅ 错误日志记录完整，包含审批单ID、员工userId、操作时间。
• ✅ 自有OA系统与钉钉考勤补卡数据定期比对一致。

​

常见问题（FAQ）

• Q1：补卡同步和钉钉原生补卡审批有什么区别？ A：两者定位完全不同：
  • 钉钉原生补卡审批：员工在钉钉APP中发起补卡申请→主管审批→自动更新考勤状态。适用于无自有OA系统的企业。
  • 本方案补卡同步：员工在自有OA/假勤系统发起补卡→OA审批通过→API同步到钉钉。适用于已有成熟OA审批流的企业，避免员工在两个系统中重复操作。
  核心差异：本方案不产生钉钉补卡审批单，仅将OA审批结果同步到钉钉考勤记录，保持自有系统审批流程的独立性。
• Q2：批量补卡同步时，部分员工失败如何处理？ A：批量补卡同步建议采用”逐条处理+失败重试”策略：
  1. 分批处理：每次批量不超过50人，避免单次请求超时。
  2. 失败隔离：解析返回结果，提取失败员工的userId及错误原因（errcode/errmsg）。
  3. 分类处理：
     • 用户不在考勤组：检查员工是否已加入对应考勤组。
     • 日期超出范围：确认补卡日期是否在允许补卡的时间窗口内。
     • 网络超时：自动重试3次，间隔递增（1s/2s/4s）。
  4. 日志记录：所有失败案例记录审批单ID、员工userId、错误原因、重试次数，便于后续人工介入。
• Q3：如何验证补卡同步后的数据一致性？ A：建议建立三层校验机制：
  1. 实时校验：补卡同步成功后，立即确认该员工当天的考勤状态已从”缺卡”变更为”补卡通过”。
  2. 定时比对：每日凌晨运行全量比对任务，拉取自有OA系统当日补卡审批记录与钉钉考勤补卡记录，按审批单ID+员工userId匹配，发现不一致时生成告警工单。
  3. 异常监控：对连续3次同步失败的员工触发告警，通知HR管理员手动核查（可能原因：员工离职未移除考勤组、排班未配置等）。
• Q4：撤销补卡后，如果员工当天有正常打卡记录会怎样？ A：撤销操作会将钉钉考勤状态恢复为补卡前的原始打卡状态，具体行为如下：
  • 若补卡前为”缺卡”（未打卡）→ 撤销后恢复为”缺卡”。
  • 若补卡前为”正常打卡” → 撤销后恢复为”正常打卡”，补卡记录被清除。
  • 若补卡前为”迟到/早退” → 撤销后恢复为”迟到/早退”，补卡记录被清除。
  重要提示：撤销操作不可逆，一旦执行无法再次恢复补卡状态。建议在自有OA系统中增加”二次确认”环节，避免误撤销。