综合人员签到协议

协议说明

综合人员签到协议主要描述了得力综合人员签到产品中如何通过与各类不同签到设备通信完成相应人员签到场景下的的关键业务，包括人员考勤、门禁通行、访客验证等等。

基础通用协议

所有和人员签到基础相关的设备交互指令定义如下，包括人员特征相关指令，设备参数配置指令等。

人员特征采集

应用可通过以下指令向特征采集设备发起人员特征录入操作，采集设备完成特征录入后需要实时将采集到特征数据上报到应用端保存，完成采集操作。

基本的采集流程描述如下:

应用->设备: 发起采集指令
设备->应用: 设备采集就绪
人员--设备: 采集人员特征
设备->应用: 采集完成，返回特征
Note left of 设备: 如果发生异常，也同步返回

注意：为了保证设备采集的人脸能够在不同型号设备都能够正常识别，请设备确保采集人脸符合系统规范要求。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_collect", 
        "payload": {
            "user_id": "123",
            "name": "张三",
            "feature_type": "fa"
        }
    }
}

其中，cmd固定为feature_collect，表示特征采集命令。payload参数说明如下：

请求参数 格式 必传 参数说明
user_id 字符串 Y 采集的人员ID标示
name 字符串 N 采集的人员名称，可用于采集屏幕显示
feature_type 字符串 Y 采集的人员特征类型。包括:
fa: 人脸；
fp: 指纹；
pass: 密码；
card: 员工卡；
identity: 身份证；

响应示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "feature_collect", 
        "payload": {
            "user_id": "123", 
            "input_status": 1,
            "error_msg": "",
            "feature_type": "fa",
            "feature_value": "特征值"
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
user_id 字符串 特征采集的人员ID，与请求一致
input_status 整型 设备特征采集状态：
0: 设备采集就绪；
1: 特征采集完成；
2: 特征采集超时；
3: 采集已取消；
4: 设备不支持；
9: 其他设备异常；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述
feature_type 字符串 当前采集的特征类型，仅在input_status等于1时返回。
feature_value 字符串 当前采集的人员特征结果数据，仅在input_status等于1时返回。

设备特征采集状态input_status的具体说明如下:

  1. 设备在接收到采集指令，且进入采集模式就绪时，应立刻返回状态0；
  2. 设备正常完成人员特征采集时，应返回状态1，并同步上传采集到的人员特征信息；
  3. 如果设备采集就绪之后，一段时间内未采集到人员特征，可主动退出采集模式，并返回状态2，具体超时时间可根据设备的场景决定；
  4. 如果设备支持主动退出采集模式，则在退出后返回状态3；
  5. 如果设备不支持采集或者不支持指令中要求的特征类型采集，则应返回状态4；
  6. 如果设备出现其他异常，则统一返回状态9，并通过error_msg返回更具体的异常原因；

人员特征采集取消

应用通知设备开始特征信息采集后，可以主动调用该指令调用取消设备端的特征信息采集工作，请求示例如下: 

{
    "mid": "123456", 
    "from": "考勤应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_collect_cancel", 
        "payload": {
            "user_id": "123",
            "feature_type": "fa"
        }
    }
}
其中cmd固定为feature_collect_cancel表示人员特征数据采集取消，payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前采集的用户ID
feature_type 字符串 当前采集的特征类型

设备收到该请求后，如果设备处于采集特征过程中且user_id和feature_type均与设备本地正在采集的用户数据一致，则自动退出采集，否则忽略该请求。

设备人员更新事件

当应用端与设备关联的人员信息包括基础属性和身份特征信息发生变化时，应用应通过本指令向设备发送通知事件。

设备在收到人员更新事件消息后，应主动调用设备人员同步指令进行同步更新。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "device_user_updated",
        "payload": {
            "reset": true
        }
    }
}

其中cmd固定为device_user_updated表示设备人员更新事件指令。payload参数说明如下:

参数 类型 描述
reset Boolean 设备人员同步重置标记，缺省为false。如果为true，则设备应清除本地所有人员数据，然后重新开始人员同步更新

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "device_user_updated"
    }
}

如果因为某些原因应用并未及时收到设备的确认消息，则应用应主动定时重发事件通知，直到收到设备确认为止。

设备人员同步

设备端通过本指令可使用增量模式向应用请求设备关联人员的更新信息。每次增量更新同步应以上次成功同步的时间点为起点，避免重复同步降低同步效率。

人员同步流程示意如下：

应用->设备: 设备人员变更事件
设备->应用: 消息确认
设备->应用: 设备人员同步
应用->设备: 根据请求时间点返回增量同步信息
设备--设备: 更新offset，继续同步
Note left of 设备: 循环同步，直到应用返回为空为止

为了确保设备始终与应用端保持信息一致，建议设备在每次上线初始化完成后，第一时间通过本指令同步最新的数据。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300,
    "data": {
        "cmd": "device_user_sync",
        "payload": {
            "offset": "1557821981123",
            "sync_size": 3
        }
    }
}

其中cmd固定为device_user_sync表示设备人员同步指令，请求payload各参数说明如下:

参数 类型 描述
offset 字符串 上一次同步成功的时间点。第一次同步时，请设置为0
sync_size 整型 单次设备同步的数量。根据设备自身的性能决定，缺省为1。 注意，特征数据较大，为了避免传递过大的消息影响性能，平台限制消息体大小不得超过512K，请确保单次同步的数据量不超过上限值，以免数据丢失。

响应示例

应用接收到请求后，向设备返回在请求offset时间点变更的人员信息，返回的变更数量不超过请求参数sync_size。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500,
    "data": {
        "cmd": "device_user_sync", 
        "payload": {
            "offset": "1568260681030", 
            "sync_size": 2,
            "users":[
                {
                    "user_id": "123", 
                    "user_type": 0,
                    "name": "张三", 
                    "empno": "A1234", 
                    "dept": "研发部", 
                    "title": "销售代表",
                    "fp": ["指纹特征值","..."],
                    "fa": ["人脸特征值","..."],
                    "pass":"4740ab3924d910bdd02564681bdd6878",
                    "identity": "440102198001021230",
                    "card":["cde10adc3949ba59a"],
                    "auth_code": ["wLrfPwJdLe3TdoMiVt1GoMXsHZvR04i0"],
                    "admin": true
                }, 
                {
                    "user_id": "113", 
                    "delete": true
                }
            ]
        }
    }
}
响应payload各参数的说明如下:

参数 类型 描述
offset 字符串 本次同步信息新的更新时间点。设备在本地更新完毕后，应将保存该时间点，用于下一次同步请求的offset
sync_size 整型 本次同步到更新条目数。该值与users数组条目数一致
users 数组 本次增量更新的人员列表，包括:
user_id: 人员ID,
user_type: 可选，人员类型，缺省为0。0表示员工，1表示访客；
name: 人员姓名,
empno: 可选，组织内员工工号,
dept: 可选，组织内员工所属部门名称,
title: 可选，人员在企业组织内的职称；
fp: 可选，指纹特征值数组；
fa: 可选，人脸特征值数组；
pass: 可选，加密密码，与员工号配合使用，密码加密规则为：MD5('原始密码'+'@'+'delicloud')。例如原始密码123456，则加密密码为：MD5("123456@delicloud")=4740ab3924d910bdd02564681bdd6878；
identity:可选，身份证编号；
card: 可选，员工ID卡数组；
auth_code: 可选，授权码数组，一般用于临时访客的身份标示；
admin: 可选，如果是管理员，则为true，否则为空,
delete: 可选，删除标记，如果不是删除操作，则置为空，否则置为true且除user_id外其它信息均不返回

设备收到人员同步信息后，应根据增量同步信息在本地完成变更操作，然后使用新的offset继续同步，直到应用返回的变更人员信息为空为止。

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

注意，如果因为某些异常原因（例如设备容量已满）导致设备无法写入人员信息，设备可终止同步操作，直到再次收到更新触发事件为止。 同时，设备应通过指令101向平台上报设备的异常状态，以便于管理人员直观了解情况。

设备人员同步检查

设备在同步完成之后，可通过本指令与应用对人员同步结果进行一致性检查。如果检查结果不一致，应用应主动发起设备人员更新事件，并将reset标记设置为true，要求设备清空本地设备人员重新同步。

为了确保及时能够发现同步问题，除了在设备每次上线和同步结束后都调用该指令之外，建议设备每天也定时进行至少一次检查。

设备->应用: 人员同步检查
应用--应用: 检查一致性
Note right of 应用: 如果一致，则终止后续流程
应用->设备: 发送全量人员同步事件
Note left of 应用: 设置reset=true
设备--设备: 清空本地人员数据
设备->应用: 重置offset，发起同步

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300,
    "data": {
        "cmd": "device_user_sync_check",
        "payload": {
            "offset": "1557821981123",
            "user_size": 100,
            "user_hash": "45af3a555f2b21a2b3111b9da318e50f"
        }
    }
}

其中cmd固定为device_user_sync_check表示设备人员同步指令，请求payload各参数说明如下:

参数 类型 描述
offset 字符串 设备最后同步成功的offset值
user_size 整型 设备本地已同步的总的人员数量
user_hash 字符串 设备将本地所有人员的数据通过算法计算得出hash值。公式如下: hash = MD5(user_id1 + user_id2 + user_id3.....+ user_idN) ，其中user_id按照数字从小到大顺序排列

当设备中没有人员时，user_hash无需计算，直接设置为空字符串。

注意，如果应用端发现设备返回的offset与同步结束的offset不一致，则视为同步并未完成，此时不需要对hash值进行比对计算。

user_hash 计算的例子 

    user_id1 = "3234", user_id2 = "3345", user_id3="42",
    按数值顺序排列，为  42, 3234, 3345,   注意不是按字符串顺序排序
    user_hash = MD5("4232343345") = "863d63bbf26d1448d5e94b6fab57124a"
    user_hash 忽略大小写

人员特征异常上报

对于通过手机APP或PC电脑等非设备端特征录入方式同步到设备的人员特征信息，由于不同设备硬件条件以及算法的不同，可能会出现部分人员特征解析失败、重复等异常问题。设备在人员数据同步完成后，可通过本指令向应用上报人员特征解析异常信息，便于应用通知相关人员及时更新处理。

请求示例

{
    "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特征重复"
                }
            ]
        }
    }
}

其中cmd固定为feature_error表示人员特征异常上报指令，请求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": 500, 
    "data": {
        "cmd": "feature_error"
    }
}
如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

人员特征更新

设备在多次签到识别过程中会因为样本的增加而通过本指令向应用更新人员特征解析信息，用于提高人员的特征相似度。应用在收到该消息后应更新签到人员对应类型的特征信息，并同步到其他关联设备。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "feature_update", 
        "payload": {
            "user_id": "123", 
            "feature_type": "fa",
            "feature_value": "特征值",
            "feature_index": 0
        }
    }
}
其中cmd固定为feature_update表示人员特征更新，请求payload各参数说明如下:

参数 类型 描述
user_id 字符串 当前特征识别的人员ID
feature_type 字符串 更新的特征类型
feature_value 字符串 设备解析更新后的特征结果数据
feature_index 整型 更新的人员特征编号，从0开始。

响应示例

应用收到请求后，应在同一消息上下文向设备返回确认。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_update"
    }
}

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

设备参数更新事件

应用端如果对设备参数做了更新，可通过指令向设备端发送更新事件，通知设备主动查询最新的设备参数配置。

设备收到该通知事件后，应主动调用设备参数配置查询指令向应用获取设备最新配置并更新。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "device_property_updated"
    }
}

其中cmd固定为device_property_updated表示设备参数更新事件指令。

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "device_property_updated"
    }
}

如果因为某些原因应用并未及时收到设备的确认消息，则应用应主动定时重发事件通知，直到收到设备确认为止。

设备参数配置查询

设备可通过本指令向应用主动查询最新的设备参数设置。

为了确保设备始终与应用端保持信息一致，建议设备在每次上线初始化完成后，第一时间通过本指令同步最新的数据。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "device_property_query"
    }
}

其中cmd固定为device_property_query表示设备参数配置查询指令。

响应示例

应用收到该请求后，应一次返回所有设备可配置参数的最新值列表。具体可配置的参数以及参数的值范围等请参考设备对应产品型号可配置参数的元数据定义。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "device_property_query",
        "payload": {
            "properties": [ 
                {
                    "property": "check_type",
                    "value": "fa"
                },
                {

                }
            ]
        }
    }
}

响应payload通过properties返回了设备所有的参数配置信息，每个设备参数的说明如下:

参数 类型 描述
property 字符串 参数名称
value 字符串 参数值

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

设备参数更新

对于某些特殊场景下，设备端本地支持参数的配置修改。修改完成后，设备可通过本指令向应用端更新参数信息。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300,  
    "data": {
        "cmd": "device_property_update", 
        "payload": {
            "properties": [ 
                {
                    "property": "check_type",
                    "value": "fa+card"
                },
                {

                }
            ]
        }
    }
}
其中cmd固定为device_property_update表示设备参数更新指令，payload通过properties一次包含多个参数的更新信息，每个更新信息的参数说明如下:

参数 类型 描述
property 字符串 参数名称
value 字符串 要更新的参数值

响应示例

应用收到请求后完成服务器端更新存储，并在一个消息上下文返回确认消息即可。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "device_property_update"
    }
}

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

签到数据主动上报

因为某些意外情况导致部分设备端签到记录未上报到应用端，平台管理人员可以通过本指令向设备主动发起请求，要求设备重新上传某个时间范围内的所有签到记录。

该指令属于售后服务指令，仅用于签到数据上报异常时恢复使用。

请求示例

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

其中cmd固定为checkin_upload表示签到数据主动上报指令，请求payload各参数说明如下:

参数 类型 描述
days 整型 表示上传最近多少天的签到记录，包括当天。例如如果当天是2018/8/27日，days设置为2，则上传2018/8/26-2018/8/27两天的签到记录。

响应示例

设备收到该请求后直接通过各设备对应业务场景下的签到数据上报指令上报指定日期范围的记录。为了提高上传的成功率，建议每次上传的签到记录数不超过50条。

其中考勤对应的签到数据指令请点击这里，门禁对应的签到数据指令请点击这里。

考勤专用协议

考勤协议用于描述如何通过与考勤设备通信完成企业员工打卡。其核心工作流程和指令如下:

人员->应用: 人员特征采集
应用--应用: 考勤规则设置
应用->设备: 设备人员同步
Note left of 设备: 增量同步直到完成
人员--设备: 员工签到
设备->应用: 签到记录上报

打卡记录上报

员工通过考勤设备打卡成功后，设备需将打卡数据实时上报给考勤应用软件用于员工考勤计算。考勤打卡数据是业务关键数据，如果应用端未确认收到，设备不可丢弃。

由于员工上下班时间相对比较集中，为了降低上传频率，设备可定时批量提交考勤打卡记录（例如5s一次）。

请求示例

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

其中cmd固定为checkin表示打卡记录上报指令，请求payload可一次包含多个打卡记录数据，数据的参数说明如下：

参数 类型 描述
user_id 字符串 打卡人员ID
check_type 字符串 打卡方式
check_time 整型 打卡时间（精确到秒）

响应示例

应用端在收到请求后，应在同一消息上下文实时向设备回复确认。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "checkin"
    }
}

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

门禁专用协议

门禁协议用于描述如何通过与门禁设备通信实现企业员工及访客安全通行管理。其核心工作流程和指令如下:

人员->应用: 人员特征采集
设备->应用: 门禁配置查询
设备->应用: 通行规则查询
设备->应用: 设备人员同步
Note left of 设备: 增量同步直到完成
人员--设备: 通行验证
设备--设备: 本地通行规则验证并开门 
设备->应用: 门禁数据上报

门禁配置更新事件

门禁系统会围绕“门”进行门禁控制，当应用系统对门禁设备和门的关系进行配置更新时，会通过本指令向设备发送更新通知事件。

设备收到事件消息后，应主动触发门禁配置查询向应用查询最新的门禁配置并更新到本地。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_config_updated"
    }
}

其中cmd固定为door_config_updated表示门禁配置更新事件指令。

响应示例

设备收到请求后在一个消息上下文返回应用确认消息。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_config_updated"
    }
}
如果因为某些原因应用并未及时收到设备的确认消息，则应用应主动定时重发事件通知，直到收到设备确认为止。

门禁配置查询

设备通过本指令可查询和设备关联的门的所有配置信息。

为了确保设备始终与应用端保持信息一致，建议设备在每次上线初始化完成后，第一时间通过本指令同步最新的数据。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_config_query"
    }
}

其中cmd固定为door_config_query表示门禁配置查询指令。

响应示例

应用收到请求后，需要在一个消息上下文返回和设备关联的门的所有配置信息。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_config_query",
        "payload": {
            "doors": [
                {
                    "door_id": "d100",
                    "door_name": "公司大门",
                    "reader_no": 1,
                    "locker_no": 1,
                    "locked": false
                }
            ]
        }
    }
}

响应payload通过doors一次返回和设备关联的所有门的配置信息。每个门的配置信息说明如下:

参数 类型 描述
door_id 字符串 和设备关联的门ID
door_name 字符串 门的名称
reader_no 整型 和门关联的读头编号
locker_no 整型 和门关联的电锁编号
locked Boolean 已废弃字段，门禁锁定状态应已设备为准。是否门禁已锁定，true表示已锁定，缺省是false；

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

通用通行规则更新事件

门禁设备通过通行规则来判断人员的通行权限。当应用端更新了与设备关联的门的通行规则时，应用会主动通过本指令向设备发送规则更新事件。

设备收到事件消息后，应主动通过通用通行规则查询指令查询最新的规则配置信息。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_access_rules_updated",
        "payload": {
            "door_id": "d001"
        }
    }
}

其中cmd固定为door_access_rules_updated表示门禁通行规则更新事件指令。

响应示例

设备收到请求后在一个消息上下文返回应用确认消息。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_access_rules_updated"
    }
}
如果因为某些原因应用并未及时收到设备的确认消息，则应用应主动定时重发事件通知，直到收到设备确认为止。

通用通行规则查询

设备通过本指令可以主动向应用查询与设备关联门的通用通行规则配置信息。对于分体式门禁机，如果设备关联多个门，可通过多次查询完成规则更新。

为了确保设备始终与应用端保持信息一致，建议设备在每次上线初始化完成后，第一时间通过本指令同步最新的数据。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_access_rules_query",
        "payload": {
            "door_id": "d001"
        }
    }
}

其中cmd固定为door_access_rules_query表示门通用通行规则查询指令，请求payload参数说明如下:

参数 类型 描述
door_id 字符串 查询规则的门ID

响应示例

应用收到请求后，应在同一上下文中返回跟请求门相关的所有通用通行规则信息列表。

{
    "mid": "123456",
    "from": "应用ID",
    "to": "设备ID",
    "time": 1502867086,
    "action": 500,
    "data": {
        "cmd": "door_access_rules_query",
        "payload": {
            "door_id": "d001",
            "access_rules": [{
                "rule_id": "123456789",
                "priority": 0,
                "users": ["123", "124"],
                "weekday_rules": [{
                    "weekdays": [1, 2, 3, 4, 5],
                    "times": [{
                        "time_begin": "08:00",
                        "time_end": "21:00",
                        "access_types": ["fa", "fp"]
                    }]
                }, {
                    "weekdays": [0, 6],     // [周日, 周六]
                    "times": [{
                        "time_begin": "08:00",
                        "time_end": "18:00",
                        "access_types": ["fa", "fp"]
                    }]
                }],
                "day_rules": [{
                    "day_begin": "20200501",
                    "day_end": "20200504",
                    "times": [{
                        "time_begin": "08:00",
                        "time_end": "18:00",
                        "access_types": ["fa+card"]
                    }]
                }]
            }, {}]
        }
    }
}

响应payload包括door_id和access_rules。其中，access_rules一次返回和指定门相关的所有通用通行规则配置信息。每个通用通行规则信息参数说明如下:

参数 类型 描述
rule_id 字符串 规则ID
priority 整型 规则优先级，缺省为0，数字越大优先级越高。当同一个人满足该门上的多个规则时，优先查找优先级最高的规则进行验证，验证失败则不能通行。如果存在多个最高优先级一样的规则，则只要满足其中任一规则即可
users JSON数组 规则关联的可通行该门的人员ID列表
weekday_rules JSON数组 按照一星期为周期批量设置的可通行时间及验证方式。
weekdays: JSON数组格式，表示一星期范围， 0代表星期日，1-6分别代表星期一到星期六 ；
times: 多个通行时段及每个时段的验证方式；其中，time_begin和time_end分别表示通行开始和结束时间，格式HH:mm；access_types表示可通行的验证方式列表，例如pass密码，fp指纹，fa人脸, app_scan扫码, fa+card表示人脸+刷卡等等；
day_rules JSON数组 按照日期范围批量设置可通行方式，优先级较weekday_rules更高。
day_begin: 字符串，日期固定格式yyyyMMdd，表示开始日期；
day_end: 字符串，日期固定格式yyyyMMdd，表示截止日期（包含）；times说明与weekday_rules一致

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

门禁记录上报

门禁记录是指一个人在通过门禁设备进行通行验证时产生的通行记录。不论是否通行成功设备都应该通过本指令实时上报记录给门禁应用软件。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_checkin", 
        "payload": {
            "users": [
                {
                    "user_id": "121", 
                    "check_type": "fp", 
                    "check_time": 1503025335,
                    "door_id": "d001",
                    "result": 0,
                    "extra_info": {
                        "temperature": "36.5",
                        "temperature_status": 0,
                        "mask_status": 0
                    }
                }, 
                {
                    "check_type": "fa", 
                    "check_time": 1503028318,
                    "door_id": "d001",
                    "result": 2,
                    "error_msg": "101",
                    "capture_img": "base64图像"
                }
            ]
        }
    }
}

其中cmd固定为door_checkin表示门禁记录上报指令，请求payload通过users一次返回多个门禁通行记录数据，每个门禁记录参数说明如下:

参数 类型 描述
user_id 字符串 通行人员的ID。如果未能识别，则设置为空
check_type 字符串 通行验证方式
check_time 整型 通行时间（精确到秒）
door_id 字符串 通行的门的ID
result 整型 通行结果。
0: 通行成功；
1: 无通行权限，开门拒绝；
2: 未识别的陌生人；
3: 无效的通行凭证；
4: 活体检测失败，开门拒绝；
7: 异常通行，例如强行破门；
8: 门禁已锁定，无法控制；
9: 设备系统异常，开门失败；
error_msg 字符串 可选，在通行失败时返回的设备自定义错误代码或描述
capture_img 字符串 可选，抓拍图像，通过base64编码
extra_info JSON 可选，其他采集信息，根据设备硬件支持可选择上报。包括：
temperature: 体温（°C）；
temperature_status: 体温是否异常。0-正常，1-异常，2-未知；
mask_status: 是否佩戴口罩。0-未佩戴，1-已佩戴，2-未知；

响应示例

应用端在收到请求后，应在同一消息上下文实时向设备回复确认。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_checkin"
    }
}

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

门禁状态更新

当门禁设备发现控制的门的状态发生变化时，应通过本指令向应用上报所有发生状态切换的门的实时状态数据，确保两端状态一致。

为了避免频繁上报无效信息，对于像正常门禁通行导致门的状态短暂发生变化的场景，门禁设备要自动识别并进行过滤。

请求示例

{
    "mid": "123456",
    "from": "设备ID",
    "to": "应用ID",
    "time": 1502867086,
    "action": 300,
    "data": {
        "cmd": "door_status_update",
        "payload": {
            "doors": [{
                "door_id": "d001",
                "status": 0,
                "locked": false,
                "open_stay": true
            }]
        }
    }
}

其中cmd固定为door_status_update门禁状态更新指令，请求payload可一次包含多个门的状态变更，状态变更参数说明如下:

参数 类型 描述
door_id 字符串 门ID
status 整型 门的开关状态。
0: 关闭状态；
1: 打开状态；
2: 未知状态。当门禁设备未安装门磁，导致无法感应到门的开关状态时返回；
locked Boolean 是否门禁已锁定，true表示是，false表示否；
open_stay Boolean 是否处于常开状态，true表示是，false表示否；

响应示例

应用收到请求后，应在同一消息上下文向设备返回确认。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_status_update"
    }
}

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

注意，如果设备网络断开连接了，再次恢复在线时，为了避免状态不一致，必须第一时间上报门禁设备关联的所有门的状态数据。

远程开门

应用支持管理员通过本指令远程控制门禁设备打开指定的门，以应对某些特殊进入场景。

远程开门指令支持两种模式，一种是直接开门的紧急模式，另外一种则需要通行人员在设备端再次做授权认证的授权模式。授权模式的安全级别更高，但需要设备端硬件支持。

授权模式相对较复杂，操作流程示意如下:

管理员->应用: 发起远程开门请求
应用--应用: 验证身份并生成授权码
应用->设备: 发送远程授权指令
应用--用户: 告知授权码信息
Note left of 用户:系统通知或其他方式
用户->设备: 输入授权码 
设备--设备: 验证授权信息并开门
设备->应用: 门禁数据上报

设备一旦进入授权模式且用户输入完成后，设备应比对用户输入与应用请求的access_code是否一致，如果完全一致且没有过期则视为验证通过，自动开门通行，否则应返回对应的错误。

为了安全起见，每个授权码只能用一次且存在过期时间。另外，为了避免暴力破解，设备在用户重试一定次数后应自动视为失败，并退出远程授权模式。

另外，不论最终通行是否成功，设备均应通过门禁记录上报指令向应用上报本次门禁通行记录。其中，通行人员应标记为授权管理人员，通行方式固定为remote。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_open", 
        "payload": {
            "admin_id" : "100",
            "door_id": "d001",
            "access_code" : "授权码加密字符串",
            "expire_time": 1502867086
        }
    }
}
其中cmd固定为door_open表示远程开门指令，payload各参数说明如下:

参数 类型 描述
admin_id 字符串 发起远程控制的管理人员ID
door_id 字符串 目标门ID
access_code 字符串 授权模式专用，表示开门授权码的加密字符串，加密规则是: md5("设备ID"+"@"+"原始授权码")
expire_time 整型 授权模式专用，表示授权码过期时间，精确到秒

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认，并上报门禁控制结果。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_open", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 开门结果。
0: 开门成功；
1: 授权验证失败（授权模式专用）；
2: 授权已过期（授权模式专用）；
3: 设备不支持（授权模式专用）；
8: 门禁已锁定，无法控制；
9: 设备系统异常，开门失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

远程常开

应用支持管理员通过本指令远程控制门禁设备将指定门设置为常开。与远程开门不同，常开模式下除非通过远程关门指令关闭，否则门是不会自动关闭的。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_open_stay", 
        "payload": {
            "admin_id" : "100",
            "door_id": "d001",
            "close_time": 1582185984
        }
    }
}
其中cmd固定为door_open_stay表示远程常开指令，payload各参数说明如下:

参数 类型 描述
admin_id 字符串 发起远程控制的管理人员ID
door_id 字符串 目标门ID
close_time 整型 可选，设备自动退出常开模式的时间点，精确到秒

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认，并上报门禁控制结果。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_open_stay", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 常开结果。
0: 开门成功；
1: 设备不支持；
8: 门禁已锁定，无法控制；
9: 设备系统异常，开门失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

远程关门

应用支持管理员通过本指令远程控制门禁设备关闭处于常开模式的门。如果门不处于常开模式，设备不需要执行任何控制操作。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_close", 
        "payload": {
            "admin_id" : "100",
            "door_id": "d001"
        }
    }
}
其中cmd固定为door_close表示远程关门指令，payload各参数说明如下:

参数 类型 描述
admin_id 字符串 发起远程控制的管理人员ID
door_id 字符串 目标门ID

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认，并上报门禁控制结果。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_close", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 关门结果。
0: 关门成功；
1: 设备不支持；
8: 门禁已锁定，无法控制；
9: 设备系统异常，关门失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

APP扫码开门

通过本指令可以支持通过APP扫描设备二维码的方式完成开门，适用于自带屏幕的门禁设备。

设备APP开门的二维码的内容格式如下：

https://delicloud.com/d/{设备ID}/appcall?access_code={设备授权码}&door={门ID}。

其中，设备ID是门禁设备的唯一标示，access_code是设备按照一定的算法随机生成的6位数字授权码，door是目标门的唯一标示。

为了保证安全，设备生成的二维码信息应该定时刷新，建议60s刷新一次。

APP扫码成功后，会解析二维码信息并请求门禁应用开启目标门，应用校验该人员身份合法性后，向设备发起APP扫码开门请求指令。

操作流程示意如下:

设备--设备: 生成通行二维码
用户->设备: 通过APP扫码，获取设备授权码
用户->应用: 通过APP请求开门
Note left of 应用: 携带门ID和设备授权码
应用--应用: 校验用户身份
应用->设备: 发送扫码开门指令
设备--设备: 授权验证并开门 
设备->应用: 门禁数据上报

设备收到请求后，应首先比对当前有效的本地授权码与应用请求access_code是否一致。如果不一致则视为请求已过期，如果一致则继续校验本地通行规则，返回校验结果。

不论通行是否成功，设备均应通过门禁记录上报指令向应用上报本次门禁通行记录。其中，通行人员应标记为扫码人员，通行方式固定为app_scan。

注意，为了避免因为网络延迟原因导致在刷新期间设备验证刷新前的授权码失败，设备应保证刷新后短时间内（例如15s）之前的授权码仍然有效。

请求示例

{
    "mid": "消息ID", 
    "from": "应用ID", 
    "to": "设备ID", 
    "action": 500,
    "time": 1503025335, 
    "data": {
        "cmd": "door_app_scan",
        "payload": {
            "user_id": "112",
            "door_id": "d001",
            "access_code" : "加密后的授权码"
        }
    }
}
其中cmd固定为door_app_scan表示APP扫码开门，payload各参数说明如下:

参数 类型 描述
user_id 整型 APP扫码开门的人员ID
door_id 字符串 扫码开启的门ID
access_code 字符串 授权码加密字符串。加密规则是: md5("设备ID"+"@"+"原始授权码") 。

响应示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "门禁应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_app_scan", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 扫码开门结果。
0: 开门成功；
1: 授权码已过期；
2: 无通行权限；
8: 门禁已锁定，无法控制；
9: 设备系统异常，开门失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

设备扫码开门

通过本指令设备可以通过扫描APP生成的二维码完成开门（主要用于访客临时电子凭证场景），适合于自带扫描二维码功能的门禁机。

APP生成的临时电子凭证二维码内容格式如下：

https://delicloud.com/auth_code?user_id={人员ID}&expire={过期时间}&sign={验证签名}

其中，user_id是同步到设备的人员ID标识，expire是指该电子凭证的过期时间(秒),sign是用于验证该电子凭证有效性的签名。sign的计算公式如下：

sign = MD5({user_id} + '-' + {expire} + '-' + {auth_code})

auth_code是设备人员同步中从应用同步到设备的人员授权码信息，一般只有0-1个授权码信息，如果有多个取第一个进行签名验证。

一个临时访客通行门禁的操作流程示意如下：

用户->应用: 登记访客，并生成访客授权码
应用->设备: 下发访客授权码
用户->应用: 获取临时二维码凭证
设备->用户: 扫描凭证
设备--设备: 识别并验证凭证
设备->应用: 门禁数据上报

设备在识别到符合规则的二维码凭证之后，需要按照如下几步验证人员身份：

  1. 检查user_id是否存在，如果不存在则视为陌生人（2）；
  2. 检查expire时间戳，如果已经超过当前时间，则视为无效的通行凭证（3）；注意，如果expire为-1，则视为永久有效，不做时间校验；
  3. 通过user_id找到该人员的授权码信息，并通过计算比较sign确认签名是否正确；如果未找到人员的授权码信息或签名不正确，则视为无效的通行凭证（3）；

不论通行是否成功，设备均应通过门禁记录上报指令向应用上报本次门禁通行记录。其中，通行人员ID应标记为电子凭证中的user_id，通行方式固定为device_scan。

远程锁定

应用支持管理员通过本指令远程控制门禁设备锁定对门的门禁控制。门一旦被锁定，除了解锁命令，设备将停止响应指定门的所有通行控制请求，包括常规的人员通行验证和远程开关门命令。

门被锁定之后，可通过远程解锁指令进行锁定解除。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_lock", 
        "payload": {
            "admin_id" : "100",
            "door_id": "d001"
        }
    }
}
其中cmd固定为door_lock表示远程锁定指令，payload各参数说明如下:

参数 类型 描述
admin_id 字符串 发起锁定的管理人员ID
door_id 字符串 目标门ID

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认，并上报门禁控制结果。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_lock", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 锁定结果。
0: 锁定成功；
9: 设备系统异常，锁定失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

远程解锁

应用支持管理员通过本指令远程控制门禁设备解除对门的锁定状态。解除锁定之后，所有针对门的通行规则和远程控制命令都可以正常使用。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "door_unlock", 
        "payload": {
            "admin_id" : "100",
            "door_id": "d001"
        }
    }
}
其中cmd固定为door_unlock表示远程解锁指令，payload各参数说明如下:

参数 类型 描述
admin_id 字符串 发起解锁的管理人员ID
door_id 字符串 目标门ID

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认，并上报门禁控制结果。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "door_unlock", 
        "payload": {
            "code": 0,
            "error_msg": ""
        }
    }
}

响应payload各参数说明如下:

参数 类型 描述
code 整型 解锁结果。
0: 解锁成功；
9: 设备系统异常，解锁失败；
error_msg 字符串 可选，响应失败时返回的设备自定义错误代码或描述

访客专用协议

访客协议用于描述如何通过与访客机设备通信完成企业外部访客预约签到、临时拜访登记以及访客签离等操作。

访客配置更新事件

当访客设备需要配置信息发生变化时，应用应通过本指令向设备发送通知事件。

设备在收到访客配置更新事件消息后，应主动调用访客配置查询指令进行同步更新。

请求示例

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "visitor_config_updated"
    }
}

其中cmd固定为visitor_config_updated表示访客配置更新事件指令。

响应示例

设备收到请求后，应在同一消息上下文向应用返回确认。

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "visitor_config_updated"
    }
}

如果因为某些原因应用并未及时收到设备的确认消息，则应用应主动定时重发事件通知，直到收到设备确认为止。

访客配置查询

设备通过本指令可以主动向应用查询访客配置信息。

为了确保设备始终与应用端保持信息一致，建议访客设备在每次上线初始化完成后，第一时间通过本指令同步最新的数据。

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "visitor_config_query"
    }
}

其中cmd固定为visitor_config_query表示访客配置查询指令。

响应示例

应用收到请求后，应在同一上下文中返回访客设备使用的配置信息。

{
    "mid": "123456",
    "from": "应用ID",
    "to": "设备ID",
    "time": 1502867086,
    "action": 500,
    "data": {
        "cmd": "visitor_config_query",
        "payload": {
            "booking_url": "https://visitor.delicloud.com?org_id=123456&org_name=得力集团&visit_place=大门口",
            "org_info": {
              "id": "123456",
              "name": "得力集团"
            },
            "visit_place": "大门口"
        }
    }
}

payload 的字段说明:

参数 类型 描述
booking_url 字符串 访客预约页面的访问url
org_info json对象 访客机所属的组织信息
id 字符串 组织的id
name 字符串 组织的名称
visit_place 字符串 签到地点

如果设备在等待一段时间后（例如1分钟）未收到响应，则应主动再次发起请求，直到收到响应结果为止。

访客预约签到

访客提前预约成功后，来访时通过访客机设备完成识别签到验证，验证通过后通过本指令上报访客签到信息。

一个人脸访客机的预约签到流程示意如下:

participant 访客 as visitor
participant 访客机 as device

participant 访客系统 as system
participant 访客管理员 as admin

visitor->system: 提交来访预约单
note right of visitor: 携带访客人脸照片信息
admin->system: 审批预约单
system->device: 访客信息同步到设备
visitor->device: 来访验证(人脸识别)
device->device: 识别访客
device->system: 访客预约签到上报
device->visitor: 验证通过，欢迎访客通行

请求示例

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "visitor_checkin", 
        "payload": {
            "user_id": "1121", 
            "check_type": "fa", 
            "check_time": 1503025335
        }
    }
}

其中cmd固定为visitor_checkin表示访客预约签到指令，签到数据的参数说明如下：

参数 类型 描述
user_id 字符串 访客人员ID
check_type 字符串 签到方式
check_time 整型 签到时间（精确到秒）

响应示例

应用端在收到请求后，应在同一消息上下文实时向设备回复确认消息。如果设备在一段时间内（例如60s）未收到确认响应，则应重发该消息直到收到响应为止。

{
    "mid": "123456", 
    "from": "应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "visitor_checkin"
    }
}

设备参数

设备参数包括产品固有特性和设备可配置参数两个类别。分别说明如下：

同一产品型号的所有设备拥有相同的固有特性和可配置参数列表，不同的产品型号可以因设备本身支持的业务范围或硬件形态不同支持不同的参数集合。每台设备用户可根据业务需要通过终端设置不同的可配置参数值。

产品固有特性

产品固有特性由于其不变性，设备一般会固化在硬件固件中，不需要通过协议查询。

适用范围 参数名 参数说明 参数值说明 缺省值
通用 admin_limit
设备管理员数量上限
 整型 10
通用 user_capacity 设备用户容量 整型 无
通用 check_type 设备支持的所有签到方式 字符串。如果支持多种签到方式，则用逗号分隔。例如fa,fp表示设备支持人脸和指纹两种签到方式。
所有设备端支持的签到方式如下：
fa: 人脸；
fp: 指纹；
pass: 密码；
identity: 身份证；
card: 员工卡；
auth_code: 授权码；

如果某个设备需要支持组合签到，则通过加号表示，例如人脸和刷卡组合的签到方式应表示为fa+card；		 无
所有 device_usage 设备支持的所有用途 字符串。如果支持多个功能用途，则用逗号分隔，例如：checkin,access。所有设备支持的用途如下：
feature_collect: 特征采集；
checkin: 考勤；
access: 门禁；
visitor: 访客；		 无
所有支持人脸识别的设备型号 fa_alg 设备端支持的人脸特征采集算法 字符串。例如base64，表示设备支持原始图像base64字符串的人脸特征数据。相同人脸特征算法标示的设备之间人脸特征数据可以互相通用 base64
所有支持人脸识别的设备型号 fa_capacity 设备人脸容量 整型 0
所有支持人脸识别的设备型号 fa_max 单用户最大人脸数 整型 1
所有支持指纹识别的设备型号 fp_alg 设备端支持的指纹特征采集算法 字符串。例如base64，表示设备支持原始图像base64字符串的人脸特征数据。相同人脸特征算法标示的设备之间人脸特征数据可以互相通用 base64
所有支持指纹识别的设备型号 fp_capacity 设备指纹容量 整型 0
所有支持指纹识别的设备型号 fp_max 单用户最大指纹数 整型 3
所有支持刷卡的设备型号 card_capacity 设备卡容量 整型 无
所有支持刷卡的设备型号 card_max 单用户最大卡数 整型 无

设备可配置参数

设备可配置参数除了下发到设备端的参数名和参数值之外，还包括有参数值的元数据定义。应用通过参数的元数据定义来确定设备支持的可配置参数以及参数值的范围。

为了以示区分，当通过得力E+平台指令向应用同步可配置参数时，参数的元数据定义的属性键（code）名称是在设备参数名的末尾增加_config命名。例如可配置参数check_type通过E+指令同步该参数的元数据定义时，其属性名定义为check_type_config。

设备可配置参数可通过设备参数相关的协议指令进行更新查询。

适用范围 参数名 参数说明 参数值说明 元数据示例
通用 check_type
设备支持的签到方式
 列表选项 [{"value":"fa","text":"人脸"},{"value":"fp","text":"指纹"},{"value":"fa/fp","text":"人脸或指纹","default":true}]。

与产品固有特性参数check_type定义相同，但可配置的值范围应是产品支持的所有签到方式的子集。
通用 checkin_interval 有效的签到间隔时间 列表选项 [{"value":"0","text":"未设置"},{"value":"1","text":"1分钟","default":true},{"value":"3","text":"30分钟"},{"value":"4","text":"60分钟"}]
通用 adminPassword 管理员密码 字符串 {"type":"string","max":20,"tips":"包含数字/大写字母/小写字母/中下划线/两种及两种以上，长度限制为8-12位","regex":"^(?![0-9]+$)(?![a-z]+$)(?![A-Z]+$)(?![-]+$)[0-9a-zA-Z-]{8,12}$","default":"admin123"}
通用 volume 设备音量 列表选项、整型 [{"value":"1","text":"无"},{"value":"2","text":"低"},{"value":"3","text":"中","default":true},{"value":"4","text":"高"}]、{"type":"number","min":0,"max":100,"default":100,"tips":"请选择0-100之间的整数"}
通用 adModeTime 进入广告模式时间 列表选项、整型 [{"value":"0","text":"关闭"},{"value":"10","text":"10秒","default":true},{"value":"30","text":"30秒"},{"value":"60","text":"60秒"},{"value":"150","text":"150秒"},{"value":"300","text":"300秒"}]、{"type":"number","min":10,"max":3600,"default":10,"tips":"请选择10-3600之间的整数"}
通用 adModeType 默认图片/自定义图片 列表选项 [{"value":"0","text":"默认图片","default":true},{"value":"1","text":"自定义图片"}]
通用 adModeMedia 广告模式媒体文件 字符串数组 无
通用 restScreenModeSwitch 息屏模式 列表选项 [{"value":"0","text":"不开启","default":true},{"value":"1","text":"开启"}]
考勤机 ring_rule 响铃规则 JSON格式字符串。可支持多组响铃设置，每组都有对应的响铃时间、时长以及响铃周期（按周天）。示例如下:
[{"index":0,"time":"08:00","duration":30,"days":"1,2,3,4,5"},{"index":1,"time":"10:00","duration":30,"days":"0,6"}]。其中：
index: 响铃分组ID。默认从0开始；
time: 响铃时间点，默认格式是HH:mm，精确到分；
duration: 响铃时长，单位是秒；
days: 响铃周期，以周天为单位。可选择一周内的任意N天，以逗号分隔，星期天到星期六从0开始6结尾；		 无
门禁机 faceScore 人脸识别阈值 列表选项 [{"value":"85", "text":"精准"},{"value":"80", "text":"常规", "default":true},{"value":"70", "text":"极速"}]
门禁机 faceDetectionType 人脸检测类型 列表选项 [{"value":"1","text":"多人识别"},{"value":"2","text":"单人识别","default":true}]
门禁机 comRecRank 识别登记级别 列表选项 [{"value":"1", "text":"非活体"},{"value":"2", "text":"活体", "default":true}]
门禁机 comRecDistModeType 识别距离 列表选项 [{"value":"1","text":"无限制"},{"value":"2","text":"0.5以内"},{"value":"3","text":"1米以内","default":true},{"value":"4","text":"1.5米以内"}]
门禁机 recSucComModeType 串口输出类型 列表选项 [{"value":"1","text":"开门","default":true},{"value":"2","text":"不输出"},{"value":"3","text":"输出phone"},{"value":"4","text":"输出cardNo"},{"value":"100","text":"自定义"}]
门禁机 recSucComModeContent 串口输出自定义内容 字符串 {"type":"string","max":100,"tips":"100字以内，格式不限"}
门禁机 recSucWiegandType 韦根输出类型 列表选项 [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}]
门禁机 recSucWiegandContent 韦根输出内容 字符串 {"type":"string","max":255, "tips":"允许{phone}、{cardNo}。其他内容只允许数字、英文和英文字符"}
门禁机 recSucRelayType 继电器输出类型 列表选项 [{"value":"1","text":"输出", "default":true},{"value":"2","text":"不输出"}]
门禁机 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 语音播报类型 列表选项 [{"value":"1","text":"播报名字","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}]
门禁机 recSucTtsModeContent 语音播报自定义内容 字符串。仅当recSucTtsModeType设置为自定义时有效 {"type":"string","max":255, "tips":"允许{name}、{tag}。字段格式固定，其他内容只允许数字、英文和汉字，长度限制255个字符"}
门禁机 recSucDisplayText1Type 人员称呼显示文字 列表选项 [{"value":"1","text":"名字","default":true},{"value":"100","text":"自定义"}]
门禁机 recSucDisplayText1Content 人员称呼自定义文字内容 字符串。仅当recSucDisplayText1Type设置为自定义时有效 {"type":"string","max":4, "tips":"最多4个字，格式不限"}
门禁机 recSucDisplayText2Type 识别状态栏显示文字 列表选项 [{"value":"1","text":"识别成功","default":true},{"value":"100","text":"自定义"}]
门禁机 recSucDisplayText2Content 识别状态栏自定义文字内容 字符串。仅当recSucDisplayText2Type设置为自定义时有效 {"type":"string","max":8, "tips":"最多8个字，格式不限"}
门禁机 recFailEnable 识别失败开关 列表选项 [{"value":"1","text":"打开","default":true},{"value":"2","text":"关闭"}]
门禁机 recFailTimesThreshold 识别失败判定陌生人次数 整型 {"type":"number","min":1,"max":20,"default":3,"tips":"请选择1-20之间的整数，1表示快速判定但精确率最低，随着数值增加，判定时间增加，精确度提高"}
门禁机 recFailTtsModeType 语音播报类型 列表选项 [{"value":"1","text":"识别失败","default":true},{"value":"2","text":"不播报"},{"value":"100","text":"自定义"}]
门禁机 recFailTtsModeContent 语音播报自定义内容 字符串。仅当recFailTtsModeType设置为自定义时有效 {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"}
门禁机 recFailDisplayTextType 识别状态栏文字类型 列表选项 [{"value":"1","text":"识别失败","default":true},{"value":"100","text":"自定义"}]
门禁机 recFailDisplayTextContent 识别状态栏自定义文字内容 字符串。仅当recFailDisplayTextType设置为自定义时有效 {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"}
门禁机 recFailComModeType 串口输出类型 列表选项 {"value":"1","text":"开门"},{"value":"2","text":"不输出","default":true},{"value":"100","text":"自定义"}]
门禁机 recFailComModeContent 串口输出自定义内容 字符串。仅当recFailComModeType设置为自定义时有效 {"type":"string","max":100, "tips":"100字以内，格式不限"}
门禁机 recFailWiegandType 韦根输出类型 列表选项 [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}]
门禁机 recFailWiegandContent 韦根输出自定义内容 字符串 {"type":"string","max":255, "tips":"只允许数字、英文和英文字符，长度限制255个字符"}
门禁机 recFailRelayType 继电器输出类型 列表选项 [{"value":"1","text":"输出"},{"value":"2","text":"不输出","default":true}]
门禁机 recNoPerTtsModeType 语音播报类型 列表选项 [{"value":"1","text":"播报姓名权限不足","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}]
门禁机 recNoPerTtsModeContent 语音播报自定义内容 字符串。仅当recNoPerTtsModeType设置为自定义时有效 {"type":"string","max":255, "tips":"允许{name}、{tag}。字段格式固定，其他内容只允许数字、英文和汉字，长度限制255个字符"}
门禁机 recNoPerDisplayText1Type 人员称呼文字类型 列表选项 [{"value":"1","text":"名字","default":true},{"value":"100","text":"自定义"}]
门禁机 recNoPerDisplayText1Content 人员称呼自定义文字内容 字符串。仅当recNoPerDisplayText1Type设置为自定义时有效 {"type":"string","max":4, "tips":"最多4个字，格式不限"}
门禁机 recNoPerDisplayText2Type 识别状态栏文字类型 列表选项 [{"value":"1","text":"权限不足","default":true},{"value":"100","text":"自定义"}]
门禁机 recNoPerDisplayText2Content 识别状态栏自定义文字内容 字符串。仅当recNoPerDisplayText2Type设置为自定义时有效 {"type":"string","max":8, "tips":"最多8个字，格式不限"}
门禁机 recNoPerComModeType 串口输出类型 列表选项 [{"value":"1","text":"开门","default":true},{"value":"2","text":"不输出"},{"value":"3","text":"输出phone"},{"value":"4","text":"输出cardNo"},{"value":"100","text":"自定义"}]
门禁机 recNoPerComModeContent 串口输出自定义内容 字符串。仅当recNoPerComModeType设置为自定义时有效 {"type":"string","max":100, "tips":"100字以内，格式不限"}
门禁机 recNoPerWiegandType 韦根输出类型 列表选项 [{"value":"1","text":"不输出","default":true},{"value":"2","text":"韦根26"},{"value":"3","text":"韦根34"}]
门禁机 recNoPerWiegandContent 韦根输出自定义内容 字符串 {"type":"string","max":255, "tips":"只允许数字、英文和英文字符，长度限制255个字符"}
门禁机 recNoPerRelayType 继电器输出类型 列表选项 [{"value":"1","text":"输出"},{"value":"2","text":"不输出","default":true}]
门禁机 scrDisplayText1Type 屏幕左下角固定文字区域文字类型 列表选项 [{"value":"1","text":"不显示","default":true},{"value":"2","text":"组织名称"},{"value":"100","text":"自定义"}]
门禁机 scrDisplayText1Content 屏幕左下角固定文字区域自定义内容 字符串。仅当scrDisplayText1Type设置为自定义时有效 {"type":"string","max":255,"tips":"255字以内，格式不限"}
门禁机 scrDisplayText2Type 屏幕右下角固定文字区域文字类型 列表选项 [{"value":"1","text":"不显示","default":true},{"value":"2","text":"设备名称"},{"value":"100","text":"自定义"}]
门禁机 scrDisplayText2Content 屏幕右下角固定文字区域自定义内容 字符串。仅当scrDisplayText2Type设置为自定义时有效 {"type":"string","max":255,"tips":"255字以内，格式不限"}
门禁机 captureImgEnabled 门禁通行时是否开启抓拍图像 列表选项。仅当设备支持人脸识别时有效，默认不开启 [{"value":"0","text":"不开启", "default":true},{"value":"1","text":"开启"}]
门禁机 tempDetectEnabled 是否开启体温检测功能 列表选项。仅当设备安装了体温检测模块时有效，默认不开启 [{"value":"0","text":"不开启", "default":true},{"value":"1","text":"开启"}]
门禁机 tempAbnormalThreshold 体温异常度数设置（℃） 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数"}
门禁机 recTempTtsModeType 体温异常语音播报 列表选项。 [{"value":"1","text":"播报体温异常及温度","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}]
门禁机 recTempTtsModeContent 体温异常语音播报自定义内容 字符串。仅当recTempTtsModeType设置为自定义时有效 {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"}
门禁机 tempDetectPosition 测温位置 列表选项 [{"value":"1","text":"额头","default":true},{"value":"2","text":"手腕"}]
门禁机 tempAbnormalPassEnabled 体温异常是否允许通行 列表选项 {"value":"1","text":"允许"},{"value":"2","text":"不允许","default":true}]
门禁机 tempEffectDetectMin 有效温度最低值（℃） 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数，默认30"}
门禁机 tempEffectDetectMax 有效温度最高值（℃） 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数，默认43"}
门禁机 tempDetectDistance 测温距离（mm） 字符串 {"type":"number","min":0,"max":100,"default":100,"tips":"请选择0-100之间的整数"}
门禁机 tempDetectOverlapRate 人脸与测温区域重叠率 列表选项 {"type":"number","min":0,"max":100,"default":70,"tips":"请选择0-100之间的整数, 0表示关闭该功能"}
门禁机 lowTempCompensationEnabled 低温补偿 列表选项 [{"value":"0","text":"不开启", "default":true},{"value":"1","text":"开启"}]
门禁机 highTempCompensationEnabled 高温补偿 列表选项 [{"value":"0","text":"不开启", "default":true},{"value":"1","text":"开启"}]
门禁机 tempMappingSourceMin 温度映射源最低值 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数"}
门禁机 tempMappingSourceMax 温度映射源最高值 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数"}
门禁机 tempMappingTargetMin 温度映射目标最低值 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数"}
门禁机 tempMappingTargetMax 温度映射目标最高值 字符串 {"type":"decimal","precision":3,"scale":1,"tips":"最多1位小数的浮点数"}
门禁机 maskDetectEnabled 是否开启口罩检测功能 列表选项 [{"value":"0","text":"不开启", "default":true},{"value":"1","text":"开启"}]
门禁机 recUnmaskTtsModeType 未佩戴口罩语音播报模式 列表选项 [{"value":"1","text":"播报未佩戴口罩","default":true},{"value":"2","text":"不播放"},{"value":"100","text":"自定义"}]
门禁机 recUnmaskTtsModeContent 未佩戴口罩语音播报自定义内容 字符串。仅当recUnmaskTtsModeType设置为自定义时有效 {"type":"string","max":255, "tips":"内容只允许数字、中英文和中英文符号，长度限制255个字符"}
门禁机 recUnmaskAction 检测到未佩戴口罩时 列表选项 [{"value":"1","text":"停止测温", "default":true},{"value":"2","text":"提示佩戴口罩并继续测温"}]