云考勤接入协议

文档目标

本文档用于描述得力云平台考勤机设备与云端考勤应用接入的标准方式、数据交换协议以及具体的接口定义。

适用范围

本文档用于说明得力云平台对外提供的云考勤机设备和云端考勤应用服务接入方式,帮助和指导智能云考勤相关开发人员正确接入云平台。

云考勤接口设计

  • 接入流程

云考勤接入主要有两种途径:

1.  一是通过扫描设备,然后绑定云端考勤应用服务;
2.  二是直接在App应用市场搜索并添加应用服务,然后扫描添加设备。

云考勤机在添加到应用服务时,需要进行初始化,将考勤人员以及人员的指纹、人脸、密码等特征信息录入到设备当中。如果之前已有相同配置型号的考勤机,那么新的考勤机中如果有部分人员之前已录入个人特征信息,应自动完成同步,不需要重复录入。

  • 云考勤机功能

云考勤机对比传统考勤机而言,业务功能更为简单,不需要在设备端实现复杂的人员管理、考勤规则设置,所有考勤管理相关操作都在应用端服务完成,考勤机仅需要实现以下功能即可:

1.  考勤机固件升级;
2.  考勤人员同步;
3.  指纹/人脸等人员特征信息录入上传;
4.  考勤机打卡记录上传;

注意,设备和应用之前的消息转发需要通过平台进行中转。其中设备发给应用的消息,使用指令300,然后经过平台中转为指令405到达应用服务。同样,应用服务发给设备的消息,使用指令500,然后由平台中转为指令301到达设备。

下面就具体的功能接口进行说明。

  • 考勤机升级

请参考通用设备接入指令103以及指令202。设备升级分为两个场景:

1. 主动升级: 设备定时通过102指令查询平台最新固件版本,如果版本不一致,则通过103指令查询最新版本信息,并按照本地升级策略进行升级操作;
2. 被动升级: 设备在线接收平台广播202指令升级信息,如果版本不一致,则通过103指令查询最新版本信息,并按照本地升级策略进行升级操作;
  • 考勤人员同步

考勤人员同步是指考勤机与考勤应用之间同步考勤人员数据的过程,通过考勤人员同步指令应实现考勤机设备和云考勤应用人员的最终一致性。

人员同步是所有考勤操作的基础,为了保证考勤机和应用之间的数据一致性,设备和应用应支持增量同步全量同步两种方式。其中,增量同步是指考勤应用根据考勤机之前的数据同步状态,仅推送增量变更的同步数据;全量同步则是设备从0开始完整的同步应用中当前所有考勤人员列表信息。

当应用端考勤人员列表发生变化时(包括人员添加、删除,特征信息添加、删除等等),考勤应用应通过指令500主动推送变动信息到设备,推送信息请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, //设备实际收到指令301
    "data": {
        "cmd": "user_sync", 
        "payload": {
            "reset": false,
            "total_count": 1000,
            "users":[
                {
                    "user_id": "用户ID", 
                    "name": "张三", 
                    "empno": "工号或空", 
                    "dept": "部门或空", 
                    "fp": [指纹列表,], //仅指纹考勤机传输
                    "fa": [人脸列表,], //仅人脸考勤机传输
                    "admin": true
                }, 
                {
                    "user_id": "420352921887575761", 
                    "delete": true
                }
            ]
        }
    }
}

其中cmd固定为user_sync表示人员同步推送,请求payload各参数说明如下:

参数 类型 描述
reset Boolean 设备重置本地数据标志。仅全量同步第一次推送时设置为true,其它情况设置为false。设备如果收到该标志为true,则应清除本地所有人员数据,然后进行同步更新
total_count 整型 本次人员同步操作的总条目数,包括所有新增、更新和删除条目数。仅在一次同步任务开始时设置,后续消息不设置该字段信息。
users 数组 本次增量更新的用户列表,包括:
user_id:用户ID,
name:用户姓名,
empno:可选,组织工号或空,
dept:可选,部门或空,
fp:可选,指纹特征数据数组,如果不支持或者不存在,则置为空,可能会返回多个,
fa:可选,人脸特征数据数组,如果不支持或者不存在,则置为空,可能会返回多个,
admin:可选,如果是管理员,则为true,否则为空,
delete:可选,删除标记,如果不是删除操作,则置为空,否则置为true且除user_id外其它信息均不返回

应用一次推送给设备的变更信息个数默认为1,除非在设备绑定时显示指定了推送数据size,参见设备绑定中的user_sync_size字段属性。

考勤机设备收到变更信息后,应在处理完成后通过指令300实时返回确认响应给应用端,响应消息示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "考勤应用ID", 
    "time": 1502867086, 
    "action": 300,//应用实际收到指令405
    "data": {
        "cmd": "user_sync",
        "payload": {
            "code": 0,
            "sync_size": 1
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 操作结果码。
0表示操作成功,可以继续同步;
1表示容量已满,无法添加,同步任务应终止并给出提示;
2表示设备繁忙,同步任务应自动暂停并给出提示,固定等待一段时间后再次启动(建议暂停5分钟)。
sync_size 整型 本次同步成功的条数,仅在code为0时有效。如果应用推送的数据size大于设备可写入的容量,同步成功的数量可能小于推送数。为了保证数据一致性,设备本地数据更新的顺序与推送数据顺序应保持一致。

user_sync响应消息不需要保证一定送达,如果设备遭遇网络异常或掉电等其它情况导致发送失败,设备不需要重传。

应用仅在确认收到设备同步成功的响应后,才能视为同步成功,否则应定时在后台重复进行数据推送操作直到操作完成为止。需要特别注意的是,如果应用收到设备容量已满的响应,应自动终止并清除后续同步插入操作。另外,如果已检测到设备离线,应用应自动暂停数据同步操作直到设备恢复在线为止。

另外,为了减少同步数据的交互次数,对于某些可以合并的同步操作建议先完成合并再进行同步推送(例如某人员添加之后又被删除等)。

为了确保设备与应用同步数据的一致性,设备端每次重新上线或某个指定定时非工作时间(例如凌晨12点)应与应用端进行数据校验,验证方式可以考虑使用简单的数据hash比对来完成。

设备端通过计算本地考勤人员列表的数据hash值,并上传应用进行验证。请求示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "考勤应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "user_sync_check",
        "payload": {
            "size": 100,
            "hash": "11207717158912",
            "reason": 0,
        }
    }
}

其中cmd固定为user_sync_check表示同步人员校验,请求payload各参数说明如下:

参数 类型 描述
size 整型 本地考勤人员数量
hash 字符串 设备将本地所有考勤人员的userid通过异或计算得出hash值,公式示例如下: hash = userid1 XOR userid2 XOR userid3.....XOR useridN
reason 整型 发起原因。0为常规检查,1为本地数据异常检查。当值为1时,如果应用判断设备数据不一致时,应清除同步队列,重新发布全量同步

设备应将QOS服务级别设置为1确保消息数据上传到应用。如果设备遭遇网络异常或掉电等其它情况导致发送失败,设备不需要重传。

应用收到请求后,比对服务器该设备的考勤人员数量以及对应hash值,如果发现与设备请求数据不一致,则认为设备数据同步出错。此时,应用应重建推送队列启动全量推送,将第一条推送的reset标记设置为true。

注意,应用在校验hash时应保证所有推送给设备的增量更新消息均已处理完成。如果在应用收到user_sync_check时,应用端仍有部分推送数据未成功推送至设备,应用应忽略该校验请求。

  • 考勤机人员特征录入

考勤设备绑定后,应用端需要引导管理人员进行考勤人员指纹或人脸等特征数据的录入。具体考虑设备支持哪些特征数据,平台会在设备绑定时通过webhook告知应用,对应指令402

应用端通过设备信息推送指令500向考勤机发起请求,请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_input", 
        "payload": {
            "user_id": "用户ID",
            "feature_type": "fa|fp"
        }
    }
}

其中cmd固定为feature_input表示用户特征数据录入,payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前录入指纹或人脸的用户ID
feature_type 字符串 需要录入的用户特征数据类型(人脸为fa,指纹为fp)

设备收到请求后,启动指纹或人脸等特征录入流程,并上传特征录入状态数据,请求示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "发起应用服务ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "feature_input", 
        "payload": {
            "user_id": "用户ID", 
            "input_status": 0|1|2,
            "feature_type": "fa|fp",
            "feature_value": "特征值"
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前特征录入的用户ID
input_status 整型 特征录入状态:0录入超时(60秒)、1录入完成、2设备繁忙、3录入准备就绪、4设备容量已满、5当前用户特征已录满、6当前用户不存在、7录入已取消
feature_type 字符串 录入完成时必传:当前录入的特征类型
feature_value 字符串 录入完成时必传:当前录入的特征数据

设备应在不同的情况下,给应用返回不同的状态数据:

1. 如果设备能够正常进入录入状态,应立刻返回设备"录入就绪状态(3)",随后特征数据录入完成后,应再次返回"录入完成(1)"并附带已录入的特征数据。
2. 如果设备进入录入状态后,长时间没有任何特征数据录入操作,则应返回"录入超时(0)";
3. 如果设备在收到请求时无法响应,例如正在处理其它用户的特征录入请求,则应立刻返回"设备繁忙(2)";
4. 如果设备本地容量已满,无法存储更多特征数据,则应立刻返回"设备容量满(4)";
5. 如果当前请求用户的特征最大录入数已满,则应立刻返回"当前用户特征已录满(5)";
6. 如果当前请求用户在本地人员列表中不存在,则应立刻返回"当前用户不存在(6)";
7. 如果设备在录入过程中,用户主动在设备端取消了录入,则应立刻返回"录入已取消(7)";

如果设备特征录入已成功,为了保证体验,设备在上传特征数据到应用时,不论消息是否发送成功,都应实时将特征数据保存到设备本地。

和人员同步指令一样,设备应将QOS服务级别设置为1确保消息数据上传到应用。除了特征数据上传外,其它状态数据响应在网络中断或掉电等异常情况下,设备不需要进行重传。

另外,应用端在收到用户指纹或人脸等特征编码信息后,如果其它考勤设备相同的考勤人员使用了同样的特征算法版本,应用应自动将该特征编码信息推送到对应设备端。

  • 考勤机人员特征录入取消

应用端通知设备开始特征信息录入之后,应用端可以主动调用该接口取消设备端的特征信息录入(例如用户在录入状态下主动在应用端关闭录入窗口)。

应用端通过设备信息推送指令500向考勤机发起请求,请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_input_cancel", 
        "payload": {
            "user_id": "用户ID",
            "feature_type": "fa|fp"
        }
    }
}

其中cmd固定为feature_input_cancel表示用户特征数据录入取消,payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前录入指纹或人脸的用户ID
feature_type 字符串 需要录入的用户特征数据类型(人脸为fa,指纹为fp)

设备收到该请求后,如果user_idfeature_type均与本地录入状态一致且当前设备正处于录入过程中,则自动取消录入,否则忽略该请求。

设备不需要向应用对该请求返回响应消息。

  • 考勤机人员特征更新

考勤机在多次打卡过程中可能会更新用户特征模版,已达到更高的用户识别度。当考勤机人员指纹或人脸特征更新之后,可通过以下请求发送请求到应用端进行更新:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "发起应用服务ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "feature_update", 
        "payload": {
            "user_id": "用户ID", 
            "feature_type": "fa|fp",
            "feature_value": "特征值",
            "feature_index": "更新索引"
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前特征录入的用户ID
feature_type 字符串 当前更新的特征类型
feature_value 字符串 当前更新的特征数据
feature_index 整型 更新的用户指纹序列,从0开始

设备应将QOS服务级别设置为1确保消息数据上传到应用,如果网络异常导致消息无法上传,应在网络恢复后进行重传。

应用端在收到用户指纹或人脸特征编码更新信息后, 处理方式应与录入新特征数据成功一致。

  • 应用端人员特征录入

除了设备端采集人员特征,也可以由应用端采集特征图像,然后发送给考勤机设备完成特征解析。

应用端拍照采集到用户特征图像后,通过设备信息推送指令500向考勤机发起解析录入请求,请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "app_feature_input", 
        "payload": {
            "user_id": "用户ID",
            "feature_type": "fa|fp",
            "image_url":"https://xxx.xxx",
            "checksum": "e33691d17e591e854e3f7996b699fb94"
        }
    }
}

其中cmd固定为app_feature_input表示用户通过APP应用进行特征数据录入,payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前录入指纹或人脸的用户ID
feature_type 字符串 需要录入的用户特征数据类型(人脸为fa,指纹为fp)
image_url 字符串 通过应用端采集的用户特征图像下载地址
checksum 字符串 特征图像的MD5校验值,用于下载之后验证数据完整性

设备收到请求后会下载特征图像,并进行本地解析,如果解析成功验证无误,则上传特征录入状态数据,请求示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "发起应用服务ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "app_feature_input", 
        "payload": {
            "user_id": "用户ID", 
            "input_status": 0|1|2,
            "feature_type": "fa|fp",
            "feature_value": "特征值"
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前特征录入的用户ID
input_status 整型 特征录入状态:0文件下载失败(或超时)、1特征录入完成、2设备繁忙、3特征文件解析失败、4设备容量已满、5当前用户特征已录满、6当前用户不存在、7特征已重复
feature_type 字符串 录入完成时上传:当前录入的特征类型
feature_value 字符串 录入完成时上传:当前录入的特征数据

设备应在不同的情况下,给应用返回不同的状态数据:

1. 如果设备下载特征图像失败、超时或者完整性校验失败,应立刻返回设备"文件下载失败(0)";
2. 如果设备在收到请求时无法响应,则应立刻返回"设备繁忙(2)";
3. 如果设备下载文件成功但无法正确解析该文件,则应立刻返回"特征文件解析失败(3)";
4. 如果设备本地容量已满,无法存储更多特征数据,则应立刻返回"设备容量已满(4)";
5. 如果当前请求用户的特征最大录入数已满,则应立刻返回"当前用户特征已录满(5)";
6. 如果当前请求用户在本地人员列表中不存在,则应立刻返回"当前用户不存在(6)";
7. 如果设备解析用户特征图像后得到的特征与设备中其他特征重复,则应立刻返回"特征已重复(7)";
8. 如果设备成功下载并解析到用户特征,且无任何异常,则应立刻返回"特征录入完成(1)"并附带已录入的特征数据;

其他逻辑与设备录入特征保持一致。

  • 考勤机打卡

员工通过设备进行密码、指纹或人脸考勤打卡时,设备需将打卡数据实时发送至应用端,为了降低上传频率,设备可定时批量提交考勤记录(例如5s一次)。

设备打卡数据上传可使用应用消息推送指令300来完成,上传请求示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用服务ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "checkin", 
        "payload": {
            "users": [
                {
                    "user_id": "用户ID1", 
                    "check_type": "fp", 
                    "check_time": 1503025335
                }, 
                {
                    "user_id": "用户ID2", 
                    "check_type": "fa", 
                    "check_time": 1503028318
                }
            ]
        }
    }
}

其中cmd固定为checkin表示考勤打卡,请求payload各参数说明如下:

参数 类型 描述
users 数组 表示一批员工打卡记录。其中各属性说明如下:
user_id:用户ID,
check_type:考勤方式,
check_time:考勤时间(精确到秒)

应用端在收到打卡数据后, 应向考勤机回复确认消息,并将考勤数据上传到云平台,见云端数据上传

考勤确认消息mid与请求一致,响应示例如下:

{
    "mid": "123456", 
    "from": "应用服务ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, //转换为301到设备 
    "data": {
        "cmd": "checkin"
    }
}

考勤机在收到确认响应之后,方可标记考勤记录为上传成功。否则,需要按照一定的重试机制再次上传直到成功为止。

  • 考勤机打卡主动上报

如果因为某些网络或服务器故障,平台还可以通过指令200向设备主动发起请求,要求设备重新上传考勤打卡记录,请求如下:

{
    "mid": "123456", 
    "from": "system", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 200, 
    "data": {
        "cmd": "checkin_upload",
        "payload": {
            "days": 2
        }
    }
}

days表示上传最近多少天的考勤打卡记录,包括当天。例如如果当天是2018/8/27日,days设置为2,则上传2018/8/26-2018/8/27两天的考勤打卡记录。设备收到消息后,无需校验,直接开始上传即可;

  • 云考勤应用功能

考勤应用的功能参照主流云考勤系统,应至少具备以下功能:

1. 考勤机管理,包括考勤机参数设置等;
2. 考勤排班管理;
3. 考勤规则设置;
4. 考勤相关申请审批,例如补卡、加班、请假、出差等
5. 考勤数据查询,报表统计分析
6. 其他特殊功能,例如极速打卡

以上功能应在APP手机端和Web分别针对终端用户和管理员进行实现,具体实现细节,这里不阐述。

为了便于考勤应用实现上述功能,平台应提供以下接口实现:

  • 应用安装通知

在组织管理员通过设备扫描或者主动安装应用时,平台会主动通过WebHook回调通知应用用户安装事件,回调应用指令为400。 考勤应用收到安装事件后,应启动初始化,通过数据同步指令507开始同步组织数据。如果之前已有组织信息,可通过update_time参数进行增量同步。

同样,当用户卸载删除了应用时,平台也会主动通知应用进行相应的数据清理操作,具体指令为401

  • 设备绑定通知

当应用绑定或者解绑某台考勤机设备时,平台会通过指令402403回调通知应用服务设备相关信息,应用服务可进行相应的处理操作。

用户在绑定考勤机设备时,平台会通过402指令向应用推送设备的产品信息,推送信息除了产品名称、图标、型号等基本信息之外,还包括产品的特征features和可配置参数信息properties

其中,产品特征信息是指该考勤机设备支持的基本特征参数指标信息,包括:

产品特征参数 描述
check_type 考勤方式,包括密码(pass)、指纹(fp)、人脸(fa)三种。如果设备支持多种,以逗号分隔。例如同时支持人脸和考勤的设备,应设置为fp,fa
fp_max 每个用户最多录入指纹数,缺省为3。
fa_max 每个用户最多录入人脸数,缺省为1。
fp_capacity 指纹容量上限。
fa_capacity 人脸容量上限。
user_capacity 用户容量上限。
fp_alg 标示该设备指纹算法版本,用于区分不同的特征识别算法。不同设备如果使用相同算法版本,则用户特征数据可共享
fa_alg 标示该设备人脸算法版本,用于区分不同的特征识别算法。不同设备如果使用相同算法版本,则用户特征数据可共享
user_sync_size 设备支持一次主动人员同步最大的更新记录数量,缺省为1
admin_limit 考勤机最多支持考勤管理员数量,默认为10
ring_config 是否支持APP响铃设置,默认是不支持false
ring_group_size 支持APP响铃设置时启用,表示最多支持响铃的设置组数,默认为24。
checkin_interval_config 是否支持APP打卡有效时间间隔设置,默认是不支持false。
checkin_interval_max 打卡有效间隔时间的上限值,默认为120,单位为分钟。

例如一台支持2000用户、1000指纹且每人最多录入3个指纹的指纹考勤机,则返回features如下:


{
    ....
    "features":[
        {
            "type": "check_type",
            "value":"fp"
        },
        {
            "type": "user_capacity",
            "value":"2000"
        },
        {
            "type": "fp_max",
            "value":"3"
        },
    ]
}

对于某些需要通过APP远程设置参数的机型例如无可操作显示屏幕的高端机型D2/D3等,平台还会对其进行可配置参数的配置, 考勤机支持的可配置参数列表如下:

可配置参数 描述
check_type 考勤方式设置。例如对于某些D3可以设置的选项值包括:0-人脸考勤、1-指纹考勤、2-人脸+指纹考勤
volume 音量设置,选项值包括:0-关、1-低、2-中、3-高

如果设备在绑定时存在可配置的参数,那么在应用的设备管理界面应有对应的配置项,配置完成后,应用端通过设备信息推送指令500向考勤机发起请求更新配置参数,请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "property_update", 
        "payload": {
            "properties": [ //一次更新多个参数
                {
                    "property": "check_type",
                    "value": "fa"
                },
                ......
            ]
        }
    }
}

其中cmd固定为property_update表示设备可配置参数值更新,payload各参数说明如下:

可配置参数 描述
property 可配置参数名称
value 参数值

设备如果配置成功,应使用应用消息推送指令300将更新结果返回给应用端,响应示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "考勤应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "property_update", 
        "payload": {
            "code": 0,  //0表示成功
            "msg" : "错误描述"
        }
    }
}

注意,设备产品信息是静态数据,平台仅在应用绑定设备时推送一次,应用应及时存储到本地数据库,用于后续业务逻辑处理。

  • 设备状态更新

平台会通过应用端回调指令404同步设备状态到应用端,包括设备的在线、离线等。应用端根据业务实际需求来更改内部设备状态。

  • 响铃设置

针对某些无法进行本地设备操作的设备,例如D2/D3,需要支持通过APP端远程进行设备响铃功能设置。设备支持多组响铃设置,每组都有对应的响铃时间、时长以及响铃周期(按周天)选择;

应用是否支持通过远程配置响铃以及可以设置的响铃组数,通过设备产品参数ring_configring_group_size来判断,参见设备绑定通知

应用通过设备信息推送指令500向考勤机发起请求更新响铃设置,示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "ring_config_update", 
        "payload": {
            "rings" : [ //可以一次更新多组响铃设置
                {
                    "index": 0,
                    "time": "08:00",
                    "duration": 30,
                    "days": "0,1,2,3,4,5,6"
                },
                ......
            ]
        }
    }
}

其中cmd固定为ring_config_update表示更新设备响铃功能设置,payload各参数说明如下:

可配置参数 描述
index 响铃分组ID。默认从0开始,不得超过最大上限ring_group_size-1。
time 响铃时间点,默认格式是HH:mm,精确到分
duration 响铃时长,单位是秒。可设置几个固定的时长
days 响铃周期,以周天为单位。可选择一周内的任意N天,以逗号分隔,星期天到星期六从0开始6结尾。

设备如果配置成功,应使用应用消息推送指令300将更新结果返回给应用端,响应示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "考勤应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "ring_config_update", 
        "payload": {
            "code": 0,  //0表示成功
            "msg" : "错误描述"
        }
    }
}
  • 打卡有效间隔时间设置

针对某些无法进行本地设备操作的设备,例如D2/D3,需要支持通过APP端远程进行打卡有效间隔时间设置(应用通过判断产品特征参数checkin_interval_config来决定是否需要开启该功能)。间隔时间的范围是0-checkin_interval_max分钟,以分钟为单位,用户可以选择输入范围内任意时间间隔。

与通用可配置参数设置一样,应用可通过命令property_update进行该参数的设置,参数名checkin_interval,请求示例如下:

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "property_update", 
        "payload": {
            "properties": [
                {
                    "property": "checkin_interval",
                    "value": "1" //1分钟
                },
            ]
        }
    }
}
  • 查询考勤数据

针对已有企业ERP系统的组织用户或开发者,需要通过平台接口向应用查询组织内的考勤打卡数据。平台通过应用数据请求409向应用转发查询请求。

应用应支持按某个时间段分页返回组织内的原始考勤数据,请求示例如下:

{
    "mid": "123456", 
    "from": "system", 
    "to": "考勤应用ID", 
    "time": 1502867086, 
    "action": 409, 
    "data": {
        "org_id": "组织ID",
        "cmd": "checkin_query", 
        "payload": {
            "next_id": 0,
            "page_size": 50,
        }
    }
}

其中cmd固定为checkin_query表示查询考勤数据,payload各参数说明如下:

可配置参数 描述
next_id 本次查询的开始记录ID,从0开始,下次请求取上次返回记录的最大ID;
page_size 可选,本次查询的最大记录数,默认50;

应用应根据按照时间正序同步返回请求的打卡数据,响应结果示例如下:

{
    "next_id": 1000,
    "data": [
        {
            "id": 123,
            "user_id": "用户ID", 
            "ext_id": "12345"
            "check_type": "fp", 
            "check_time": 1503025335,
            "check_data": "打卡数据"
        }
    ]
}

响应结果各参数说明如下:

参数 类型 描述
next_id 整型 下次查询的记录id
data 数组 打卡记录,以数组形式返回。各属性说明如下:
user_id:用户ID,
ext_id:可选,用户外部系统ID,如果不存在则不返回;
check_type:打卡方式,包括fp、fa、pass、card、wifi、gps、外勤、补签等;
check_time:打卡时间(精确到秒);
check_data:打卡数据,不同的打卡方式数据不同。例如考勤机打卡应保存考勤机设备ID,gps打卡应保存gps坐标位置等

如果接口调用失败,应用应返回HTTP错误码400,并将具体的错误消息存储在HTTP响应消息体内返回。

  • JSAPI接口

应用端以网页方式嵌入APP时,需要通过原生APP访问相关数据,因此,需要提供基于JS的一套API库方便应用调用,具体接口定义见《第三方云应用JS-SDK API说明》文档

  • APP消息推送

应用服务可通过平台向终端用户APP推送消息和代办事项。目前考勤里面应该两种都会存在,例如打卡提醒是消息,补卡申请是代办。

具体接口实现可参考应用接入协议指令501502503

  • 极速打卡

为了更方便的实现员工快速打卡,平台应支持在特定排班时间段,考勤云应用未启动的状况下完成打卡,包括:

1. 极速wifi打卡,当用户处于某个wifi热点范围内时,自动完成打卡;
2. 极速GPS定位打卡,当用户处于某个GPS位置附近时,自动完成打卡;
3. 极速蓝牙打卡,当用户处于某个支持蓝牙考勤的考勤机附近时,自动完成打卡;

当用户选择极速打卡时,考勤应用应通过指令505向平台注册用户相应的事件监听,平台随后会将相应的事件信息通过Webhook同步到考勤应用服务,由考勤服务决定是否极速打卡成功。 如果极速打卡成功,考勤应用应通过平台指令501通知应用考勤成功。具体操作流程如下:

  • 云端数据上传

考勤场景下,以下几类数据应用需要通过指令600上传到云平台,包括:

1. 人员特征信息数据变更记录,包括录入和删除
2. 人员考勤签到数据,包括设备签到和app签到
  • 人员指纹特征信息上传请求示例如下:
{
    "mid": "123456", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 600, 
    "data": {
        "user_id": "用户ID", 
        "client_type": "device", 
        "client_id": "考勤机ID", 
        "event_type": "user_feature_input", //如果是删除,更改为"user_feature_remove"
        "event_data": {
            "feature_type": "fp|fa", 
            "feature_value": "特征值"
        }
    }
}

其中各参数说明如下:

参数 类型 描述
user_id 字符串 用户ID
client_type 字符串 固定为device,表示来自设备的数据
client_id 字符串 用户正在使用的考勤机设备ID
event_type 字符串 事件类型:user_feature_input标识事件类型为用户特征信息录入
event_data 数组 事件所产生的数据。
feature_type:fp是指纹、fa是人脸,
feature_value:对应特征值
  • 人员签到数据上传请求示例如下:
{
    "mid": "123456", 
    "from": "发起应用服务ID", 
    "to": "system", 
    "time": 1502867086, 
    "action": 600, 
    "data": {
        "user_id": "用户ID", 
        "client_type": "device", 
        "client_id": "设备ID", 
        "event_type": "user_checkin", 
        "event_data": {
            "check_type": "fp", 
            "check_time": 1234567890
        }
    }
}

其中各参数说明如下:

参数 类型 描述
user_id 字符串 用户ID
client_type 字符串 用户数据产生设备类型:device表示考勤机设备。如果是手机打卡,则应为ios或者android
client_id 字符串 用户正在使用的设备ID或手机UDID
event_type 字符串 固定为user_checkin,表示当前事件类型为用户考勤打卡
event_data 字符串 考勤数据:
check_type: 表示考勤方式
check_time: 表示考勤时间

更新日志

  • 1.0 (2017-10-24)

    1. 发布1.0线上版本
  • 1.1 (2017-11-06)

    1. 完善文档,更改部分接口的定义
    2. 云端数据上传内容完善
  • 1.2 (2018-03-05)

    1. 更改考勤机人员同步实现协议,取消设备主动同步操作,改有应用端主动推送数据;
    2. 增加考勤人员一致性校验指令user_sync_check,一旦不一致,清除设备数据重新更新(全量更新);
    3. 人员特征录入指令feature_input增加了几种不同的input_status响应结果;
    4. 增加考勤机人员特征信息更新指令feature_update
    5. 所有重要的设备端请求,标注应通过QOS级别1进行消息传输,一旦消息发送成功,由云平台保障消息可靠传递到应用,不需要应用再回复确认响应消息;
    6. 设备绑定时的产品特征数据增加了一些新的属性,例如user_sync_size
  • 1.3 (2018-07-18)

    1. 针对D2/D3等高端机型,增加了应用远程设置参数的功能支持,包括考勤方式、音量以及响铃设置;
    2. 增加考勤数据查询接口功能;
  • 1.4 (2019-07-08)

    1. 针对DL-D5考勤机增加了应用端拍照录入人脸的支持;