云门禁接入协议

文档目标

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

适用范围

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

接口设计

通信方式

参考设备标准接入协议,门禁机设备固件程序采用MQTT协议与设备网关进行通信完成所有通信操作,由于门禁涉及到公司财产安全,所有通信都需要通过SSL加密传输。

产品功能

门禁机是门禁管理的核心控制设备,广泛安装于公司大门,实现了开关门的自动化控制,门禁机的主要使用场景是员工通过指纹、人脸验证后自动开门,其次是员工上下班打卡考勤;实现电子化控制之后需要重点考虑门禁的安全性,避免未授权人员开门。

通过云门禁系统与门禁机设备的集成,可以实现通过APP进行门禁机管理、门禁人员设置、远程监控等高级功能。具体涉及到接口协议的功能有:

1. 门禁人员信息同步,包括新增、更新、删除等;
2. 门禁人员(包括临时访客)特征信息录入和管理,包括人脸、指纹、密码、刷卡等;
3. 设置门禁管理员,仅管理员可以进入门禁机固件系统中进行本地功能操作;
4. 门禁状态上报;
5. 门禁打卡数据上报;
6. 门禁机开门时间段设置;
7. 远程开门;
8. APP扫码开门;
9. 门禁设备固件升级;

平台接口定义

  • 人员同步

与考勤机人员同步类似,门禁机在开始使用之前,首先需要通过云门禁应用将可以使用门禁的人员列表同步到门禁设备中去,后续门禁人员列表的信息发生变化时,也应实时同步到门禁设备,保持设备和应用之前人员列表数据的最终一致性。

应用会采用增量同步的方式主动将应用端门禁人员变化数据推送到设备,同时为了避免意外情况的发生。设备和应用之间要定时进行一致性检查,如果数据不一致,则由应用发起全量同步从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": 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_iduser_type外其它信息均不返回;

应用一次推送给设备的变更信息个数默认为1,除非在设备绑定时显示指定了推送数据size(产品特征类型user_sync_size),参见设备绑定指令402

门禁机设备收到人员变更信息后,应在处理完成后通过指令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 字符串 设备将本地所有门禁机人员的user_id通过异或计算得出hash值,公式示例如下: hash = user_id1 XOR user_id2 XOR user_id3.....XOR user_idN
reason 整型 发起原因。0为常规检查,1为本地数据异常检查。当值为1时,如果应用判断设备数据不一致时,应清除同步队列,重新发布全量同步

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

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

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

  • 人员特征信息录入

门禁机设备绑定后,应用端需要引导管理人员进行门禁人员指纹、人脸、密码或门禁卡等特征数据的录入。具体支持的特征类型通过产品特征类型参数access_type配置,参见设备绑定指令402

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

{
    "mid": "123456", 
    "from": "门禁应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_input", 
        "payload": {
            "user_id": 123,
            "feature_type": "fa|fp|pass|card"
        }
    }
}

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

参数 类型 描述
user_id 整型 当前录入身份特征的用户ID
feature_type 字符串 需要录入的用户特征数据类型(fa-人脸,fp-指纹,pass-密码,card-门禁卡)

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

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

响应payload各参数说明如下:

参数 类型 描述
user_id 整型 当前特征录入的用户ID
input_status 整型 特征录入状态:0录入超时(60秒)、1录入完成、2设备繁忙、3录入准备就绪、4设备容量已满、5当前用户特征已录满、6当前用户不存在、7录入已取消
feature_type 字符串 录入完成时必传:当前录入的特征类型
feature_value 字符串 录入完成时必传:当前录入的特征数据。为了安全起见,类似密码可采用MD5加密存储。

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

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

需要注意的是,如果应用收到响应状态为"当前用户不存在(6)",则应通过user_sync同步指令将该用户信息重新推送给设备。另外,如果应用一定时间内(例如15s)未收到任何设备响应时,可直接判定设备状态异常,自动终止当前操作。

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

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

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

  • 人员特征信息录入取消

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

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

{
    "mid": "123456", 
    "from": "门禁应用ID", 
    "to": "设备ID", 
    "time": 1502867086, 
    "action": 500, 
    "data": {
        "cmd": "feature_input_cancel", 
        "payload": {
            "user_id": 123,
            "feature_type": "fa|fp|pass|card"
        }
    }
}

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

参数 类型 描述
user_id 整型 当前录入特征信息的用户ID
feature_type 字符串 需要录入的用户特征数据类型

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

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

  • 人员特征信息更新

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

{
    "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开始

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

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

  • 门禁打卡上传

员工通过设备进行指纹、人脸、密码或刷卡打开门禁时,设备需将门禁数据发送至应用端(如果门禁机离线,应暂存本地等待上线后再次上传)。为了降低上传频率,设备可定时批量提交门禁打卡记录。

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

{
    "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:打卡时间(精确到秒);

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

门禁应用确认消息mid与请求一致,响应示例如下:

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

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

  • 门禁状态上报

门禁机如果安装了门磁传感器等装置的话,在门禁开启和关闭状态切换时,应主动上报门禁的开关状态数据到应用。

状态上报使用应用消息推送指令300来完成,上传请求示例如下:

{
    "mid": "123456", 
    "from": "设备ID", 
    "to": "门禁应用ID", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "device_status_update", 
        "payload": {
            "status": 0|1,
        }
    }
}

其中cmd固定为device_status_update表示门禁状态更新,请求payload各参数说明如下:

参数 类型 描述
status 整型 0-门禁关闭状态,1-门禁开启状态

应用收到该门禁状态变化后应返回确认信息给设备,示例如下:

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

如果设备未收到确认响应,应定时重复上传最新的门禁状态数据。另外,如果设备与平台断开连接了,再次恢复在线时,应第一时间上报门禁的状态数据。

  • 开门时间段设置

管理人员可以通过应用控制门禁机每天工作的时间段,非工作时间段非管理人员无法通过身份识别打开门禁。

应用支持按照周天设置不同的工作时间段,并通过设备信息推送指令500更新到设备,请求示例如下:

{
    "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,精确到分;

应用支持多组的时间段设置(考虑设备容量,建议最多10组),且每次更新时都应全量下发到设备,设备进行覆盖式更新。设备更新成功后,应使用应用消息推送指令300将更新结果返回给应用端,响应示例如下:

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

注意,多组时间段设置可能存在重叠,设备在开门时间段判断时应逐一比较,只要当前时间符合其中任一组设置即可开门。

  • 远程开门

应用应支持管理员通过APP远程控制门禁开启大门,以应对某些临时进入的特殊情况。但为了安全起见,远程开门必须管理员和进入人员协作分3步来完成:

1. 管理员通过APP生成临时授权码发送给门禁系统,门禁系统进入临时授权模式;
2. 管理员通过其他方式(例如电话、短信等)将授权码告知需要进入室内的人员,并通过设备屏幕输入临时授权码;
3. 门禁系统本地验证授权码,并打开大门。

首先,应用通过设备信息推送指令500将临时开门授权信息发送到设备,请求示例如下:

{
    "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键操作等方式主动退出了远程授权模式时返回
9 设备异常。设备出现了其他异常情况,例如设备繁忙、管理员身份验证失败、门禁无法开启等

注意,设备在不同的状态下应返回不同的status。设备一旦进入授权模式且用户输入完成授权码后,设备本地应通过相同的计算公式计算出结果与应用提供的授权access_code进行比对,如果完全一致且没有过期则视为认证通过,自动开启门禁,否则应提示对应的错误。

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

另外,如果门禁开启成功,设备需要通过门禁打卡将远程开门记录上传,但access_type应为remoteuser_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_scanuser_id为APP扫码的用户id。

  • 得力E+扫码进入云门禁应用

用户直接使用得力E+扫一扫扫描符合上一节中定义格式的二维码后,将自动进入云门禁应用,打开云门禁应用的H5应用页面,同时会在请求的头部headers中加入以下内容:

参数key 参考值 描述
_d_from qrCode(固定值) 表示是从扫描二维码打开的应用
_d_qr https://delicloud.com/d/12/appcall?to=actl&data=99 扫描到的原始二维码
_d_data 99 原始二维码中data部分的值
  • 固件升级

与其他接入平台的设备一样,门禁机通过统一的升级指令进行升级。具体逻辑请参考指令103以及指令202

  • 门禁考勤

由于门禁与考勤类似,均可用于员工出入管理。原则上来讲,门禁打卡记录上传门禁系统之后,可通过接口开放给考勤系统用于员工考勤。

为了实现门禁数据与考勤系统的互通,门禁应用应开放以下接口用于考勤:

1. 门禁数据开启通知;
2. 门禁数据推送;
3. 门禁数据关闭通知;

门禁应用可通过平台指令409以及指令516实现应用之间的接口通信。注意,以上接口均为同步请求,如果请求失败,应触发重试机制或提示用户重新操作。

  • 门禁数据开启通知

组织管理人员可在门禁应用主动开启考勤,开启之后,门禁应用将主动向考勤应用发起门禁数据开启通知。通知请求示例如下:

{
    "mid": "消息ID", 
    "from": "门禁应用ID", 
    "to": "考勤应用ID", 
    "action": 516, //该指令平台会自动转换为409转发
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
        "cmd": "access_data_open",
    }
}

其中cmd固定为access_data_open表示开启门禁数据推送,无payload参数。

开启通知请求通过指令409转发给考勤应用后,如果接收成功,考勤应用应同步返回如下结果:

{
    "code": 0, //0表示成功
    "msg": "", 
    "time": 1503025335,
}

一旦开启成功,门禁应用后续应自动推送本组织内门禁数据的变化信息到考勤应用,具体内容见下一小节。

  • 门禁数据推送

对于已经开启了门禁应用数据的其他应用,门禁应用应主动将门禁数据的信息更新实时推送给目标应用,推送信息包括:

1. 门禁设备数据;
2. 门禁打卡数据;

门禁设备推送数据应包括门禁机设备的更新(包括绑定、解绑)、设备名称以及设备状态的变化,推送数据请求示例如下:

{
    "mid": "消息ID", 
    "from": "门禁应用ID", 
    "to": "订阅应用ID", 
    "action": 516, //该指令平台会自动转换为409转发给目标订阅应用
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
        "cmd": "device_data_push",
        "payload": {
            "devices": [
                {
                    "device_id": "设备ID",
                    "device_name": "设备名称",
                    "status": 0|1,
                }, 
                {
                    "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, //该指令平台会自动转换为409
    "time": 1503025335, 
    "data": {
        "org_id": "组织ID",
        "cmd": "access_data_close",
    }
}

其中cmd固定为access_data_close表示关闭门禁数据推送,无payload参数。

关闭通知请求通过指令409转发给考勤应用后,如果接收成功,考勤应用应同步返回如下结果:

{
    "code": 0, //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。