版本明细

协议说明

背景

目前市场上ZKTeco的产品使用的通讯协议大部分是基于http/https的PUSH协议，短连接数据协议，经过多年的使用，发现了一些不足，主要是性能方面的，包括：

• HTTP的连接问题，HTTP客户端和服务器之间的交互是采用请求/应答模式，在客户端请求时，会建立一个HTTP连接，然后发送请求消息，服务端给出应答消息，然后连接就关闭了。（后来的HTTP1.1支持持久连接）因为TCP连接的建立过程是有开销的，如果使用了SSL/TLS开销就更大。
• HTTP消息头问题，现在的客户端会发送大量的HTTP消息头。
• HTTP通信方式问题，HTTP的请求/应答方式的会话都是客户端发起的，缺乏服务器通知客户端的机制，设备想要获取服务器命令，就需要不断地轮询服务器

综上为解决各种性能问题，由此引进面向长连接数据协议的ZKTeco BEST数据协议。

BEST 简介

BEST协议是Biometric Exchange Synchronization Transmission Protocol缩写，应用于ZKTeco相关产品，其强调的是数据协议，可应用于各种网络传输协议，如mqtt、websocket等

BEST-T 简介

BEST-T，即Best over tencent，表示基于腾讯IoT Hub 的BEST协议，采用mqtt协议通讯，，本文档只说明关于通道建立之后的数据通讯协议，关于设备端如何接入请直接参考腾讯IoT签名认证接入指引。

特别注意：BEST系列协议，如BEST-T，与主流BEST协议，其除了初始化(鉴权)流程多了一步腾讯的签名认证，其余数据格式均一致。

Broker声明

腾讯IoT Hub分为公有云及ZKTeco专有云，对应的Mqtt Broker Address如下：

注：从v1.3.0开始，提供broker信息动态获取操作

Topic声明

以腾讯IoT Hub鉴权为基础，以下相关数据交互与Topic关系：

• ${productId}/${deviceName}/event

对设备而言属于消息发布topic，凡是设备主动上报的消息，包含数据上传、命令回复、心跳、登录等，都固定发布到此topic。

• ${productId}/${deviceName}/control

对设备而言属于消息订阅topic，凡是服务端主动下发的消息，包含命令下发、设备消息回复等，都固定发布到此topic。

设备初始化流程

获取代理服务器信息

此步骤为http/https请求，在获取不到通讯服务器地址时，默认一直请求，直到获取到通讯服务器地址为止，请求时间间隔默认30秒。

Request:

URL: https://${ServerAddress}/v3/device/getBrokerServer?sn={SN}&type={TYPE}&nonce={NONCE}&timestamp={timestamp}&sign={SIGN}
Method: Get

• 正常回复：

{
    "code": "00000000",
    "message": "success",
    "payload": {
        "results": {
            "url": "mqtts://xxxx:port",
            "tProductId":"xxxxxxxxxx",
            "tSecretKey":"xxxxxxxx"
        }
    }
}

• 异常回复：

设备没权限或服务异常时回复

{
    "code": "其他不等于00000000的错误码",
    "message": "错误描述"
}

设备注册

设备注册，主要是为了获取授权码。
当设备Flash中不存在授权码，或者设备登录失败时调用。

若设备注册成功，则继续请求设备授权；
若设备注册失败，则60秒之后重新请求设备注册；

设备请求：

{
    "funcId": "dev.register",
    "sn": "xxxx", 
    "mid": "xxxx",
    "payload": {
        "params": {
            "protType": "best-t",
            "protVer": "1.0.0",
            "devKey": "xxxx",
            "devType": "att"
        }
    }
}

参数描述：

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "00000000", 
    "message": "消息内容", 
    "mid": "xxxxxxxx",
    "payload": {
        "results": {
            "authCode": "xxxxx"
        }
    }
}

设备授权

设备请求：

授权是为了获取登录密码。
设备注册成功后调用，若授权失败，则需重新注册，获取授权码。

{
    "funcId": "dev.accredit",
    "sn": "xxxx",
    "mid": "xxxx",
    "payload": {
        "params": {
            "devKey": "xxxx",
            "authCode": "xxxx"
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "00000000", 
    "message": "消息内容", 
    "mid": "xxxxxxxx",
    "payload": {
        "results": {
            "secret": "xxxxxxx"
        }
    }
}

设备登录

授权成功后走设备登录
若收到00000000成功编码，则继续走下一步流程【设备上报】；
若收到S00E0001、S00E0002、S00E0003、S00E0004等错误码，则重新走初始化流程；
若收到其他错误编码，则60秒之后继续登录；

设备请求:

{
    "funcId": "dev.login",
    "sn": "xxxx",
    "mid": "xxxx",
    "payload": {
        "params": {
            "devKey": "xxxx",
            "authCode": "xxxx",
            "secret": "xxxx"
        }
    }
}

服务端回复：

登录成功回复：

{
    "funcId": "cmd.dev.response",
    "code": "xxxxxxxx",
    "message": "消息内容",
    "mid": "xxxxxxxx"
}

设备上报

设备登录成功后，必须上报设备信息
设备信息上报仅仅在初始化流程上报，若服务端需要设备重新上报所有设备信息，则让设备重新走登录流程即可。
上报设备信息，包括设备容量、设备属性、固件信息等

设备请求：

{
    "funcId":"dev.report",
    "mid":"xxxx",
    "payload":{
        "params":{
            "devModel":"IFace302",
            "fwVer":"xxx",
            "maxUserCount":"10000",
            "userCount":"500",
            "maxAttLogCount":"50000",
            "attLogCount":"50000",
            "fpFunOn":"1",
            "fpVer":"10.0",
            "maxFpCount":"10000",
            "fpCount":"10000",
            "faceFunOn":"1",
            "faceVer":"9.0",
            "maxFaceCount":"1000",
            "faceCount":"1000",
            "visLightFunOn":"1",
            "maxVisLightCount":"5000",
            "visLightCount":"5000",
            "ip":"192.168.213.10",
            "mac":"00:17:61:10:01:26",
            "wirelessSSID":"ZKTeco-wifi",
            "lockFunOn":"0",
            "qrCodeSupport":"1",
            "qrCodeDec":"1",
            "qrCodeOn":"1",
            "auxInFunOn":"0",
            "lockOn":"1",
            "doorSensorTimeout":"10",
            "doorSensorAlarmTimeout":"5",
            "doorSensorMode":"0",
            "isHolidayValid":"0",
            "localAlarmOn":"1",
            "faceMThr":"74",
            "faceVThr":"63",
            "faceEThreshold":"70",
            "facePitchThreshold":"35",
            "faceRollYawThreshold":"25",
            "modifyClarityCond":"40",
            "faceMinThreshold":"80",
            "motionDetectSensitivity":"4",
            "grayThroldValue":"80",
            "faceLivenessThreshold":"50",
            "enableBioTest":"1",
            "IRLivenessFunOn":"0",
            "WDRStatus":"0",
            "volume" : "10",
            "funcIds": ["dev.option.upload", "dev.data.upload.user", "xxxxx"],
            "autoRegisterFunOn":"0"
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx",
    "message": "xxxx",
    "mid": "xxxx",
    "payload": {
        "results": {
            "timezone": "+08:00",
            "supportHeartbeat": "1",
            "heartbeatInterval": "60",
            "fpFunOn": "0",
            "faceFunOn": "0",
            "visLightFunOn": "0",
            "punchPhotoFunOn": "0",
            "qrCodeDecryptType": "2",
            "qrCodeDecryptKey": "UkhGaXpuaXE2bjQ3YkxqNFhVVlpMUzF5eVFFVzhTaUo="
        }
    }
}

心跳

设备登录成功才需要发送业务心跳。
此处心跳为业务心跳，主要作用是告知服务端设备当前的运行状态，以便服务端能够准确的下发设备命令；

设备请求：

{
    "funcId": "dev.heartbeat", 
    "mid": "xxxx", 
    "payload": {
        "params": {
            "isFree": "1"
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "00000000", 
    "message": "xxxx", 
    "mid": "xxxx"
}

业务心跳使用约定：

1. 长连接本身系统心跳(如ping/pong)仍然保留；
2. 初始化流程走完才能发送业务心跳；
3. 若设备在处理命令，可不用发业务心跳；
4. 业务心跳的时间间隔默认60秒，可由服务端控制(初始化返回参数或者单独下发设置客户端选项命令)；

为什么需要业务心跳：

业务心跳主要是补救措施，假设服务端一批命令下发了100条，设备只回复了99条，这个时候服务端没法准确的判断剩下的一条是在执行中，还是已丢失(可能网络传输丢失，也可能设备拿到数据之后因某些原因丢失)，此时服务端不知道是要重新下发命令，还是继续等待设备回复。

如何关闭心跳：

服务端可以不依赖此心跳，自己内部实现解决上面描述的问题，此时设备不应该再开启业务心跳功能，会浪费流量，给服务端压力，所以可以将其关闭掉。仅需要在设备信息请求回复不支持心跳功能即可，即supportHeartbeat为0

设备上传数据

上传设备参数

上传设备参数，主要是上传设备记录数据，如人员数、指纹数、打卡记录数等等信息。
若设备数据有产生变动，则应上传相关的数据记录信息。

设备请求：

{
    "funcId":"dev.option.upload",
    "mid":"xxxx",
    "payload":{
        "params":{
            "option":{
                "optionName1":"optionValue1",
                "optionName2":"optionValue2"
            }
        }
    }
}

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

上传人员信息

上传设备上的人员信息，包含基本信息、设备密码、角色、卡号、模板信息等

设备请求

{
    "funcId": "dev.data.upload.user",
    "mid": "xxxx",
    "payload": {
        "params": {
            "users": [{
                "pin": "2956",
                "name": "luther.lin",
                "passwd": "",
                "pri": "0",
                "verifyMode": "0",
                "cards": ["4010846978"],
                "bioDatas": [{
                    "no": "0",
                    "index": "0",
                    "valid": "1",
                    "duress": "0",
                    "type": "2",
                    "majorVer": "10",
                    "minorVer": "1",
                    "fmt": "0",
                    "tmp": "xxxxxxxxxxxxxxxxxxxx"
                }]
            }]
        }
    }
}

请求参数详解:

通用部分见附录1

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

响应参数详解:

通用部分见附录1

上传打卡记录

设备请求

{
    "funcId": "dev.data.upload.attLog",
    "mid": "xxxx",
    "payload": {
        "params": {
            "attLogs": [{
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T08:59:59+08:00",
                "type": "1"
            }, {
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T14:59:59+08:00",
                "type": "1"
            }]
        }
    }
}

请求参数详解:

通用部分见附录1

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

上传生物特征图片

设备请求

{
    "funcId": "dev.data.upload.bioPhoto",
    "mid": "xxxx",
    "payload": {
        "params": {
            "bioPhotos": [{
                "pin": "2956",
                "type": "9",
                "no": "0",
                "index": "0",
                "size": "95040",
                "content": "AAAA........",
                "extension": "xxxx"
            }]
        }
    }
}

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

上传访客记录

预约访客的来访记录

设备请求

{
    "funcId": "dev.data.upload.visitLog",
    "mid": "xxxxxxxx",
    "payload": {
        "params": {
            "logs": [{
                    "pin": "8065",
                    "verifyMode": "1",
                    "visitTime": "2019-07-31T08:59:59+08:00"
                }
            ]
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx", 
    "message": "xxxx", 
    "mid": "xxxx"
}

上传文件

此协议主要针对需上传大文件时使用，此处不强调具体文件格式，仅读取文件字节流base64进行传输，具体文件目标格式以目标业务使用时为准；

注：大数据时也可以直接使用此协议进行预先传输，然后再具体功能协议中指定大数据内容所属fileId，此时fileId可以理解为是一个大数据标识

上传开始

通知服务端要开始上传文件，指定文件的fileId、大小、checksum等文件基础信息

设备请求

{
    "funcId": "dev.file.upload.start",
    "mid": "xxxx",
    "payload": {
        "params": {
            "fileId": "e78dc2cef23d495ab4f890fe3362bee9",
            "size": "1208",
            "checksum": ""
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx", 
    "message": "xxxx", 
    "mid": "xxxx"
}

上传文件包

上传文件分包内容到服务端，其中分包内容为读取文件分包字节base64加密串

设备请求

{
    "funcId": "dev.file.upload.package",
    "mid": "xxxx",
    "payload": {
        "params": {
            "fileId": "e78dc2cef23d495ab4f890fe3362bee9",
            "offset": "215",
            "content": "xxxxxxxxxxxxxxx"
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx", 
    "message": "xxxx", 
    "mid": "xxxx"
}

上传完成

设备请求

{
    "funcId": "dev.file.upload.end",
    "mid": "xxxx",
    "payload": {
        "params": {
            "fileId": "e78dc2cef23d495ab4f890fe3362bee9"
        }
    }
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx", 
    "message": "xxxx", 
    "mid": "xxxx"
}

上传打卡照片

设备请求

{
    "funcId": "dev.data.upload.punchPhoto",
    "mid": "xxxx",
    "payload": {
        "params": {
            "punchPhotos": [{
                "pin": "2956",
                "punchTime": "2019-07-31T08:59:59+08:00",
                "type": "1",
                "content": "xxxxxxxxxxxxxxxxxxxxx",
                "contentFileId": "xxxxxxxxxxxxx"
            }]
        }
    }
}

上传门实时状态

设备上传门实时状态到服务端

设备请求:

{
    "funcId":"dev.data.upload.doorRealStatus",
    "mid":"xxxx",
    "payload":{
        "params":{
            "realStatuss":[
                {
                    "time":"2020-12-30T20:00:00+08:00",
                    "sensor":"2",
                    "relay":"0",
                    "alarm":"0",
                    "coerce":"0",
                    "auxOut":"0"
                }
            ]
        }
    }
}

请求参数详解:

服务端响应:

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

上传设备实时状态

设备上传设备实时状态到服务端

设备请求:

{
    "funcId":"dev.data.upload.devRealStatus",
    "mid":"xxxx",
    "payload":{
        "params":{
            "realStatuss":[
                {
                    "time":"2020-12-30T20:00:00+08:00",
                    "tamper":"0"
                }
            ]
        }
    }
}

请求参数详解:

服务端响应:

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

设备实时请求

获取服务端时间

设备请求服务端获取当前时间，2秒之内没收到服务端的回复此同步时间无效。

设备请求：

{
    "funcId": "dev.system.sync.time",
    "imme": "1",
    "mid": "xxxx"
}

服务端响应：

{
    "funcId": "cmd.dev.response",
    "code": "xxxx",
    "message": "xxxx",
    "mid": "xxxx",
    "payload": {
        "results": {
            "time": "2019-08-12T20:01:01+08:00"
        }
    }
}

物理重置通知

人工手动对设备进行恢复出厂设置时触发事件，通知服务端。
恢复出厂设置之后，设备可能网络已经断开，所以设备需在下一次联网初始化成功后告知服务端。

设备请求

{
    "funcId": "dev.system.reset",
    "mid": "xxxx",
    "payload": {
        "params": {
            "time": "2019-08-12T20:01:01+08:00"
        }
    }
}

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

指纹登记进度通知【已过时】

设备接收到服务端下发的远程登记指纹命令后，需将指纹登记进度实时通知服务端。

但远程登记指纹协议已过时，建议使用远程登记生物特征

设备请求：

{
    "funcId":"dev.data.tip.fp",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "num":"xxxx",
            "code":"xxxx",
            "message":"xxxx"
        }
    }
}

请求参数详解:

code与message消息列表：

服务端响应：

{
    "funcId":"cmd.dev.response",
    "code":"xxxx",
    "message":"xxxx",
    "mid":"xxxx"
}

控制命令

登记指纹【已过时】

设备接收到此命令，则自动打开登记指纹窗口，登记指定员工工号的指纹模板；

此接口已过时，建议使用远程登记生物特征

服务端请求：

{
    "funcId":"cmd.control.enter.fp",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "pin":"xxxx",
            "no":"xxxx"
        }
    }
}

请求参数详解:

设备响应：

1. 上传指纹登记进度，见指纹登记进度通知

2. 回复命令执行结果，见命令回复

取消登记指纹

设备收到此命令，要取消登记指纹动作，退出登记指纹窗口。

服务端请求：

{
    "funcId":"cmd.control.cancel.fp",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

见命令回复

重启客户端

重启设备

服务端请求：

{
    "funcId":"cmd.control.reboot",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

请求参数详解:

设备响应：

见命令回复

重新登录

设备收到此命令，重新请求设备登录

服务端请求：

{
    "funcId":"cmd.control.relogin",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

见命令回复

远程开门

Request:

{
    "funcId": "cmd.control.open.door", 
    "imme": "1",
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxxx"
        }
    }
}

设备响应：

见命令回复

远程登记生物特征

服务端下发远程登记生物特征命令，固件端实时响应打开对应的登记生物特征窗口，并实时上报登记进度和结果。

服务端需根据设备上报的multiBioEnrollSupport参数来判断设备是否支持远程登记功能

服务端请求:

{
    "funcId": "cmd.control.enroll.bio",
    "imme": "1",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "pin": "2956",
            "type": "1",
            "no" : "0"
        }
    }
}

设备响应

• 上传生物特征登记进度/结果

{
    "funcId": "dev.data.tip.bio", 
    "imme": "1",
    "mid": "xxxx", 
    "payload": {
        "params": {
            "num":"1",
            "code": "0", 
            "message": "成功",
            "end": "1"
        }
    }
}

code及message说明

• 回复命令执行结果, 见命令回复

取消登记生物特征

设备收到此命令，要取消登记生物特征动作，退出登记生物特征窗口

服务端请求:

{
    "funcId": "cmd.control.cancel.bio",
    "imme": "1",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId": "xxxx"
        }
    }
}

设备响应:

见命令回复

清除命令

清除全部数据

清除设备中所有数据，包括人员信息、生物模板、打卡记录等。

服务端请求：

{
    "funcId":"cmd.data.clear.all",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

见命令回复

清除用户信息

删除设备中的所有用户，包含模板等关联信息

服务端请求：

{
    "funcId":"cmd.data.clear.user",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

见命令回复

清除打卡记录

删除设备中的打卡记录

服务端请求：

{
    "funcId":"cmd.data.clear.attLog",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

见命令回复

清除节假日信息

删除设备中所有的节假日信息

Request:

{
    "funcId": "cmd.data.clear.holiday", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxxx"
        }
    }
}

设备响应：

见命令回复

清除开门密码

Request:

{
    "funcId": "cmd.data.clear.doorPassword", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxxx"
        }
    }
}

设备响应：

见命令回复

删除命令

删除人员

删除设备中人员信息

服务端请求：

{
    "funcId":"cmd.data.delete.user",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "pins":[
                "xxxx",
                "xxxx",
                "xxxx"
            ]
        }
    }
}

请求参数详解:

设备响应：

见命令回复

删除模板

删除设备中的生物模板

服务端请求：

{
    "funcId":"cmd.data.delete.bioData",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "bioDatas":[
                {
                    "pin":"2956",
                    "type":"2",
                    "no":"0"
                }
            ]
        }
    }
}

请求参数详解:

通用部分见附录1

设备响应：

见命令回复

删除门禁时间段

Request:

{
    "funcId": "cmd.data.delete.accTimezone", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "timezoneIds": ["100","101"]
        }
    }
}

设备响应：

见命令回复

删除门禁组

Request:

{
    "funcId": "cmd.data.delete.accGroup", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "groupIds": ["100","101"]
        }
    }
}

设备响应：

见命令回复

删除节假日

Request:

{
    "funcId": "cmd.data.delete.holiday", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "holidayIds": ["xx"]
        }
    }
}

设备响应：

见命令回复

删除访客信息

Request:

{
    "funcId": "cmd.data.delete.visitor", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxxx", 
            "pins": ["xxx","xxxx"]
        }
    }
}

设备响应：

见命令回复

删除开门密码

Request:

{
    "funcId": "cmd.data.delete.doorPassword", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxxx", 
            "operators": ["xxx","xxxx"]
        }
    }
}

设备响应：

见命令回复

更新命令

更新人员信息

服务端请求：

{
    "funcId":"cmd.data.update.user",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "users":[
                {
                    "pin":"2956",
                    "name":"林某某",
                    "passwd":"123456",
                    "pri":"1",
                    "cards":[
                        "4010846978",
                        "521186050"
                    ],
                    "verifyMode":"0",
                    "bioDatas":[
                        {
                            "no":"0",
                            "index":"0",
                            "valid":"1",
                            "duress":"0",
                            "type":"2",
                            "majorVer":"10",
                            "minorVer":"1",
                            "fmt":"0",
                            "tmp":"xxxxxxxxxxxx"
                        }
                    ]
                }
            ]
        }
    }
}

请求参数详解:

通用部分见附录1

其他参数信息参考人员信息上传

注：人员信息除了pin号为必填字段，其他为选填，当不包含某个属性key时，表示该属性不做变更。

// 举例说明，以下为表示更新员工设备密码

{
    "funcId": "cmd.data.update.user",
    "mid": "b488030912294ff29d5cc4435248452e",
    "payload": {
        "params": {
            "cmdId": "1001",
            "users": [{
                "pin": "2956",
                "passwd": "123456"
            }]
        }
    }
}

设备响应：

见命令回复

更新比对照片

服务端请求：

{
    "funcId":"cmd.data.update.bioPhoto",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "bioPhotos":[
                {
                    "pin":"xxxx",
                    "type":"xxxx",
                    "content":"xxxx",
                    "url":"xxxx"
                }
            ]
        }
    }
}

请求参数详解:

通用部分见附录1

设备响应：

见命令回复

更新门禁时间段

Request:

{
    "funcId": "cmd.data.update.accTimezone", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx", 
            "timezones": [
                {
                    "timezoneId": "1", 
                    "monStart": "0", 
                    "monEnd": "2359", 
                    "tuesStart": "0", 
                    "tuesEnd": "2359", 
                    "wedStart": "0", 
                    "wedEnd": "2359", 
                    "thurStart": "0", 
                    "thurEnd": "2359", 
                    "friStart": "0", 
                    "friEnd": "2359", 
                    "satStart": "0", 
                    "satEnd": "2359", 
                    "sunStart": "0", 
                    "sunEnd": "2359"
                }
            ]
        }
    }
}

设备响应：

见命令回复

更新门禁权限组

Request:

{
    "funcId": "cmd.data.update.accGroup", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx", 
            "groups": [
                {
                    "groupId": "1", 
                    "verifyMode": "0", 
                    "timezoneIds": ["xx","xx","xx"],
                    "vaildHoliday": "0"
                }
            ]
        }
    }
}

设备响应：

见命令回复

更新节假日

Request:

{
    "funcId": "cmd.data.update.holiday", 
    "mid": "xxxxxxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "holidays":[{
                "holidayId": "x",
                "holidayName": "NationalDay",
                "startDate": "2018-10-01",
                "endDate": "2018-10-07",
                "startTime": "0",
                "endTime": "2359"
            }]
        }
    }
}

设备响应：

见命令回复

更新访客信息

Request:

{
    "funcId": "cmd.data.update.visitor", 
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "xxxx", 
            "visitors": [
                {
                    "pin": "xxxx", 
                    "name": "xxxx",
                    "password":"fbfe82e76c06ea568e3301ab17a9d4677c1481b8a4f1ca137411e10153deabc3",
                    "passwordSalt":"c09eb7463827cda245f3a398bd453c42",
                    "startTime":"2020-01-01T00:00:00+08:00",
                    "endTime":"2020-12-31T23:59:59+08:00"
                }
            ]
        }
    }
}

设备响应：

见命令回复

更新人员门禁权限

设置人员门禁权限，如时间段、门禁组等信息

服务端请求：

{
    "funcId": "cmd.data.update.userAccPrivilege",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId": "xxxx",
            "userAccPrivileges": [{
                "pin": "xxxx",
                "timezoneType": "1",
                "timezoneIds": ["xxx", "xxx", "xxx"],
                "groupIds": ["xx", "xx"],
                "customTimezones": [{
                    "monStart": "0",
                    "monEnd": "2359",
                    "tuesStart": "0",
                    "tuesEnd": "2359",
                    "wedStart": "0",
                    "wedEnd": "2359",
                    "thurStart": "0",
                    "thurEnd": "2359",
                    "friStart": "0",
                    "friEnd": "2359",
                    "satStart": "0",
                    "satEnd": "2359",
                    "sunStart": "0",
                    "sunEnd": "2359"
                }],
                "ruleType": "1",
                "verifyModeType": "0"
            }]
        }
    }
}

请求参数详解:

通用部分见附录1

设备响应：

见命令回复

更新访客照片

服务端请求：

{
    "funcId":"cmd.data.update.visitorBioPhoto",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "visitorBioPhotos":[
                {
                    "pin":"2956",
                    "type":"9",
                    "content":"base64",
                    "url":"https://test.zkteco.com/xxxx.jpg"
                }
            ]
        }
    }
}

请求参数详解:

通用部分见附录1

设备响应：

见命令回复

更新开门密码

服务端下发密码命令到设备, 用于临时密码或者远程密码开门

服务端请求:

{
    "funcId": "cmd.data.update.doorPassword",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId": "1001",
            "doorPasswords": [{
                "operator": "luther",
                "startTime": "2020-01-01T00:00:00+08:00",
                "endTime": "2020-02-01T00:00:00+08:00",
                "password": "fbfe82e76c06ea568e3301ab17a9d4677c1481b8a4f1ca137411e10153deabc3",
                "passwordSalt": "c09eb7463827cda245f3a398bd453c42",
                "passwordType": "0"
            }]
        }
    }
}

请求参数详解:

使用密码开门将会产生一条门禁记录，使用上传打卡记录上传数据，其中pin=operator，type=2即门禁记录

设备响应：

见命令回复

获取数据命令

重新上传人员信息

重新上传设备人员信息到服务端

服务端请求：

{
    "funcId":"cmd.data.reupload.user",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

1. 重新上传人员信息

重新上传人员信息，与人员信息上传一样，只多了cmdId：

设备请求：

{
    "funcId":"dev.data.upload.user",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "users":[
                {
                    "pin":"xxxx",
                    "name":"xxxx",
                    "passwd":"xxxx",
                    "pri":"xxxx",
                    "cards":[
                        "xxxx",
                        "xxxx"
                    ],
                    "bioDatas":[
                        {
                            "no":"xxxx",
                            "index":"xxxx",
                            "valid":"xxxx",
                            "duress":"xxxx",
                            "type":"xxxx",
                            "majorVer":"xxxx",
                            "minorVer":"xxxx",
                            "fmt":"xxxx",
                            "tmp":"xxxx"
                        }
                    ]
                }
            ]
        }
    }
}

2. 回复命令执行结果，见命令回复

打卡数据自动校对

打卡数据自动校对

服务端请求：

{
    "funcId":"cmd.data.check.attLog",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "startTime":"2019-07-31T00:00:00+08:00",
            "endTime":"2019-07-31T23:59:59+08:00",
            "logCount":"20"
        }
    }
}

请求参数详解:

设备响应：

1. 上传时间段内的数据

如果设备在此时间段内的打卡记录总数大于服务端的，则要重新上传此时间段内的所有打卡记录，入参与上传打卡记录基本一致，仅多回传了cmdId.

设备请求：

{
    "funcId":"dev.data.upload.attLog",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "attLogs":[
                {
                    "pin":"2956",
                    "attState":"255",
                    "verifyMode":"0",
                    "workCode":"0",
                    "punchTime":"2019-07-31T08:59:59+08:00"
                }
            ]
        }
    }
}

2. 回复命令执行结果，见命令回复

查询打卡记录

查询指定时间段内的打卡记录

服务端请求：

{
    "funcId":"cmd.data.query.attLog",
    "imme":"xxxx",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "startTime":"2019-07-31T00:00:00+08:00",
            "endTime":"2019-07-31T23:59:59+08:00"
        }
    }
}

设备响应：

1. 上传时间段内的数据

上传此时间段内的所有打卡记录，入参与上传打卡记录基本一致，仅多回传了cmdId.

设备请求：

{
    "funcId": "dev.data.upload.attLog",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId":"xxxx",
            "attLogs": [{
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T08:59:59+08:00"
            }, {
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T08:59:59+08:00"
            }]
        }
    }
}

参数描述详见上传打卡记录

2. 回复命令执行结果，见命令回复

重新上传打卡记录

重新上传设备上的所有打卡记录

服务端请求：

{
    "funcId":"cmd.data.reupload.attLog",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

设备响应：

1. 重新上传打卡记录

   重新上传设备上打卡记录，与上传打卡记录一样，只多传了cmdId

设备请求：

{
    "funcId": "dev.data.upload.attLog",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId":"xxxx",
            "attLogs": [{
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T08:59:59+08:00"
            }, {
                "pin": "2956",
                "attState": "255",
                "verifyMode": "0",
                "workCode": "0",
                "punchTime": "2019-07-31T08:59:59+08:00"
            }]
        }
    }
}

参数描述详见上传打卡记录

2. 回复命令执行结果，见命令回复

设备参数命令

设置设备参数

请求规范

服务端请求：

{
    "funcId":"cmd.option.set",
    "imme":"xxxx",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "option":{
                "optionName1":"optionValue1",
                "optionName2":"optionValue2"
            }
        }
    }
}

设备响应：

见命令回复

设置门禁参数

请求案例如下，按需设置参数：

{
    "funcId": "cmd.option.set", 
    "imme": "1",
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "1",
            "option":{
                "lockOn": "1", 
                "doorSensorTimeout": "10",
                "doorSensorAlarmTimeout": "5",
                "doorSensorMode": "0",
                "doorOpenTimezone": "1",
                "doorCloseTimezone": "1",
                "isHolidayValid": "0",
                "localAlarmOn": "1",
                "auxOutKeepTime":"255",
                "auxOutOption":"1"
            }
        }
    }
}

名词解释：

设置设备音量

请求案例如下，按需设置参数：

{
    "funcId": "cmd.option.set", 
    "imme": "1",
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "1",
            "option":{
                "volume": "10"
            }
        }
    }
}

设置人脸阈值

请求案例如下，按需设置参数：

{
    "funcId": "cmd.option.set", 
    "imme": "1",
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "1",
            "option":{
                "faceMThr": "74",
                "faceVThr": "63"
            }
        }
    }
}

设置打卡照片参数

人员在设备人脸识别比对时的相关配置

请求案例如下，按需设置参数：

{
    "funcId": "cmd.option.set", 
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "1",
            "option":{
                "punchPhotoFunOn": "1",
                "capturePic": "2",
                "captureAlarm": "80",
                "captureFailInterval": "5",
                "captureSuccInterval": "5",
                "captureSaveType": "0",
                "captureVoiceOn": "0"
            }
        }
    }
}

设置门禁二维码参数

{
    "funcId": "cmd.option.set", 
    "mid": "xxxx", 
    "payload": {
        "params": {
            "cmdId": "1",
            "option":{
                "qrCodeDecryptType": "2",
                "qrCodeDecryptKey": "UkhGaXpuaXE2bjQ3YkxqNFhVVlpMUzF5eVFFVzhTaUo=" 
            }
        }
    }
}

获取设备参数

服务端获取设备参数信息

服务端请求：

{
    "funcId":"cmd.option.get",
    "imme":"xxxx",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "options":[
                "xxxx",
                "xxxx"
            ]
        }
    }
}

1. 上传设备参数

参考上报设备参数

设备请求：

{
    "funcId":"dev.option.upload",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
            "option":{
                "xxxx":"xxxx"
            }
        }
    }
}

请求参数详解:

通用部分见附录1

2. 回复命令执行结果，见命令回复

重置设备参数

设备重置分为以服务端为主和以设备端为主，以服务端为主时，服务端自行定义默认配置值，重置时下发对应参数的设备设置指令即可，以设备端为主时，只需下发一条指令，设备端自行根据端侧默认配置进行重置。

此处重置设备参数指令只要指的是以设备端为主的业务场景指令。

重置所有参数

以设备端为主，重置所有设备参数为默认值，即设备参数配置恢复出厂设置

服务端请求：

{
    "funcId":"cmd.option.reset",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
        }
    }
}

设备响应：

见命令回复

人脸参数重置

以设备端为主，重置人脸相关参数为默认值，涉及参数可参考设置人脸阀值

服务端请求：

{
    "funcId":"cmd.option.reset.face",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
        }
    }
}

设备响应：

见命令回复

门禁参数重置

以设备端为主，重置门禁相关参数为默认值，涉及参数可参考设置门禁参数

服务端请求：

{
    "funcId":"cmd.option.reset.acc",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
        }
    }
}

设备响应：

见命令回复

设备音量重置

以设备端为主，重置音量相关参数为默认值，涉及参数可参考设置设备音量

服务端请求：

{
    "funcId":"cmd.option.reset.volume",
    "imme":"1",
    "mid":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx",
        }
    }
}

设备响应：

见命令回复

命令回复

设备收到服务端下发的命令之后，回复命令执行结果

设备请求：

{
    "funcId":"dev.cmd.response",
    "mid":"xxxx",
    "code":"xxxx",
    "message":"xxxx",
    "payload":{
        "params":{
            "cmdId":"xxxx"
        }
    }
}

请求参数详解:

通用部分见附录1

附录

请求规范说明

业务功能命名规范

每个消息都带有业务功能标识，即funcId。
绑定流程请求以及心跳请求格式固定，其他请求数据格式要求如下：

funcId: xxxx.xxxx.xxxx.xxxx
第一个xxxx，请求类型，cmd表示命令下发，dev表示设备请求
第二个xxxx，数据大类，data表示基础数据，option表示参数数据，firmware表示固件数据，system表示系统数据，cmd表示命令数据，control表示控制数据，......
第三个xxxx，操作类型, delete表示删除，upload表示上传，update表示更新，get表示获取，set表示设置，upgrade表示升级，sync表示同步，......
第四个xxxx，数据小类，user表示用户数据，info表示信息，time表示时间，... ...

命令下发规范

命令下发为服务端发起的，funcId约定cmd开头

格式如下：

{
    "funcId": "cmd.xxxx",
    "imme": "xxxx",
    "mid": "xxxx",
    "payload": {
        "params": {
            "cmdId": "xxxx"

        }
    }
}

参数说明：

设备请求规范

此处包含两个方面
1. 设备主动请求上传数据；
2. 回复服务端下发的命令执行结果集；

请求格式如下：

{
        "funcId": "dev.xxxx",
        "imme": "xxxx",
        "sn": "xxxx",
        "mid": "xxxx",
        "payload": {
            "params": {
                "cmdId": "xxxx",
                ... ...
            }
        }
    }

参数说明：

消息回复规范

格式如下：

{
    "code": "xxxx",
    "message": "xxxx",
    "imme": "xxxx",
    "mid": "xxxx",
    "payload": {
        "results": {

        }
    }
}

参数说明：

验证方式说明

生物特征类别

0：通用的
1：指纹
2：面部(近红外)
3：声纹
4：虹膜
5：视网膜
6：掌纹
7：指静脉
8：掌静脉
9：面部(可见光)

服务端错误编码

设备错误编码

生物具体个体编号