云考勤接入协议（已废弃）
协议说明
云考勤接入协议主要描述了考勤场景下云考勤机与应用如何通过数据交互实现考勤机人员同步、人员特征录入以及考勤打卡数据上报等考勤关键业务。
注意，该版本的协议已废弃，请新加入的考勤设备使用综合人员签到协议接入。
设备交互指令
人员同步
人员同步是所有考勤操作的基础，为了保证考勤机和应用之间的数据一致性，设备和应用应支持增量同步和全量同步两种方式。其中，增量同步是指考勤应用根据考勤机之前的数据同步状态，仅推送增量变更的同步数据；全量同步则是设备从0开始完整的同步应用中当前所有考勤人员列表信息。
当应用端考勤人员列表发生变化时（包括人员添加、删除，特征信息添加、删除等等），考勤应用应通过指令500主动推送变动信息到设备，请求示例如下：
{
"mid": "123456",
"from": "考勤应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"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，但可以通过产品配置参数user_sync_size进行更新设置。
考勤机设备收到变更信息后，应在处理完成后通过指令300实时返回确认响应给应用端，响应消息示例如下:
{
"mid": "123456",
"from": "设备ID",
"to": "考勤应用ID",
"time": 1502867086,
"action": 300,
"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时，如果应用判断设备数据不一致时，应清除同步队列，重新发布全量同步 |
应用收到请求后，比对服务器该设备的考勤人员数量以及对应hash值，如果发现与设备请求数据不一致，则认为设备数据同步出错。此时，应用应重建推送队列启动全量推送，将第一条推送的reset标记设置为true。
注意，应用在校验hash时应保证所有推送给设备的增量更新消息均已处理完成。如果在应用收到user_sync_check时，应用端仍有部分推送数据未成功推送至设备，应用应忽略该校验请求。
人员特征录入
应用可通过以下指令向考勤机发起人员特征数据录入，具体设置支持的特征类型可通过产品配置参数check_type获取，请求示例如下：
{
"mid": "123456",
"from": "考勤应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "feature_input",
"payload": {
"user_id": "用户ID",
"feature_type": "fa"
}
}
}cmd固定为feature_input表示用户特征数据录入，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 字符串 | 当前录入的用户ID |
| feature_type | 字符串 | 当前设备端录入的用户特征类型。包括: fa: 人脸； fp: 指纹； pass: 密码； card: 员工卡； identity: 身份证； |
设备收到请求后，启动用户特征录入解析流程，并实时上传特征录入状态结果，响应示例如下:
{
"mid": "123456",
"from": "设备ID",
"to": "发起应用服务ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "feature_input",
"payload": {
"user_id": "用户ID",
"input_status": 1,
"feature_type": "fa",
"feature_value": "用户特征结果值"
}
}
}payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 字符串 | 当前特征录入的用户ID |
| input_status | 整型 | 特征录入状态： 0：录入超时（例如60秒） 1：录入完成； 2：设备繁忙； 3：录入准备就绪，仅在设备端录入时返回； 4：设备容量已满； 5：当前用户特征已录满； 6：当前用户不存在； 7：录入已取消； |
| feature_type | 字符串 | 当前录入的特征类型，录入完成时返回。 |
| feature_value | 字符串 | 当前录入的用户特征解析结果数据，录入完成时返回。 |
设备应在不同的情况下，给应用返回不同的状态数据:
- 如果需要设备端录入用户特征，且设备能够正常进入录入状态，应立刻返回设备"录入就绪状态(3)"；
- 如果设备本地录入用户特征成功，应返回"录入完成(1)"并附带返回已解析的用户特征结果值。
- 如果设备进入录入状态后，长时间没有完成特征数据录入操作，则应返回"录入超时(0)"；
- 如果设备在收到请求时无法响应，例如正在处理其它用户的特征录入请求，则应立刻返回"设备繁忙(2)"；
- 如果设备本地容量已满，无法存储更多特征数据，则应立刻返回"设备容量满(4)"；
- 如果当前请求用户的特征最大录入数已满，则应立刻返回"当前用户特征已录满(5)"；
- 如果当前请求用户在本地人员列表中不存在，则应立刻返回"当前用户不存在(6)"， 并通过人员同步检查指令检查设备本地的人员数据是否正常；
- 如果设备在录入中，用户在设备端或者APP端手动取消了录入，则应立刻返回"录入已取消(7)"；
如果设备特征录入解析已成功，为了保证体验，设备在上传数据到应用时，不论消息是否发送成功，都应实时将特征数据保存到设备本地，以便于用户立刻进行识别操作。
另外，应用端在更新了用户特征信息后，如果其它考勤设备相同的考勤人员使用了同样的特征算法版本，应用应自动将该用户的更新特征信息推送到对应设备端。
人员特征录入取消
应用通知设备开始特征信息录入后，可以主动调用该指令调用取消设备端的特征信息录入或解析工作，请求示例如下:
{
"mid": "123456",
"from": "考勤应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "feature_input_cancel",
"payload": {
"user_id": "用户ID",
"feature_type": "fa"
}
}
}cmd固定为feature_input_cancel表示用户特征数据录入取消，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 字符串 | 当前正在录入的用户ID |
| feature_type | 字符串 | 当前正在进行的特征录入类型 |
设备收到该请求后，如果user_id和feature_type均与本地录入状态一致且当前设备正处于录入过程中，则自动取消录入，否则忽略该请求。
设备如果取消成功，可返回特征录入指令feature_input的状态码7。
人员特征异常上报
对于通过手机APP等非设备端特征录入方式同步到设备的人员特征信息，由于不同设备硬件条件以及算法的不同，可能会出现部分人员特征解析失败、重复等异常问题。设备在user_sync人员特征数据同步成功后，可通过本指令向应用上报人员特征解析异常信息，便于应用通知相关人员及时更新处理。
请求示例如下：
{
"mid": "123456",
"from": "设备ID",
"to": "门禁应用服务ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "feature_error",
"payload": {
"error_list": [
{
"user_id": 123,
"feature_type": "fa",
"feature_value": "AIhzD5DXAojGCHb339+OEPd3Jvfd8X9/km9igtkoLc2PIGaC2S0p951iIIDQLWPi",
"feature_length": 394858,
"index": 0,
"status": 2,
"detail": "与用户111特征重复"
}
]
}
}
}payload中通过error_list可批量返回一组人员特征解析失败的信息。其中，各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 字符串 | 当前特征解析的用户ID |
| feature_type | 字符串 | 当前解析的特征类型 |
| feature_value | 字符串 | 可选。当前解析特征值的前64个字符，用于检查设备是否特征值同步出现了异常 |
| feature_length | 整型 | 可选。当前解析特征值的字符串长度，用于检查设备是否特征值同步出现了异常 |
| index | 整型 | 当前解析的人员特征的索引，从0开始 |
| status | 整型 | 特征解析异常状态： 1: 特征数据错误，无法解析； 2: 特征重复； |
| detail | 字符串 | 可选。设备端解析错误具体原因描述，设备端自定义 |
人员特征更新
考勤机在多次打卡过程中可能会更新用户特征模版，已达到更高的用户识别度。当考勤机人员指纹或人脸特征更新之后，可通过以下请求发送请求到应用端进行更新:
{
"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开始。主要针对支持类似指纹等多个特征信息录入的场景。 |
应用在收到用户指纹或人脸特征编码更新信息后, 处理方式应与录入新特征数据成功一致。
考勤打卡
员工通过密码、指纹或人脸考勤打卡时，设备需将打卡数据实时发送至应用端，请求示例如下:
{
"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：考勤时间（精确到秒） |
为了降低上传频率，设备可定时批量提交考勤记录（例如5s一次）。
应用端在收到打卡数据后，应向考勤机回复确认消息，响应示例如下：
{
"mid": "123456",
"from": "应用服务ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "checkin"
}
}mid必须与请求一致。 为了避免消息丢失，如果考勤机在一段时间内（例如60s）未收到应用确认消息，应重新上传直到收到确认消息为止。
考勤打卡主动上报
因为某些意外情况导致部分考勤打卡记录在应用端丢失，平台还可以通过指令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两天的考勤打卡记录。设备收到消息后，无需校验，直接开始上传即可；
设备参数设置
设备支持通过应用端远程配置一些可变参数，具体支持的配置参数见设备参数。
请求示例如下:
{
"mid": "123456",
"from": "考勤应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "property_update",
"payload": {
"properties": [
{
"property": "check_type",
"value": "fa",
"ext_value": ""
},
......
]
}
}
}cmd固定为property_update表示设备可配置参数值更新，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| property | 字符串 | 参数名称 |
| value | 字符串 | 参数值 |
| ext_value | 字符串 | 参数值补充。主要针对自定义参数值场景使用 |
设备如果配置成功，应将更新结果返回给应用端，响应示例如下：
{
"mid": "123456",
"from": "设备ID",
"to": "考勤应用ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "property_update",
"payload": {
"code": 0,
"msg" : ""
}
}
}响铃设置
设备支持多组响铃设置，每组都有对应的响铃时间、时长以及响铃周期（按周天）选择。应用通过以下指令请求可向设备发起响铃设置，请求示例如下：
{
"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结尾。 |
设备如果配置成功，应将更新结果返回给应用端，响应示例如下：
{
"mid": "123456",
"from": "设备ID",
"to": "考勤应用ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "ring_config_update",
"payload": {
"code": 0,
"msg" : ""
}
}
}注意，应用端响铃设置每次都是全量更新，设备端收到响铃设置请求后，应清除本地设置重新写入。
第三方对接指令
考勤数据同步
考勤应用通过以下指令支持对外提供考勤打卡数据查询的功能，用于第三方ERP系统对接使用，请求示例如下：
{
"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响应消息体内返回。
人员特征更新
考勤应用通过以下指令支持对外提供考勤人员的特征信息录入&更新的功能，用于第三方人事系统对接使用，请求示例如下：
{
"mid": "123456",
"from": "system",
"to": "考勤应用ID",
"time": 1502867086,
"action": 409,
"data": {
"org_id": "组织ID",
"cmd": "feature_update",
"payload": {
"users": [
{
"ext_id": "12345",
"feature_type": "fa",
"feature_alg": "base64",
"feature_value": []
}
]
}
}
}其中cmd固定为feature_update表示人员特征更新，支持批量录入更新多人的特征数据，各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| ext_id | 字符串 | 用户外部系统ID |
| feature_type | 字符串 | 人员特征类型。包括: fa: 人脸； fp: 指纹； pass: 密码； card: 员工卡； identity: 身份证； |
| feature_alg | 字符串 | 特征算法标示，用于区分不同的特征值解析算法 |
| feature_value | 数组 | 录入的多个特征值信息 |
应用会根据外部人员ID找到对应的考勤人员并进行特征数据更新操作并返回结果。响应结果示例如下：
{
"error_ext_ids": ["12345"]
}响应结果各参数说明如下：
| 参数 | 类型 | 描述 |
|---|---|---|
| error_ext_ids | 数组 | 更新失败的人员列表。一般外部人员未同步到系统时产生，请确保录入特征之前完成组织人员的同步操作 |
设备参数
不同的考勤机产品型号支持的特性略有不同，并可通过开发者平台进行自定义配置。应用通过指令520可以获取设备对应产品型号的参数配置，并进行针对性的业务处理。
设备参数包括两个类别：固有特性和可配置参数。如果从平台未获取到某些参数的产品定义时，固有特性请直接使用默认值，可配置参数可视为不支持。
固有特性
设备固有的静态特性参数，不可配置更改，例如考勤机的用户容量等。
所有考勤机支持的固有特性如下：
| 参数名 | 是否必传 | 参数说明 | 默认值 | 示例值 |
|---|---|---|---|---|
| admin_limit | N | 设备管理员数量上限 | 10 | 10 |
| check_type | Y | 设备支持的考勤方式，逗号分隔； fa: 人脸； fp: 指纹； pass: 密码 |
fp | fa,fp |
| fa_alg | Y | 人脸识别算法标示。用于特征多设备同步时使用 | SMKFA | |
| fa_capacity | Y | 设备人脸容量 | 200 | 200 |
| fa_max | Y | 单用户最大人脸数 | 1 | 1 |
| fp_alg | N | 指纹识别算法标示。用于特征多设备同步时使用 | SMKFPL | |
| fp_capacity | Y | 设备指纹容量 | 1000 | 1000 |
| fp_max | Y | 单用户指纹数 | 3 | 3 |
| ring_group_size | N | 响铃最大组数 | 24 | 24 |
| user_capacity | Y | 考勤机用户容量 | 1000 | 1000 |
| user_sync_size | N | 设备支持单次同步人员数量 | 1 | 3 |
| fa_app_input | N | 是否支持APP录入人脸 | false | false |
可配置参数
设备可调节的特性参数，可通过设备参数设置等命令进行更改，例如音量。
所有考勤机设备支持的可配置参数列表如下：
| 参数名 | 参数说明 | 设置参数名 | 示例值 | 适用产品型号 |
|---|---|---|---|---|
| checkin_interval_config | 打卡间隔时间 | checkin_interval | [{"value":"0","text":"未设置","default": true},{"value":"1","text":"1分钟"},{"value":"30","text":"30分钟"},{"value":"59","text":"59分钟"}] | - |
| check_type_config | 设备可配置的考勤方式 | check_type | [{"value":"fa/fp","text":"指纹或人脸","default": true},{"value":"fa","text":"人脸"},{"value":"fp","text":"指纹"}] | - |
| volume_config | 设备音量配置 | volume | [{"value":"0","text":"关","default": true},{"value":"1","text":"低"},{"value":"2","text":"中"},{"value":"3","text":"高"}] | - |
所有可配置参数以_config后缀结尾，用于与固有特性进行区分。不同的可配置参数，其可配置的参数值的格式都是自定义的，需要应用自行完成解析。
另外，应用通过设备参数设置下发可配置参数到设备时使用的参数名，请使用上述表格中的设置参数名列。例如音量设置功能，应用在解析可配置参数时，是通过产品配置参数volume_config获取到音量可配置值的定义，但是下发到设备时发送的参数property应该是volume。