飞书开放平台 Server API 文档

主题

导入打卡流水 ​

导入员工的打卡流水记录。导入后，会根据员工所在的考勤组班次规则，计算最终的打卡状态与结果。可在打卡管理-打卡记录中查询

Tip: 适用于考勤机数据导入等场景。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/attendance/v1/user_flows/batch_create
HTTP MethodPOST
接口频率限制50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用attendance:task 写入打卡数据

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
employee_typestring是请求体和响应体中的 user_id 和 creator_id 的员工id类型。如果没有后台管理权限，可使用通过手机号或邮箱获取用户 ID
示例值：employee_id
可选值有：
- employee_id: 员工 employee ID，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的用户 ID，或者通过手机号或邮箱获取用户 ID获取的user_id。 - employee_no: 员工工号，即飞书管理后台 > 组织架构 > 成员与部门 > 成员详情中的工号

请求体 ​

名称类型必填描述
flow_recordsuser_flow\[\]是打卡流水记录列表(数量限制50)
  └ user_idstring是用户 ID。与employee_type对应
示例值："abd754f7"
  └ creator_idstring是记录创建者 ID。与employee_type对应
示例值："abd754f7"
  └ location_namestring是打卡位置名称信息
示例值："西溪八方城"
  └ check_timestring是打卡时间，精确到秒的时间戳（只支持导入打卡时间在2022年1月1日之后的数据）
示例值："1611476284"
  └ commentstring是打卡备注
示例值："上班打卡"
  └ record_idstring否打卡记录 ID，导入时此参数无效
示例值："6709359313699356941"
  └ ssidstring否打卡 Wi-Fi 的 SSID
示例值："b0:b8:67:5c:1d:72"
  └ bssidstring否打卡 Wi-Fi 的 MAC 地址
示例值："b0:b8:67:5c:1d:72"
  └ is_fieldboolean否是否为外勤打卡。默认为false，非外勤打卡
示例值：true
  └ is_wifiboolean否是否为 Wi-Fi 打卡。默认为false，非Wi-Fi打卡
示例值：true
  └ typeint否记录的生成方式。举例：type=0表示「开放平台导入」的「用户打卡」流水；type=1表示「开放平台导入」的「管理员修改」流水。若不设置type，则默认是0。
示例值：7
可选值有：
- 0: 用户打卡 - 1: 管理员修改 - 2: 用户补卡 - 3: 系统自动生成 - 4: 下班免打卡 - 5: 考勤机 - 6: 极速打卡 - 7: 考勤开放平台导入
  └ photo_urlsstring\[\]否打卡照片列表（该字段目前不支持）
示例值：["https://time.clockin.biz/manage/download/6840389754748502021"]
  └ device_idstring否打卡设备ID，（只支持小程序打卡，导入时无效）
示例值："99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d"
  └ check_resultstring否打卡结果，作为入参时无效
示例值："Invalid"
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡 - Normal: 正常 - Early: 早退 - Late: 迟到 - SeriousLate: 严重迟到 - Lack: 缺卡 - Invalid: 无效 - None: 无状态 - Todo: 尚未打卡
  └ external_idstring否用户导入的外部打卡记录ID，用于和外部数据对比，如果不传，在查询的时候不方便区分
示例值："record_123"
  └ idempotent_idstring否唯一幂等键，不传的话无法实现幂等处理
示例值："*_"

请求体示例 ​

json
{
    "flow_records": [
        {
            "user_id": "abd754f7",
            "creator_id": "abd754f7",
            "location_name": "西溪八方城",
            "check_time": "1611476284",
            "comment": "上班打卡",
            "record_id": "6709359313699356941",
            "ssid": "b0:b8:67:5c:1d:72",
            "bssid": "b0:b8:67:5c:1d:72",
            "is_field": true,
            "is_wifi": true,
            "type": 7,
            "photo_urls": [
                "https://time.clockin.biz/manage/download/6840389754748502021"
            ],
            "device_id": "99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
            "check_result": "Invalid",
            "external_id": "record_123",
            "idempotent_id": "****_***"
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ flow_recordsuser_flow\[\]打卡流水记录列表
    └ user_idstring用户 ID
    └ creator_idstring记录创建者 ID
    └ location_namestring打卡位置名称信息
    └ check_timestring打卡时间，精确到秒的时间戳
    └ commentstring打卡备注
    └ record_idstring打卡记录 ID
    └ ssidstring打卡 Wi-Fi 的 SSID
    └ bssidstring打卡 Wi-Fi 的 MAC 地址
    └ is_fieldboolean是否为外勤打卡
    └ is_wifiboolean是否为 Wi-Fi 打卡
    └ typeint记录生成方式
可选值有：
- 0: 用户打卡 - 1: 管理员修改 - 2: 用户补卡 - 3: 系统自动生成 - 4: 下班免打卡 - 5: 考勤机 - 6: 极速打卡 - 7: 考勤开放平台导入
    └ photo_urlsstring\[\]打卡照片列表
    └ device_idstring打卡设备ID（只支持小程序打卡，导入时无效）
    └ check_resultstring打卡结果
可选值有：
- NoNeedCheck: 无需打卡 - SystemCheck: 系统打卡 - Normal: 正常 - Early: 早退 - Late: 迟到 - SeriousLate: 严重迟到 - Lack: 缺卡 - Invalid: 无效 - None: 无状态 - Todo: 尚未打卡
    └ external_idstring用户导入的外部打卡记录ID
    └ idempotent_idstring唯一幂等键

响应体示例 ​

json
{
    "code": 0,
    "msg": "success，当流水导入失败时，msg格式为：[失败流水1userid-失败流水1creatorid, 失败流水2userid-失败流水2creatorid ... ]",
    "data": {
        "flow_records": [
            {
                "user_id": "abd754f7",
                "creator_id": "abd754f7",
                "location_name": "西溪八方城",
                "check_time": "1611476284",
                "comment": "上班打卡",
                "record_id": "6709359313699356941",
                "ssid": "b0:b8:67:5c:1d:72",
                "bssid": "b0:b8:67:5c:1d:72",
                "is_field": true,
                "is_wifi": true,
                "type": 7,
                "photo_urls": [
                    "https://time.clockin.biz/manage/download/6840389754748502021"
                ],
                "device_id": "99e0609ee053448596502691a81428654d7ded64c7bd85acd982d26b3636c37d",
                "check_result": "Invalid",
                "external_id": "record_123",
                "idempotent_id": "****_***"
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001220001param is invalid入参校验失败，请根据具体返回的信息检查入参。例如“employee_type invalid”代表人员类型异常。如仍无法解决可联系 技术支持
4001220002tenant_id is empty请检查入参中的 tenant_access_token是否正确
4001220004param is invalid请参考实际返回的错误信息排查问题。例如“user_id is not exist or does not have permission”代表入参传入的用户id不存在或者没有权限。如仍无法解决可联系 技术支持
4001220005没有权限请前往考勤管理后台检查数据权限范围
5001225000param is invalid请参考实际返回的错误信息排查问题。例如“internal server error”代表内部服务异常。如仍无法解决可联系 技术支持
5001226500历史错误码，不再使用-
4001220600通用错误信息通用错误信息包含多条，详细的错误信息以及处理建议可参见 错误信息

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有