必须通过服务端API调用“上传打卡记录”接口完成批量打卡数据上传，客户端不支持手动导入；需先配置企业内部应用获取access_token，再校验员工userId并构造含必填字段的JSON请求体发送POST请求。
如果您在使用钉钉App进行考勤管理时，需将本地或第三方系统生成的打卡记录上传至钉钉平台，则必须通过服务端API调用方式完成数据写入。钉钉不支持直接在客户端手动导入打卡记录，所有打卡数据的批量上传均依赖已授权的应用调用“上传打卡记录”接口实现。以下是具体操作路径与技术步骤：
一、配置企业内部应用并获取调用凭证
该步骤旨在为数据上传建立合法身份，确保调用方具备对应权限且能被钉钉服务端识别与鉴权。未完成此配置将导致接口调用返回401或403错误。
1、登录钉钉开发者后台，进入「应用开发」→「企业内部开发」，点击「创建应用」。
2、填写应用名称、描述等基本信息，完成创建后进入应用详情页。
3、在「基础信息」→「应用信息」中，复制记录 AppKey 与 AppSecret。
4、在「权限管理」中，搜索并勾选「考勤」类权限，包括但不限于：上传打卡记录、获取部门用户详情、获取考勤组信息，提交审批。
5、调用 getAccessToken 接口，传入 AppKey 和 AppSecret，获取有效期为2小时的 access_token，后续所有考勤API调用均需携带该凭证。
二、准备打卡数据并校验员工身份
上传前必须确保每条打卡记录绑定真实有效的钉钉组织内员工身份标识（userId），否则数据将被拒绝写入。系统不接受手机号、工号或姓名作为打卡主体标识。
1、调用通讯录接口 /v1.0/users/get 或批量接口 /v1.0/users/list，根据部门ID或关键词查询目标员工的 userId。
2、若员工尚未加入当前企业组织架构，需先通过「通讯录管理」手动添加或调用 /v1.0/users/create 接口创建用户。
3、整理待上传打卡记录，每条记录须包含以下必填字段：userId、checkinTime（毫秒级时间戳）、groupId（所属考勤组ID）、sourceType（来源类型，如 1 表示APP打卡，3 表示API上传）。
4、检查 checkinTime 是否在当前日期前后7天范围内，超出范围的数据将被丢弃。
三、调用上传打卡记录接口
该接口为 POST 方法，用于向指定考勤组批量写入打卡行为，单次最多支持100条记录。成功响应后，数据将在1–3分钟内同步至考勤统计报表中。
1、构造请求URL：https://oapi.dingtalk.com/topapi/attendance/record/upload?access_token=YOUR_ACCESS_TOKEN。
2、设置请求头：Content-Type: application/json。
3、构建请求体JSON，结构如下：
{"records":[{"userId":"u123456","checkinTime":1713292800000,"groupId":"g789012","sourceType":3,"type":1,"locationResult":"北京市朝阳区XX大厦A座"},{"userId":"u234567","checkinTime":1713293100000,"groupId":"g789012","sourceType":3,"type":2,"locationResult":"北京市朝阳区XX大厦A座"}]}
4、其中 type 字段表示打卡类型：1为上班打卡，2为下班打卡；locationResult 为可选字段，用于记录打卡时的地理位置描述。
5、发起HTTP POST请求，接收返回结果。若返回 errcode: 0，表示上传成功；若返回非零 errcode，请依据 errmsg 定位问题，常见错误包括 userId 不存在、groupId 无效、时间格式错误等。
四、验证上传结果与异常排查
上传完成后需人工或自动化方式核对数据是否准确落库，避免因字段缺失或格式偏差导致记录不可见。系统不会主动通知上传失败明细，必须依赖返回体逐条比对。
1、登录钉钉管理后台，进入「工作台」→「考勤打卡」→「考勤统计」，选择对应考勤组与日期，查看员工打卡状态是否显示为“API上传”。
2、在「考勤报表」中导出当日明细，筛选 打卡来源为“系统API” 的记录，确认 checkinTime 与原始数据一致。
3、若部分记录未出现，检查返回响应中的 failList 字段，提取失败原因及对应 userId。
4、针对失败项重新构造请求体，修正字段后重试上传；注意单日同一 userId 同一 type 类型仅允许一条有效记录，重复上传将覆盖前值。
