云门禁接入协议（已废弃）
协议说明
云门禁接入协议主要描述了门禁场景下云门禁机与应用如何通过数据交互实现门禁机人员同步、人员特征录入、门禁开门以及门禁打卡数据上报等门禁关键业务。
注意，该版本的协议已废弃，请新加入的门禁设备使用综合人员签到协议接入。
交互指令
人员同步
与考勤机人员同步类似，门禁机在开始使用之前，首先需要通过云门禁应用将可以使用门禁的人员列表同步到门禁设备中去，后续门禁人员列表的信息发生变化时，也应实时同步到门禁设备，保持设备和应用之前人员列表数据的最终一致性。
应用会采用增量同步的方式主动将应用端门禁人员变化数据推送到设备，同时为了避免意外情况的发生。设备和应用之间要定时进行一致性检查，如果数据不一致，则由应用发起全量同步从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": 123,
"user_type": 0,
"name": "张三",
"empno": "工号或空",
"dept": "部门或空",
"fp": ["指纹特征值",""],
"fa": ["人脸特征值",""],
"pass": "加密密码",
"card": "门禁卡ID",
"expire_time": 1502867086,
"admin": true
},
{
"user_id": 124,
"user_type": 0,
"delete": true
}
]
}
}
}
cmd固定为user_sync表示人员同步推送，请求payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| reset | Boolean | 设备重置本地数据标志。仅全量同步第一次推送时设置为true，其它情况设置为false。设备如果收到该标志为true，则应清除本地所有人员数据，然后进行同步更新 |
| total_count | 整型 | 本次人员同步操作的总条目数，包括所有新增、更新和删除条目数。仅在一次同步任务开始时设置，后续消息不设置该字段信息。 |
| users | 数组 | 本次增量更新的用户列表，包括: user_id:用户在组织内的唯一ID，32位整型； user_type:用户类型，0表示员工，1表示访客； name:用户在组织内的姓名； empno:可选，组织工号或空； dept:可选，部门或空； fp:可选，指纹特征值数组，如果不支持或者不存在，则置为空，根据设备特性可能会返回多个； fa:可选，人脸特征值数组，如果不支持或者不存在，则置为空，根据设备特性可能会返回多个； pass:可选，门禁密码不可明文传输，加密规则由应用和设备协商决定，不可外泄。如果不支持或者不存在，则置为空； card:可选，门禁卡唯一ID,如果不支持或者不存在，则置为空； expire_time:可选，门禁过期时间，精确到秒，默认为0表示永不过期，针对访客可设置一个过期时间，到期之后访客人员将无法使用门禁； admin:可选，如果是管理员，则为true，否则为空； delete:可选，删除标记，如果不是删除操作，则置为空，否则置为true且除 user_id和user_type外其它信息均不返回； |
应用一次推送给设备的变更信息个数默认为1，但可以通过产品配置参数user_sync_size进行更新设置。
门禁机设备收到人员变更信息后，应在处理完成后实时返回确认响应给应用端，响应消息示例如下:
{
"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 | 字符串 | 设备将本地所有门禁机人员的user_id通过异或计算得出hash值，公式示例如下: hash = user_id1 XOR user_id2 XOR user_id3.....XOR user_idN 。 |
| 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": 123,
"feature_type": "fa"
}
}
}
cmd固定为feature_input表示用户特征数据录入，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 整形 | 当前录入的用户ID |
| feature_type | 字符串 | 需要在设备端录入的用户特征数据类型。例如： fa: 录入人脸； fp: 录入指纹； pass: 门禁密码； card: 门禁卡ID信息 |
设备收到请求后，启动用户特征录入解析流程，并实时上传特征录入状态结果，响应示例如下:
{
"mid": "123456",
"from": "设备ID",
"to": "门禁应用服务ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "feature_input",
"payload": {
"user_id": 123,
"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": 123,
"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": 123,
"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": "access_data_upload",
"payload": {
"users": [
{
"user_id": 123,
"user_type": 0,
"access_type": "fp",
"access_time": 1503025335
},
{
"user_id": 124,
"user_type": 0,
"access_type": "fa",
"access_time": 1503028318
}
]
}
}
}
其中cmd固定为access_data_upload表示门禁打卡记录上传，请求payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| users | 数组 | 表示一批员工门禁打卡记录。其中各属性说明如下: user_id：用户ID，32位整型； user_type：用户类型，0表示员工，1表示访客; access_type：门禁打卡方式； access_time：打卡时间（精确到秒）； |
为了降低上传频率，设备可定时批量提交门禁打卡记录（例如5s一次）。
应用端在收到门禁打卡数据后，应向门禁机回复确认消息，响应示例如下：
{
"mid": "123456",
"from": "门禁应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "access_data_upload"
}
}
注意，确认消息的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": 300,
"data": {
"cmd": "device_status_update",
"payload": {
"status": 0
}
}
}
其中cmd固定为device_status_update表示门禁状态更新，请求payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| status | 整型 | 门禁状态。 0-门禁关闭状态； 1-门禁开启状态 |
应用收到该门禁状态变化后应返回确认信息给设备，响应示例如下：
{
"mid": "123456",
"from": "门禁应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "device_status_update"
}
}
开门时间段设置
管理人员可以通过应用控制门禁机每天工作的时间段，非工作时间段非管理人员无法通过身份识别打开门禁。
应用支持按照周天设置不同的工作时间段，并更新到设备，请求示例如下:
{
"mid": "123456",
"from": "门禁应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "access_time_config",
"payload": {
"times" : [
{
"day": [0,1,2,3,4,5,6],
"time_begin": "08:00",
"time_end": "21:00"
},
......
]
}
}
}
cmd固定为access_time_config表示设置门禁工作时间，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| times | 数组 | 多组工作时间段设置，包括： day:周天数组，0到6依次表示星期天到星期六； time_begin:门禁工作的开始时间，格式是HH:mm，精确到分; time_end:门禁工作的结束时间，格式是HH:mm，精确到分； |
应用支持多组的时间段设置，且每次更新时都应全量下发到设备，设备进行覆盖式更新。 设备更新成功后，应将更新结果实时返回给应用端，响应示例如下：
{
"mid": "123456",
"from": "设备ID",
"to": "门禁应用ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "access_time_config",
"payload": {
"code": 0,
"msg" : "错误描述"
}
}
}
注意，多组时间段设置可能存在重叠，设备在开门时间段判断时应逐一比较，只要当前时间符合其中任一组设置即可开门。
远程开门
应用应支持管理员通过APP远程控制门禁开启大门，以应对某些临时进入的特殊情况。但为了安全起见，远程开门应该尽可能让管理员和进入人员协作分3步来完成：
- 管理员通过APP生成临时授权码发送给门禁系统，门禁系统进入临时授权模式；
- 管理员通过其他方式（例如电话、短信等）将授权码告知需要进入室内的人员，并通过设备屏幕输入临时授权码（设备必须支持屏幕输入功能）；
- 门禁系统本地验证授权码，并打开大门。
首先，应用将临时开门授权信息通过指令发送到设备，请求示例如下：
{
"mid": "123456",
"from": "门禁应用ID",
"to": "设备ID",
"time": 1502867086,
"action": 500,
"data": {
"cmd": "access_remote_control",
"payload": {
"admin_id" : 1,
"access_code" : "开门授权码加密字符串",
"expire_time": 1502867086
}
}
}
cmd固定为access_remote_control表示远程开门授权，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| admin_id | 整型 | 授权管理员ID |
| access_code | 字符串 | 开门授权码的MD5加密字符串。由APP生成6位数字授权码，授权码需要加密，加密规则由应用与设备协商决定，不可外泄。针对设备不支持输入或者其他特殊场景，应用可不返回授权码，这种情况视为紧急开门，不需要用户确认直接开门 |
| expire_time | 整型 | 授权码过期时间，精确到秒。授权码未返回时，不需要 |
设备收到该请求后，如果需要授权码，则设备应立刻进入授权码输入界面，否则直接开门。设备响应消息示例如下：
{
"mid": "123456",
"from": "设备ID",
"to": "门禁应用ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "access_remote_control",
"status" : 0
}
}
其中，status在不同的情况下返回值不同:
| status值 | 描述 |
|---|---|
| 0 | 设备就绪。需要授权码的情况下，设备进入录入就绪状态时返回。 |
| 1 | 录入成功。需要授权码的情况下且用户录入授权码成功，门禁开启并返回 |
| 2 | 录入失败。需要授权码的情况下，用户输入错误次数超过上限（例如3次），设备应自动退出授权模式并返回 |
| 3 | 录入超时。用户授权码过期之前没有完成录入，设备视为授权超时返回 |
| 4 | 主动取消。用户在设备端通过Esc键操作等方式主动退出了远程授权模式时返回 |
| 5 | 权限验证失败。如果管理员信息认证失败时返回 |
| 9 | 设备异常。门禁设备出现故障无法开门时返回 |
注意，设备在不同的状态下应返回不同的status。设备一旦进入授权模式且用户输入完成授权码后，设备本地应通过相同的计算公式计算出结果与应用提供的授权access_code进行比对，如果完全一致且没有过期则视为认证通过，自动开启门禁，否则应提示对应的错误。
为了安全起见，每个远程授权码只能用一次，且存在过期时间，另外，为了避免暴力破解，重试一定次数后将自动视为失败，并退出远程授权模式。
另外，如果门禁开启成功，设备需要通过门禁打卡将远程开门记录上传，但access_type应为remote，user_id为授权管理员id。
APP扫码开门
用户可通过APP扫描设备二维码的方式开启门禁。为了保证安全，设备生成的二维码信息应该定时刷新，建议60s刷新一次。
二维码的内容格式如下：
https://delicloud.com/d/{设备ID}/appcall?to=YMJ&data={原始授权码}。
其中，YMJ是云门禁应用在云平台的唯一标示，原始授权码由设备按照一定的算法每次随机生成6位数字组成。由于授权码会定时刷新，为了避免在刷新期间用户扫码开门失败的问题，刷新前的授权码应该仍然有效。也就是说，一个时刻当前和上次的授权码均为有效授权码。
APP扫码成功之后，解析data信息并通过服务器请求开启门禁，服务器校验该用户身份后，向设备发送开启请求，示例如下：
{
"mid": "消息ID",
"from": "门禁应用ID",
"to": "设备ID",
"action": 500,
"time": 1503025335,
"data": {
"cmd": "access_app_scan",
"payload": {
"user_id": 2,
"access_code" : "开门授权码加密字符串"
}
}
}
cmd固定为access_app_scan表示APP扫码开门，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 整型 | APP扫码开门的用户ID |
| access_code | 字符串 | 与远程开门一样，该授权字符串需要加密，加密规则由应用和设备协商，不可外泄 |
设备收到请求后，根据不同情况返回不同的响应结果，响应请求示例：
{
"mid": "123456",
"from": "设备ID",
"to": "门禁应用ID",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "access_app_scan",
"code" : 0
}
}
code在不同的情况下返回值不同:
| code值 | 描述 |
|---|---|
| 0 | 验证通过，自动开启门禁。 |
| 1 | 授权码不正确。 |
| 2 | 不存在的用户。 |
| 3 | 非开门时间段，拒绝开门。 |
| 9 | 设备异常，无法开启门禁。 |
注意：门禁设备开启成功后， 第一时间需要主动刷新设备二维码。另外，同样需要通过门禁打卡将APP扫码开门记录上传，但access_type应为app_scan，user_id为APP扫码的用户id。
门禁抓拍上报
对于支持监控抓拍功能的门禁机，可通过以下请求向应用上传抓拍结果信息，示例如下：
{
"mid": "消息ID",
"from": "设备ID",
"to": "门禁应用ID",
"action": 300,
"time": 1503025335,
"data": {
"cmd": "access_capture",
"payload": {
"user_id": 2,
"capture_data" : "抓拍图像数据",
"capture_time": 1503025335
}
}
}
cmd固定为access_capture表示门禁抓拍上报，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| user_id | 整型 | 抓拍识别到的人员ID。如果未识别，则不返回 |
| capture_data | 字符串 | 抓拍到的图像信息，base64编码 |
| capture_time | 整型 | 抓拍时间，精确到秒 |
设备参数设置
设备支持通过应用端远程配置一些可变参数，具体支持的配置参数见设备参数。
请求示例如下:
{
"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" : "错误描述"
}
}
}
设备参数
不同的门禁机产品型号支持的特性略有不同，并可通过开发者平台进行自定义配置。应用通过指令520可以获取设备对应产品型号的参数配置，并进行针对性的业务处理。
设备参数包括两个类别：固有特性和可配置参数。如果从平台未获取到某些参数的产品定义时，固有特性请直接使用默认值，可配置参数可视为不支持。
固有特性
设备固有的静态特性参数，不可配置更改，例如门禁机的用户容量等。
所有门禁机支持的固有特性如下：
| 参数名 | 是否必传 | 参数说明 | 默认值 | 示例值 |
|---|---|---|---|---|
| check_type | Y | 门禁机支持的开门方式 | fp | fa,fp,pass,card |
| 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 |
| user_capacity | Y | 考勤机用户容量 | 1000 | 1000 |
| user_sync_size | N | 设备支持单次同步人员数量 | 1 | 3 |
| fa_app_input | N | 是否支持APP录入人脸 | false | false |
可配置参数
设备可调节的特性参数，可通过设备参数设置等命令进行更改，例如音量。
所有门禁机设备支持的可配置参数列表如下：
| 参数分类 | 参数名 | 参数说明 | 设置参数名 | 示例值 |
|---|---|---|---|---|
| 识别设置 | check_type_config | 识别方式 | check_type | [{"value":"fa","text":"人脸"},{"value":"card","text":"刷卡"},{"value":"fa/card","text":"人脸或卡", "default":true}] |
| 识别设置 | faceScore_config | 人脸识别阈值 | faceScore | [{"value":"85", "text":"精准"},{"value":"80", "text":"常规", "default":true},{"value":"70", "text":"极速"}] |
| 识别设置 | faceDetectionType_config | 人脸检测类型 | faceDetectionType | [{"value":"1","text":"多人识别"},{"value":"2","text":"单人识别","default":true}] |
| 识别设置 | checkin_interval_config | 识别间隔 | checkin_interval | [{"value":"0","text":"未设置"},{"value":"60","text":"1分钟","default": true},{"value":"1800","text":"30分钟"},{"value":"3600","text":"1小时"}] |
| 识别设置 | comRecRank_config | 识别登记级别 | comRecRank | [{"value":"1", "text":"非活体"},{"value":"2", "text":"活体", "default":true}] |
| 识别设置 | comRecDistModeType_config | 识别距离 | comRecDistModeType | [{"value":"1","text":"无限制"},{"value":"2","text":"0.5以内"},{"value":"3","text":"1米以内","default":true},{"value":"4","text":"1.5米以内"}] |
| 识别成功信号输出配置 | recSucComModeType_config | 串口输出类型 | recSucComModeType | [{"value":"1","text":"开门","default":true},{"value":"2","text":"不输出"},{"value":"3","text":"输出phone"},{"value":"4","text":"输出cardNo"},{"value":"100","text":"自定义"}] |
| 识别成功信号输出配置 | recSucComModeContent_config | 串口输出自定义内容 | recSucComModeContent | {"type":"string","max":100,"tips":"100字以内，格式不限"} |
| 识别成功信号输出配置 | recSucWiegandType_config | 韦根输出类型 | recSucWiegandType | [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}] |
| 识别成功信号输出配置 | recSucWiegandContent_config | 韦根输出内容 | recSucWiegandContent | {"type":"string","max":255, "tips":"允许{phone}、{cardNo}。其他内容只允许数字、英文和英文字符"} |
| 识别成功信号输出配置 | recSucRelayType_config | 继电器输出类型 | recSucRelayType | [{"value":"1","text":"输出", "default":true},{"value":"2","text":"不输出"}] |
| 识别成功设备交互配置 | comRelayTime_config | 开门后延迟关门时长 | comRelayTime | [{"value":"1","text":"1s"},{"value":"3","text":"3s","default":true},{"value":"5","text":"5s"},{"value":"10","text":"10s"},{"value":"15","text":"15s"},{"value":"20","text":"20s"},{"value":"25","text":"25s"}] |
| 识别成功设备交互配置 | recSucTtsModeType_config | 语音播报类型 | recSucTtsModeType | [{"value":"1","text":"播报名字","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}] |
| 识别成功设备交互配置 | recSucTtsModeContent_config | 语音播报自定义内容 | recSucTtsModeContent | {"type":"string","max":255, "tips":"允许{name}、{tag}。字段格式固定，其他内容只允许数字、英文和汉字，长度限制255个字符"} |
| 识别成功设备交互配置 | recSucDisplayText1Type_config | 人员称呼显示文字 | recSucDisplayText1Type | [{"value":"1","text":"名字","default":true},{"value":"100","text":"自定义"}] |
| 识别成功设备交互配置 | recSucDisplayText1Content_config | 人员称呼自定义文字内容 | recSucDisplayText1Content | {"type":"string","max":4, "tips":"最多4个字，格式不限"} |
| 识别成功设备交互配置 | recSucDisplayText2Type_config | 识别状态栏显示文字 | recSucDisplayText2Type | [{"value":"1","text":"识别成功","default":true},{"value":"100","text":"自定义"}] |
| 识别成功设备交互配置 | recSucDisplayText2Content_config | 识别状态栏自定义文字内容 | recSucDisplayText2Content | {"type":"string","max":8, "tips":"最多8个字，格式不限"} |
| 识别失败交互配置 | recFailEnable_config | 识别失败开关 | recFailEnable | [{"value":"1","text":"打开","default":true},{"value":"2","text":"关闭"}] |
| 识别失败交互配置 | recFailTimesThreshold_config | 识别失败判定陌生人次数 | recFailTimesThreshold | {"type":"number","min":1,"max":20,"default":3,"tips":"请选择1-20之间的整数，1表示快速判定但精确率最低，随着数值增加，判定时间增加，精确度提高"} |
| 识别失败交互配置 | recFailTtsModeType_config | 语音播报类型 | recFailTtsModeType | [{"value":"1","text":"识别失败","default":true},{"value":"2","text":"不播报"},{"value":"100","text":"自定义"}] |
| 识别失败交互配置 | recFailTtsModeContent_config | 语音播报自定义内容 | recFailTtsModeContent | {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"} |
| 识别失败交互配置 | recFailDisplayTextType_config | 识别状态栏文字类型 | recFailDisplayTextType | [{"value":"1","text":"识别失败","default":true},{"value":"100","text":"自定义"}] |
| 识别失败交互配置 | recFailDisplayTextContent_config | 识别状态栏自定义文字内容 | recFailDisplayTextContent | {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"} |
| 识别失败信号输出配置 | recFailComModeType_config | 串口输出类型 | recFailComModeType | {"value":"1","text":"开门"},{"value":"2","text":"不输出","default":true},{"value":"100","text":"自定义"}] |
| 识别失败信号输出配置 | recFailComModeContent_config | 串口输出自定义内容 | recFailComModeContent | {"type":"string","max":100, "tips":"100字以内，格式不限"} |
| 识别失败信号输出配置 | recFailWiegandType_config | 韦根输出类型 | recFailWiegandType | [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}] |
| 识别失败信号输出配置 | recFailWiegandContent_config | 韦根输出自定义内容 | recFailWiegandContent | {"type":"string","max":255, "tips":"只允许数字、英文和英文字符，长度限制255个字符"} |
| 识别失败信号输出配置 | recFailRelayType_config | 继电器输出类型 | recFailRelayType | [{"value":"1","text":"输出"},{"value":"2","text":"不输出","default":true}] |
| 权限不足（非开门时段）交互配置 | recNoPerTtsModeType_config | 语音播报类型 | recNoPerTtsModeType | [{"value":"1","text":"播报姓名权限不足","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}] |
| 权限不足（非开门时段）交互配置 | recNoPerTtsModeContent_config | 语音播报自定义内容 | recNoPerTtsModeContent | {"type":"string","max":255, "tips":"允许{name}、{tag}。字段格式固定，其他内容只允许数字、英文和汉字，长度限制255个字符"} |
| 权限不足（非开门时段）交互配置 | recNoPerDisplayText1Type_config | 人员称呼文字类型 | recNoPerDisplayText1Type | [{"value":"1","text":"名字","default":true},{"value":"100","text":"自定义"}] |
| 权限不足（非开门时段）交互配置 | recNoPerDisplayText1Content_config | 人员称呼自定义文字内容 | recNoPerDisplayText1Content | {"type":"string","max":4, "tips":"最多4个字，格式不限"} |
| 权限不足（非开门时段）交互配置 | recNoPerDisplayText2Type_config | 识别状态栏文字类型 | recNoPerDisplayText2Type | [{"value":"1","text":"权限不足","default":true},{"value":"100","text":"自定义"}] |
| 权限不足（非开门时段）交互配置 | recNoPerDisplayText2Content_config | 识别状态栏自定义文字内容 | recNoPerDisplayText2Content | {"type":"string","max":8, "tips":"最多8个字，格式不限"} |
| 权限不足（非开门时段）信号输出配置 | recNoPerComModeType_config | 串口输出类型 | recNoPerComModeType | [{"value":"1","text":"开门","default":true},{"value":"2","text":"不输出"},{"value":"3","text":"输出phone"},{"value":"4","text":"输出cardNo"},{"value":"100","text":"自定义"}] |
| 权限不足（非开门时段）信号输出配置 | recNoPerComModeContent_config | 串口输出自定义内容 | recNoPerComModeContent | {"type":"string","max":100, "tips":"100字以内，格式不限"} |
| 权限不足（非开门时段）信号输出配置 | recNoPerWiegandType_config | 韦根输出类型 | recNoPerWiegandType | [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}] |
| 权限不足（非开门时段）信号输出配置 | recNoPerWiegandContent_config | 韦根输出自定义内容 | recNoPerWiegandContent | {"type":"string","max":255, "tips":"只允许数字、英文和英文字符，长度限制255个字符"} |
| 权限不足（非开门时段）信号输出配置 | recNoPerRelayType_config | 继电器输出类型 | recNoPerRelayType | [{"value":"1","text":"输出"},{"value":"2","text":"不输出","default":true}] |
| 屏幕显示配置 | scrDisplayText1Type_config | 屏幕左下角固定文字区域文字类型 | scrDisplayText1Type | [{"value":"1","text":"不显示","default":true},{"value":"2","text":"组织名称"},{"value":"100","text":"自定义"}] |
| 屏幕显示配置 | scrDisplayText1Content_config | 屏幕左下角固定文字区域自定义内容 | scrDisplayText1Content | {"type":"string","max":255,"tips":"255字以内，格式不限"} |
| 屏幕显示配置 | scrDisplayText2Type_config | 屏幕右下角固定文字区域文字类型 | scrDisplayText2Type | [{"value":"1","text":"不显示","default":true},{"value":"2","text":"设备名称"},{"value":"100","text":"自定义"}] |
| 屏幕显示配置 | scrDisplayText2Content_config | 屏幕右下角固定文字区域自定义内容 | scrDisplayText2Content | {"type":"string","max":255,"tips":"255字以内，格式不限"} |
所有可配置参数以_config后缀结尾，用于与固有特性进行区分。不同的可配置参数，其可配置的参数值的格式都是自定义的，需要应用自行完成解析。
另外，应用通过设备参数设置下发可配置参数到设备时使用的参数名，请使用上述表格中的设置参数名列。例如识别方式，应用在解析可配置参数时，是通过产品配置参数check_type_config获取到门禁机识别方式可配置值的定义，但是下发到设备时发送的参数property应该是check_type。
考勤门禁集成
由于门禁与考勤类似，均可用于员工出入管理。原则上来讲，门禁打卡记录上传门禁系统之后，可通过接口开放给考勤系统用于员工考勤。
为了实现门禁数据与考勤系统的互通，门禁应用应开放以下接口用于考勤：
1. 门禁数据开启通知；
2. 门禁数据推送；
3. 门禁数据关闭通知；
门禁应用可通过平台指令409以及指令516实现应用之间的接口通信。注意，以上接口均为同步请求，如果请求失败，应触发重试机制或提示用户重新操作。
门禁数据开启通知
组织管理人员可在门禁应用主动开启考勤，开启之后，门禁应用将主动向考勤应用发起门禁数据开启通知。通知请求示例如下：
{
"mid": "消息ID",
"from": "门禁应用ID",
"to": "考勤应用ID",
"action": 516,
"time": 1503025335,
"data": {
"org_id": "组织ID",
"cmd": "access_data_open"
}
}
cmd固定为access_data_open表示开启门禁数据推送，无payload参数。
开启通知请求通过指令409转发给考勤应用后，如果接收成功，考勤应用应同步返回如下结果：
{
"code": 0,
"msg": "",
"time": 1503025335
}
一旦开启成功，门禁应用后续应自动推送本组织内门禁数据的变化信息到考勤应用，具体内容见下一小节。
门禁数据推送
对于已经开启了门禁应用数据的其他应用，门禁应用应主动将门禁数据的信息更新实时推送给目标应用，推送信息包括：
1. 门禁设备数据；
2. 门禁打卡数据；
门禁设备推送数据应包括门禁机设备的更新（包括绑定、解绑）、设备名称以及设备状态的变化，推送数据请求示例如下：
{
"mid": "消息ID",
"from": "门禁应用ID",
"to": "订阅应用ID",
"action": 516,
"time": 1503025335,
"data": {
"org_id": "组织ID",
"cmd": "device_data_push",
"payload": {
"devices": [
{
"device_id": "设备ID",
"device_name": "设备名称",
"status": 0
},
{
"device_id": "设备ID",
"delete": true
}
]
}
}
}
cmd固定为device_data_push表示门禁设备数据推送，payload各参数说明如下:
| 参数 | 类型 | 描述 |
|---|---|---|
| devices | 数组 | 设备信息列表，仅推送发生变化的设备信息。包括: device_id:设备ID； device_name:设备名称； status: 设备状态，0表示离线，1表示在线； delete:可选，删除标记，如果设备未解绑，则置为空，否则置为true且除 device_id外其它信息均不返回 |
门禁打卡数据推送应包括组织内人员通过门禁设备打卡的所有数据，推送请求示例如下：
{
"mid": "123456",
"from": "门禁应用ID",
"to": "考勤应用ID",
"time": 1502867086,
"action": 516,
"data": {
"cmd": "access_data_push",
"payload": {
"users": [
{
"user_id": 123,
"user_type": 0,
"access_type": "fp",
"access_time": 1503025335
},
{
"user_id": 124,
"user_type": 0,
"access_type": "fa",
"access_time": 1503028318
}
]
}
}
}
其中cmd固定为access_data_push表示门禁打卡数据推送，payload各参数与门禁打卡上传一致。
门禁数据关闭通知
与开启功能对应，门禁应用可主动关闭对考勤应用的数据推送。关闭后应通知考勤应用，通知请求示例如下：
{
"mid": "消息ID",
"from": "门禁应用ID",
"to": "考勤应用ID",
"action": 516,
"time": 1503025335,
"data": {
"org_id": "组织ID",
"cmd": "access_data_close"
}
}
cmd固定为access_data_close表示关闭门禁数据推送，无payload参数。
关闭通知请求通过指令409转发给考勤应用后，如果接收成功，考勤应用应同步返回如下结果：
{
"code": 0,
"msg": "",
"time": 1503025335
}
访客设计
访客和普通员工比较，除了没有工号之外，其门禁支持的操作方式基本一致。因此，在整个协议交互流程上来讲，会保持统一的设计。
考虑到访客和普通员工在门禁机设备上都属于门禁用户，但需要有全局唯一的用户ID标示，我们约定在应用创建访客人员信息时，其起始ID为10^8（也就是1亿），最多支持1000个访客（0～999）。
在创建访客信息时，需要为访客生成7位数的授权码。授权码的生成规则为： 0 + {后3位用户ID} + {3位的随机密码} , 其中首位0是访客授权码特殊标示符。假如某个访客的ID为10^8 + 11，三位随机密码为345，那么最终的授权码为0011345。
创建访客完成后，访客信息也应通过人员同步下发到门禁设备中。其中，user_id为访客的ID，user_type固定为1，pass为生成访客授权码的3位随机密码的MD5值。
当用户在门禁设备上首位输入为0时，门禁设备应自动识别为访客授权码输入模式。用户输入完毕后，门禁机设备应按照与应用相同的规则识别出访客的真实信息。比如，用户输入00111345，则对应的访客ID为10^8 + 11，密码是345。