​

打卡数据同步：硬件打卡记录自动上传至钉钉

​

概述

​

方案背景

• 数据孤岛严重：员工在自有系统提交请假申请并审批通过后，仍需手动在钉钉打卡或补卡，造成重复操作和数据不一致。
• 时长计算复杂：不同日期的排班时长不同（如工作日8小时、周末4小时），人工计算可请假时长容易出错，且无法动态适配排班调整。
• 状态不同步：自有系统审批通过后，钉钉考勤无法自动感知，HR需手动核对两个系统的数据，耗时且易遗漏。

​

核心价值

• 轻量级接入：无需改造业务系统前端，仅需调用3个核心API即可完成集成，开发成本低。
• 排班智能计算：根据考勤系统的排班情况，预计算员工加班、出差及请假的时长信息，避免人工计算错误。
• 状态实时同步：审批通过后自动通知钉钉考勤同步，审批撤销时自动同步撤销，确保数据一致性。
• 灵活的场景适配：支持跨天请假、多日期排班等复杂场景，自动累加各天排班时长，提升用户体验。

​

适用场景

• 自有假勤系统集成：将企业自研的加班、出差、请假审批系统与钉钉考勤模块打通，实现审批结果自动同步。
• 排班时长预计算：根据员工排班情况，智能计算可提交的请假时长上限，避免超期申请或资源浪费。
• 审批结果同步：自有系统审批通过后，自动同步至钉钉考勤，避免HR手动核对两个系统的数据。
• 跨天请假管理：员工请假跨越多个工作日且每日排班时长不同时，自动累加各天排班时长，简化操作流程。

​

典型业务场景

​

场景一：自有假勤审批与钉钉考勤同步

​

痛点分析

​

价值验证

• 自动化流程
• 关键优势
  • 智能时长预计算：根据排班自动计算最大可请假时长，避免超期申请，减少HR审核工作量。
  • 审批自动同步：审批通过后自动通知钉钉考勤，无需二次操作，节省HR 80%的核对时间。
  • 撤销实时生效：审批撤销后自动同步至钉钉，确保数据一致性，避免考勤统计错误。
  • 低成本接入：仅需调用3个核心API，开发周期缩短70%，快速上线。

​

场景二：跨天请假时长智能计算

​

痛点分析

​

价值验证

• 自动化流程
• 关键优势
  • 自动累加排班：调用预计算接口，自动返回跨天请假的最大可提交时长，消除人工计算错误。
  • 精准控制：根据实际排班动态调整可请假时长上限，避免资源浪费或超期申请。
  • 用户体验提升：员工提交请假时无需手动计算，系统自动提示可请假时长，降低操作门槛。
  • 动态适配调整：若排班发生变更，重新调用预计算接口即可获取最新时长，确保数据准确性。

​

实施指南

​

技术架构

• 身份鉴权层：通过 Client ID / Client Secret 获取 access_token，确保接口调用安全性。
• 权限管理层：申请考勤相关接口权限（qyapi_attendance_group_manage 和 qyapi_attendance_group_read）。
• 时长预计算引擎：调用服务端API-预计算时长接口，根据考勤系统排班情况预计算员工加班、出差及请假的时长信息。
• 审批同步层：审批通过后调用通知审批通过接口，实现钉钉考勤同步；审批撤销时调用通知审批撤销接口，实现同步撤销。

​

前置条件

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

​

代码实现

1. 调用服务端API-预计算时长接口，实现根据考勤系统的排班情况，预计算员工加班、出差及请假的时长信息。
2. 在企业自有审批系统提交了假勤申请，审批通过后通过该接口通知钉钉考勤，调用服务端API-通知审批通过接口，实现钉钉考勤同步通过。保存自定义审批单IDapprove_id。
3. 在企业自有审批系统提交了撤销假勤申请，根据自定义审批单IDapprove_id，调用服务端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-预计算时长接口，实现根据考勤系统的排班情况，预计算员工加班、出差及请假的时长信息。

​

说明

• 情况一，选择请假开始时间是10月15日，结束时间是10月15日；调用预计算时长接口，获取的可提交请假时长最大是8小时。
• 情况二，选择请假开始时间是10月15日，结束时间是10月16日，调用预计算时长接口，获取的可提交请假时长最大是12小时。

public CalculateDurationResponseBody durationCalculate(){
  com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
  config.protocol = "https";
  config.regionId = "central";
  try {
    com.aliyun.dingtalkattendance_1_0.Client client = new  com.aliyun.dingtalkattendance_1_0.Client(config);
    CalculateDurationHeaders calculateDurationHeaders = new CalculateDurationHeaders();
    calculateDurationHeaders.xAcsDingtalkAccessToken = "<your access token>";
    CalculateDurationRequest calculateDurationRequest = new CalculateDurationRequest()
      .setUserId("01472825524039877041")
      .setBizType(3L)
      .setFromTime("2022-10-13 09:00")
      .setToTime("2022-10-13 18:00")
      .setDurationUnit("day")
      .setCalculateModel(1L)
      .setLeaveCode("e2dsad-34dfa-2vas23da");
    CalculateDurationResponse calculateDurationResponse = client.calculateDurationWithOptions(calculateDurationRequest, calculateDurationHeaders, new com.aliyun.teautil.models.RuntimeOptions());
    System.out.println(calculateDurationResponse.getBody());
    return calculateDurationResponse.getBody();
  } catch (Exception e) {
    throw new RuntimeException(e);
  }
}

2. 通知审批通过：在企业自有审批系统提交了假勤申请，审批通过后通过该接口通知钉钉考勤，调用服务端API-通知审批通过接口，实现钉钉考勤同步通过。 说明
   • 本步骤不会在钉钉中产生OA审批单。
   • 保存自定义审批单ID approve_id，后续如需撤销审批时需使用该ID。
   public ProcessApproveFinishResponseBody approveFinish(){
     com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
     config.protocol = "https";
     config.regionId = "central";
     try {
       com.aliyun.dingtalkattendance_1_0.Client client = new  com.aliyun.dingtalkattendance_1_0.Client(config);
       ProcessApproveFinishHeaders processApproveFinishHeaders = new ProcessApproveFinishHeaders();
       processApproveFinishHeaders.xAcsDingtalkAccessToken = "<your access token>";
       ProcessApproveFinishRequest.ProcessApproveFinishRequestTopCalculateApproveDurationParam topCalculateApproveDurationParam = new ProcessApproveFinishRequest.ProcessApproveFinishRequestTopCalculateApproveDurationParam()
         .setBizType(2L)
         .setFromTime("2022-10-13 09:00")
         .setToTime("2022-10-13 19:00")
         .setDurationUnit("hour")
         .setCalculateModel(1L);
       com.aliyun.dingtalkattendance_1_0.models.ProcessApproveFinishRequest processApproveFinishRequest = new com.aliyun.dingtalkattendance_1_0.models.ProcessApproveFinishRequest()
         .setUserId("manager123")
         .setTopCalculateApproveDurationParam(topCalculateApproveDurationParam)
         .setTagName("外出")
         .setApproveId("dingTalk")
         .setJumpUrl("https://open.dingtalk.io/");
       ProcessApproveFinishResponse processApproveFinishResponse = client.processApproveFinishWithOptions(processApproveFinishRequest, processApproveFinishHeaders, new com.aliyun.teautil.models.RuntimeOptions());
       System.out.println(processApproveFinishResponse.getBody());
       return processApproveFinishResponse.getBody();
     } catch (Exception e) {
       throw new RuntimeException(e);
     }
   }
   
3. 通知审批撤销：在企业自有审批系统提交了撤销假勤申请，根据自定义审批单ID approve_id，调用服务端API-通知审批撤销接口，实现钉钉考勤同步撤销。
   public void approveCancel() throws ApiException {
       DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/approve/cancel");
   
       OapiAttendanceApproveCancelRequest req = new OapiAttendanceApproveCancelRequest();
       req.setUserid("01472825524039877041");
       req.setApproveId("dingTalk");
   
       OapiAttendanceApproveCancelResponse rsp = client.execute(req, "access_token");
       System.out.println(rsp.getBody());
   }
   

• 应用凭证获取成功（Client ID / Client Secret）。
• 考勤相关权限申请成功（qyapi_attendance_group_manage / qyapi_attendance_group_read）。
• access_token获取成功。
• 预计算时长接口调用成功，返回正确的可请假时长。
• 审批通过后调用通知审批通过接口，钉钉考勤同步成功。
• 审批撤销时调用通知审批撤销接口，钉钉考勤同步撤销成功。

​

常见问题（FAQ）

• Q1：为什么需要先调用预计算时长接口？ A：预计算时长接口会根据员工的排班情况，智能计算可提交的请假时长上限。例如，员工在某天排班4小时，则当天最多只能请假4小时。跳过此步骤可能导致请假时长与实际排班不匹配，影响考勤数据统计准确性。
• Q2：approve_id的作用是什么？ A：approve_id 是自定义审批单的唯一标识，由业务系统生成并保存。当需要撤销审批时，必须通过该ID调用通知审批撤销接口，钉钉才能准确定位并撤销对应的考勤记录。
• Q3：本方案会在钉钉中产生OA审批单吗？ A：不会。本方案仅实现自有系统审批结果与钉钉考勤的数据同步，不会在钉钉OA审批中心创建审批实例。审批流程仍在自有系统中完成，钉钉仅作为考勤数据的接收方。
• Q4：如果员工跨天请假，预计算时长接口如何工作？ A：接口会自动累加请假期间所有工作日的排班时长。例如，小明10月15日排班8小时，10月16日排班4小时，若请假时间为10月15日至10月16日，接口返回的最大可请假时长为12小时（8+4）。
• Q5：权限申请失败怎么办？ A：请确认以下几点：
  • 应用类型是否为”企业内部应用”
  • 账号是否具有企业管理员或子管理员权限
  • 权限标识是否输入正确（qyapi_attendance_group_manage 和 qyapi_attendance_group_read）
  • 如仍失败，联系钉钉技术支持提供应用ID和错误日志