登录
智慧硬件开发 硬件直连接入 考勤/门禁设备 接口调用 指纹/人脸多算法版本协议
指纹/人脸多算法版本协议
最后更新：2022/09/16
目录
1.订阅企业信息
当企业取消授权后secret失效，当调用登录或者激活接口返回企业未授权时，设备应清空所有数据，重新进行激活。
若设备已经获取过secret并保存，下次联网时可以跳过active，直接发起subscribe_corp。
请求包体：
{
"cmd":"subscribe_corp",
"headers":
{
"req_id":"xxxxx"
},
"body":
{
"secret":"xxxxx",
"firmware_version":"xxxxx",
"ext_args":
{
"fp_algorithm":["aaa", "bbbb"],
"fa_algorithm":["ccc", "dddd"]
}
}
}参数说明：
| 参数名 | 是否必须 | 类型 | 描述 |
|---|---|---|---|
| req_id | 是 | String | 请求的id，自行保证不会重复即可 |
| secret | 是 | String | 凭证密钥 |
| firmware_version | 是 | String | 当前固件版本号 |
| ext_args | 否 | object | 额外参数 |
| fp_algorithm | 否 | array(string) | 该设备支持的指纹算法，"default"为默认值，最多支持5个，仅当设备支持采集指纹时支持该参数，订阅后企业微信会按照本参数优先级选择指纹下发（在数组位置越靠前优先级越高） |
| fa_algorithm | 否 | array(string) | 该设备支持的人脸算法，"default"为默认值，最多支持5个，仅当设备支持采集人脸时支持该参数，订阅后企业微信会按照本参数优先级选择人脸下发（在数组位置越靠前优先级越高） |
返回结果：
{
"headers": {
"req_id" : "xxxx"
},
"errcode": 0,
"errmsg": "ok"
}参数说明：
| 参数名 | 描述 |
|---|---|
| req_id | 透传请求的req_id |
| errcode | 错误码 |
| errmsg | 错误码描述 |
2.上传用户数据
用户录入指纹或人脸信息后，将信息同步至云端。最多200人。
请求包体：
{
"cmd":"upload_userinfo",
"headers":
{
"req_id":"xxxxx"
},
"body":
{
"oper_id":"xxxx",
"errcode":0,
"errmsg":"ok",
"userinfo":
[
{
"userid":"x1",
"user_type":0,
"fp_algorithm":"aaa",
"fp":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
],
"fa_algorithm":"bbb",
"fa_list":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
]
},
{
"userid":"x2",
"fa_algorithm":"bbb",
"fa_list":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
],
"user_type":1
}
]
}
}参数说明：
| 参数名 | 是否必须 | 类型 | 描述 |
|---|---|---|---|
| req_id | 是 | string | 请求的id，自行保证不会重复即可 |
| userid | 是 | string | 成员id（字符串），长度为1-128个字节。当为访客userid时，参见访客userid规则说明 |
| user_type | 否 | Uint32 | 成员的类型： 0：企业员工 1：访客 不填则默认值为0 |
| fa_list | 否 | Array(object) | 人脸数据列表，当fa_list存在时，忽略fa的值 |
| fa_algorithm | 否 | string | 人脸数据算法,没有该字段或者为"default"则为默认算法 |
| fa_list: id | 否 | string | 人脸数据编号，支持0-11，共12个人脸数据 |
| fa_list：data | 否 | string | 人脸数据base64编码，可不填，如果填入空串则表示删除 |
| fp_algorithm | 否 | string | 指纹数据算法, 没有该字段或者为"default"则为默认算法 |
| fp | 否 | Array(object) | 指纹数据 |
| fp: id | 否 | string | 指纹编号， 支持0-9，共十个指纹 |
| fp：data | 否 | string | 指纹数据(base64)，如果填入空串则表示删除 |
| oper_id | 否 | String | 录入指纹的操作id，由3.2 （进入录入信息）或者3.7（推送成员录制人脸事件）下发下去。 |
| errcode | 否 | int32 | 本次操作的返回值，0表示录入成功， 非0表示失败，非0的具体错误码可以机器自行定义。 |
| errmsg | 否 | string | 本次操作的结果描述， 如果录入成功请填写”ok”。其他errmsg可以机器自行定义。 |
注：oper_id，errcode，errmsg这三个参数填写时机为：在操作界面录入单个成员指纹1min内调用upload_userinfo接口。如果设备断网，后续网络恢复后的补推可以不填写。
访客或者企业内成员通过企业微信app录制也需要传回oper_id，页面会根据回传的errcode和errmsg展示录制结果。
企业微信允许第三方应用设置访客人脸。此处建议设备访客的信息补推一律都不要合并，且尽量带上oper_id，errcode，errmsg，方便企业微信通知第三方应用每个访客的录制结果。
返回结果：
{
"headers": {
"req_id" : "xxxx"
},
"body": {
"fail_list" : [
{
"userid":"x1"
},
{
"userid":"x3"
}
]
},
"errcode": 0,
"errmsg": "ok"
}参数说明：
| 参数名 | 描述 |
|---|---|
| req_id | 透传请求的req_id |
| errcode | 错误码 |
| errmsg | 错误码描述 |
| fail_list | 上传失败的用户， 返回值为userid |
3.全量拉取用户信息
设备每次登录成功之后，需要比对本地通讯录版本号和云端最大的版本号，如果不一致则设备需要主动调用该接口。
本接口为分页接口，每页数据返回时会同时返回当前云端的最大版本号，如果同步到最后一页的过程中版本号有变化则需要重新开始同步。
请求包体：
{
"cmd":"get_userinfo_by_page",
"headers":
{
"req_id":"xxxxx"
},
"body":
{
"offset":0,
"limit":10,
"is_req_fp_info":1,
"is_req_fa_info":1
}
}参数说明：
| 参数名 | 是否必须 | 类型 | 描述 |
|---|---|---|---|
| req_id | 是 | string | 请求的id，自行保证不会重复即可 |
| offset | 是 | Uint32 | 偏移量(范围是该机器设置的考勤人员列表) |
| limit | 是 | Uint32 | 本次同步的人数(最高200) |
| is_req_fp_info | 否 | Uint32 | 默认1, 0:不返回fp数据列表, 1:才返回 |
| is_req_fa_info | 否 | Uint32 | 默认1, 0:不返回fa数据列表, 1:才返回 |
返回结果：
{
"headers":
{
"req_id" : "xxxx"
},
"body":
{
"is_last": false,
"perm_version": 5,
"userinfo":
[
{
"userid":"x1",
"openvid":123456,
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"name":"张三",
"fp_algorithm":"aaa",
"fp":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
],
"fa_algorithm":"bbb",
"fa_list":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
]
},
{
"userid":"x2",
"openvid":1234567,
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"name":"李四",
"fa":"xxxx"
},
{
"userid":"x3",
"openvid":12345678,
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"name":"王五",
"fa_algorithm":"bbb",
"fa":"xxxx"
}
]
},
"errcode": 0,
"errmsg": "ok"
}参数说明：
| 参数名 | 描述 |
|---|---|
| req_id | 透传请求的req_id |
| errcode | 错误码 |
| errmsg | 错误码描述 |
| is_last | true/false 表示是否最后一页数据 |
| userid | 成员id（字符串），长度为1-64个字节。 |
| openvid | 成员id（uint64）， 可用于二维码签名校验 |
| user_type | 成员的类型： 0：企业员工 1：访客 本接口固定均为0 |
| fp_ver | 指纹版本号 |
| fa_ver | 人脸版本号 |
| pass_rule_list | 放行规则列表，id为编号，rule为具体规则，其解析语法请参考附录门禁放行规则语法说明 |
| effect_time | 规则生效时间 |
| fp | 成员指纹信息(base64), id,data数据同上传用户数据 |
| fa | 成员脸部识别信息(base64) |
| fa_list | 成员脸部识别信息(base64),id,data数据同上传用户数据 |
| name | 成员姓名，utf8编码，长度为1-64个字节 |
| perm_version | 当前云端通讯录版本号 |
| fa_algorithm | 人脸算法，没有该字段或者为"default"则为默认算法 |
| fp_algorithm | 指纹算法，没有该字段或者为"default"则为默认算法 |
注：成员没有放行规则或者放行规则为空时，建议默认行为是员工通行，访客不可通行。
4.增量拉取用户信息
设备收到成员增量同步的指令后主动调用该接口。
请求包体：
{
"cmd":"get_userinfo_by_ids",
"headers":
{
"req_id":"xxxxx"
},
"body":
{
"userids":
[
"x1","x2","x3"
],
"is_req_fp_info":1,
"is_req_fa_info":1
}
}参数说明：
| 参数名 | 是否必须 | 类型 | 描述 |
|---|---|---|---|
| req_id | 是 | string | 请求的id，自行保证不会重复即可 |
| userids | 是 | array(string) | Userid列表，最多200人 |
| is_req_fp_info | 否 | Uint32 | 默认1, 0:不返回fp数据列表, 1:才返回 |
| is_req_fa_info | 否 | Uint32 | 默认1, 0:不返回fa数据列表, 1:才返回 |
返回结果：
{
"headers":
{
"req_id" : "xxxx"
},
"body":
{
"userinfo":
[
{
"userid":"x1",
"openvid":123456,
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"name":"张三",
"fp_alogrithm":"aaa",
"fp":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
],
"fa_algorithm":"bbb",
"fa_list":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
]
},
{
"userid":"x2",
"openvid":1234567,
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"name":"李四",
"fp_alogrithm":"aaa",
"fp":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
]
},
{
"userid":"x3",
"openvid":12345678,
"name":"王五",
"user_type":0,
"fp_ver":1,
"fa_ver":1,
"pass_rule_list": [
{
"id":0,
"rule":"9:00-10:00 * * 1-5 *",
"effect_time":1542874137
},
{
"id":1,
"rule":"9:300-10:00 * * 6 *",
"effect_time":1542874137
}
],
"fp_alogrithm":"aaa",
"fp":[
{
"id":0,
"data":"xxxx"
},
{
"id":1,
"data":"xxxx"
}
]
}
]
},
"errcode": 0,
"errmsg": "ok"
}参数说明：
| 参数名 | 描述 |
|---|---|
| req_id | 透传请求的req_id |
| errcode | 错误码 |
| errmsg | 错误码描述 |
| userid | 成员id(字符串)，长度为1-64个字节 |
| openvid | 成员id(uint64) ， 可用于二维码签名校验 |
| user_type | 成员的类型： 0：企业员工 1：访客 本接口固定均为0 |
| fp_ver | 指纹版本号 |
| fa_ver | 人脸版本号 |
| pass_rule_list | 放行规则列表，id为编号，rule为具体规则，其解析语法请参考附录门禁放行规则语法说明 |
| effect_time | 规则生效时间 |
| fp | 成员指纹信息(base64), id,data数据同上传用户数据 |
| fa_list | 成员脸部识别信息(base64),id,data数据同上传用户数据 |
| name | 成员姓名 |
| fp_algorithm | 指纹算法，为空时表示默认算法 |
| fa_algorithm | 人脸算法，为空时表示默认算法 |
注：成员没有放行规则或者放行规则为空时，建议默认行为是员工通行，访客不可通行。
