门禁一体机标准协议接口定义-20210630

本文是门禁设备对接物业一体机的接口协议。

一、方案介绍

elevator

上图是物业一体机的整体架构,如图所示,物业一体机上已经集成好了阿里云IoT开发的门禁驱动,厂商门禁设备只需要对接好门禁设备驱动相应的协议接口即可。

门禁一体机标准协议支持:人脸识别、二维码、刷卡、蓝牙、可视对等功能,本文会围绕这些功能介绍对应的接口协议。

二、通用

注意

1)门禁机对接边缘服务器,访问边缘服务器的10000端口。

2)边缘服务器访问门禁机的端口由门禁设备厂商自定义,定义后固定不变。

3)所有HTTP 报文的首部信息中,不能带有Connection: Keep-Alive字段,可以设置为Connection:Close。

4)物业管理一体机,以下简称“边缘服务器”。

通用接口是必须实现的接口,主要有以下几个。

2.1 建立连接

调用此接口建立门禁机与边缘服务器的双向通信连接,门禁设备跟边缘服务器互为客户端和服务端。

URL:http://[边缘服务器IP 或 门禁机IP]:[端口]/connect
Method:POST
Content-Type:application/json

说明

连接建立流程:

  1. 门禁机携带下面的请求参数向边缘服务器发起连接请求。

  2. 边缘服务器校验ip参数是否已经配置,如未配置,拒绝连接请求。设备信息配置需要预先在云端配置好,并部署到边缘。

  1. 门禁机收到边缘服务器返回的成功消息后,单向连接建立完成。响应消息中包含一个有效的token信息。

  2. 边缘服务器携带下面的请求参数向门禁机发起连接请求。

  1. 门禁机收到请求后,返回成功消息,里面包含一个有效的token信息。

  2. 边缘服务器收到成功消息后,双向连接建立完成。

请求参数

名称

类型

是否必选

示例值

描述

sn

String

123456789

长度为4-32个字符,可以包含英文字母、数字和特殊字符:连字符(-)、下划线(_)、at符号(@)、点号(.)、和英文冒号(:)。

time

Integer

1589472000

请求的时间戳。以秒为单位,需要使用UTC时间。

ip

String

192.168.1.128

连接发起方的IPv4地址。

mac

String

00-**-3D-40

连接发起方的MAC地址。

keepalive

Integer

30

单位:秒,合法取值范围[10,120]。

signMethod

String

md5

签名方式,目前支持MD5、SHA-1、SHA-256。取值范围{ md5, sha1, sha256 }。

sign

String

4db511**42

需要签名的内容封装格式:

"TIME{time}MAC{mac}SN{sn}IP{ip}"大括号内的是具体内容,其外面的是名称。备注:time要转换成string类型。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

调用成功时,返回内容定义如下。

名称

类型

示例值

描述

token

String

6f2a-***-1-128

连接成功后,由接收连接的server端颁发的连接成功标识,代表一个有效连接,最大长度位64字节。在后续client的请求中需要携带,如“心跳保活”。

示例

请求示例

{
    "sn": "123456789",
    "time": 1589472000,
    "ip": "192.168.1.128",
    "mac": "00-16-EA-AE-3D-40",
    "keepalive": 30,
    "signMethod": "md5",
    "sign": "4db51117ad87cef349f45a3b14c05142"
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
    }
}

错误码

code

描述

7

设备ip地址未在边缘服务器上注册。需要在IoT物联网平台上添加子设备,配置好ip,部署到边缘服务器上,即可。

附录查看更多错误码

2.2 心跳保活

门禁机与边缘服务器之间定期发送心跳消息,以确保消息通道的连通性,维持对方的在线状态。

URL:http://[边缘服务器IP 或 门禁机IP]:[端口]/keepalive
Method:POST
Content-Type:application/json

说明

建立连接后,服务器会向客户端颁发一个token,心跳消息中需要携带此token。当发送心跳时,如果对方返回token无效,那么需要重新建立连接,获取有效token。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-1-128

有效连接的标识。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

code

描述

4

token失效,需要重新建立连接,获取有效token。

附录查看更多错误码

2.3 远程开门

边缘服务器发送开门指令给门禁机。

URL:http://[门禁机IP]:[端口]/remoteOpen
Method:POST
Content-Type:application/json

说明

云端调用IoT设备的远程开门服务,边缘端接收到消息后,发送开门指令给门禁机,设备收到指令后开门放行。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-1-128

有效连接的标识。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

code

描述

4

token失效,需要重新建立连接,获取有效token。

附录查看更多错误码

2.4 报警事件

门禁机上报报警事件给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/alarmEvent
Method:POST
Content-Type:application/json

说明

门禁机上报设备报警事件给边缘服务器,边缘服务器发送事件到云端。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

alarmType

Integer

1

报警类型,枚举如下:

  • 0:防拆报警

  • 1:防拆报警解除

  • 2:无效门禁卡

  • 3:无效蓝牙卡

  • 4:强制开门报警

  • 5:强制开门报警解除

  • 6:超时未关门报警

  • 7:超时未关门报警解除

cardId

String

777342461

门禁卡或蓝牙卡的卡号。当alarmType为2或3时,需要加入此参数。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "alarmType":2,
    "cardId":"777342461"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

code

描述

4

token失效,需要重新建立连接,获取有效token。

附录查看更多错误码

2.5 设置常开状态

边缘服务器设置门禁设备的常开状态。

URL:http://[门禁机IP]:[端口]/setKeepOpen
Method:POST
Content-Type:application/json

说明

目前设置门常开状态的功能只支持具有刷卡功能的门禁设备。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

data

JSONArray

  • keepOpen

Integer

1

门禁设备常开状态,枚举如下:

  • 0:关闭

  • 1:开启(常开状态)

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "data":{
        "keeOpen": 1
    }
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

2.6 查询常开状态

边缘服务器查询门禁设备的常开状态。

URL:http://[门禁机IP]:[端口]/getKeepOpen
Method:POST
Content-Type:application/json

说明

目前查询门常开状态的功能只支持具有刷卡功能的门禁设备。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

  • keepOpen

Integer

0

门禁设备常开状态,枚举如下:

  • 0:关闭

  • 1:开启(常开状态)

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "keepOpen": 0
    }
}

错误码

附录查看更多错误码

三、人脸

注意

人脸识别由两种方式:边侧识别和端侧识别。

边侧识别:人脸识别在边缘端完成,用的是阿里提供的运行在一体机上的人脸识别算法。设备端只需要发送人脸识别请求到边缘端即可。

端侧识别:人脸识别在设备端完成,用的是厂商自有的人脸识别算法。设备端识别完成后,上报人脸通行事件到边缘端。

3.1 人脸识别请求(边缘端识别)

门禁机抓拍通行人员的人脸照片,向边缘服务器发起人脸识别请求。

URL:http://[边缘服务器IP]:[端口]/recognize
Method:POST
Content-Type:multipart/form-data

说明

当有人员通行时,门禁设备向边缘服务器发起人脸识别。边缘认证成功后,返回给门禁设备允许放行,并上报人脸匹配通行事件。如果认证失败,返回失败结果给设备。

如果开启体温检测功能,体温值超过正常范围,则不允许通行。体温的正常范围由后台配置。

图片质量要求:

• 抓拍的图片中需要包含完整人脸像素

• 可根据自身设备能力选择在设备端或者边缘端完成人脸抠图处理(推荐设备端完成)

• 如果设备端进行人脸抠图,要求图片尺寸(宽、高)保证一致

• 图片分辨率不低于120 * 120 像素,大小不超过1MB

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

photo

File

disableEdgeDetectFace

String

1

参数固定为1,表示边缘服务器对图片中的人脸进行检测定位,可以提高识别准确率,但识别时间会增加。

temperature

String

36.5

通过人脸识别获取的面部体温值。默认单位为摄氏度。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

调用成功时,返回内容定义如下。

  • faceId

String

ac1c2-31a7-3**066

人脸(人员身份)的唯一标识,字符串长度最大64字节。

  • name

String

王*飞

识别的人员名字。

  • photoId

String

d8a9a-dd-**-d355

在边缘人脸照片库中,通行人员人脸照片的唯一标识。

示例

请求示例

token: "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
photo: xxx.jpg
disableEdgeDetectFace: "1"
temperature: "36.5"

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "faceId": "ac4af1c2-31a7-4206-9c8d-2a69cdaac066",
        "name": "王小飞",
        "photoId": "d8a0e59a-ddeb-11ea-a8c7-6c96cfdfd355"
    }
}

错误码

code

描述

1

人脸识别认证失败。

附录查看更多错误码

3.2 同步人脸信息(设备端识别)

边缘服务器同步人脸特征值信息到门禁机。

URL:http://[门禁机IP]:[端口]/faceAC/syncFaces
Method:POST
Content-Type:application/json

说明

当人脸数据超过50条,会被拆分为多次同步调用。每次同步最大50条,每次同步超时时间为10秒。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

faces

JSONArray

  • type

Integer

1

人脸信息操作类型,枚举如下:

  • 1:增加

  • 2:删除

  • 3:更新

  • 4:删除全部

更新操作中有三种情形:

情形一:只更新userInfo

情形二:只更新feature

情形三:userInfo和feature都更新

  • faceId

String

ac1c2-31a7-3**066

人脸(人员身份)的唯一标识,字符串长度最大64字节。

  • feature

String

人脸照片的特征值。

  • featureMd5

String

259**704

人脸照片特征值(feature)的MD5值。

  • userInfo

JSONObject

人员信息。

  • userName

String

王*飞

人员姓名。

  • expiryTime

String

1905004800000

人脸信息失效时间。以毫秒为单位,需要使用UTC时间。

  • isInBlackList

Bool

true

代表人员是否在黑名单中。

  • userInfoMd5

String

56s**sk9

人员信息(userInfo)的MD5值。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "faces":[
        {
            "type":4
        },
        {
            "type":1,
            "faceId":"452f3570-4717-4a39-910b-d72542550001",
            "userInfo":{
                "userName":"张三",
                "expiryTime":"1599892792000",
                "isInBlackList":false
            },
            "userInfoMd5":"25984f381c98bfc842280b528f424701",
            "feature":"......",
            "featureMd5":"4be6f1e4bda138a555416b866a90530c"
        },
        {
            "type":3,
            "faceId":"452f3570-4717-4a39-910b-d72542550002",
            "feature":"......",
            "featureMd5":"4be6f1e4bda138a555416b866a90530c"
        },
        {
            "type":3,
            "faceId":"452f3570-4717-4a39-910b-d72542550003",
            "userInfo":{
                "userName":"李四",
                "expiryTime":"1599892792111",
                "isInBlackList":true
            },
            "userInfoMd5":"25984f381c98bfc842280b528f424703"
        },
        {
            "type":3,
            "faceId":"452f3570-4717-4a39-910b-d72542550004",
            "userInfo":{
                "userName":"赵五",
                "expiryTime":"1599892792222",
                "isInBlackList":false
            },
            "userInfoMd5":"25984f381c98bfc842280b528f424704",
            "feature":"......",
            "featureMd5":"4be6f1e4bda138a555416b866a90530c"
        },
        {
            "type":2,
            "faceId":"452f3570-4717-4a39-910b-d72542550009"
        }
    ]
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

code

描述

0

同步成功,非0为同步失败。

附录查看更多错误码

3.3 查询设备上人脸设备库信息(设备端识别)

边缘服务器查询设备上的人脸特征值信息。

URL:http://[门禁机IP]:[端口]/faceAC/queryFaces
Method:POST
Content-Type:application/json

说明

当门禁机首次连接到边缘服务器或重新连接到边缘服务器时,获取设备上的人脸特征值存储情况,用于计算还需要同步到设备端的人脸数据。每次查询超时时间为10秒。

当人脸数量较多时,支持分页查询。边缘服务器先向设备发送全量查询请求,如果设备上的人脸数超过设备可处理的最大值,那么设备返回第1页的人脸数据和分页信息,之后边缘服务器会进行分页查询。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

currentPage

Integer

1

当前页号。

如果不传此参数,表示全量查询。设备最多返回一次可查询的最大人脸数。

pageSize

Integer

200

指定返回结果中每页的最大人脸数量。

与currentPage参数一起使用。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

  • currentPage

Integer

1

当前页号。

  • pageCount

Integer

93

总页数。

  • pageSize

Integer

200

每页的最大人脸数量。

  • total

Integer

18483

设备上的人脸总数。

  • faceInfo

JSONArray

String

ac1c2-31a7-3**066

人脸(人员身份)的唯一标识,字符串长度最大64字符。

String

259**704

人员信息(userInfo)的MD5值。

String

56s**sk9

人脸照片特征值(feature)的MD5值。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "currentPage": 1,
    "pageSize": 200
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "data": {
        "currentPage": 1,
        "pageCount": 93,
        "pageSize": 200,
        "total": 18483,
        "faceInfo": [
            [
                "452f3570-4717-4a39-910b-d72542550001",
                "25984f381c98bfc842280b528f424701",
                "4be6f1e4bda138a555416b866a90530c"
            ],
            [
                "452f3570-4717-4a39-910b-d72542550004",
                "25984f381c98bfc842280b528f424704",
                "4be6f1e4bda138a555416b866a90530c"
            ]
        ]
    }
}

错误码

code

描述

0

同步成功,非0为同步失败。

附录查看更多错误码

3.4 人脸通行事件(设备端识别)

门禁机上报通行人员识别人脸的通行事件给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/faceAC/passEvent
Method:POST
Content-Type:multipart/form-data

说明

门禁机上报通行人员刷脸成功的事件给边缘服务器,边缘服务器发送事件到云端。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

faceId

String

ac1c2-31a7-3**066

人脸(人员身份)的唯一标识,字符串长度最大64字节。

similarity

String

0.68

通行人脸照片与人脸库照片匹配的相似度。内容为0-1之间的小数,0代表匹配度最低,1代表匹配的最高。

photo

File

人员通行时抓拍的人脸照片。

temperature

String

36.5

通过人脸识别获取的面部体温值。默认单位为摄氏度。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

data

JSONObject

  • photoId

String

d8a9a-dd-**-d355

在边缘人脸照片库中,通行人员人脸照片的唯一标识。

示例

请求示例

token: "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128"
faceId: "ac4af1c2-31a7-4206-9c8d-2a69cdaac066"
photo: xxx.jpg
similarity: "0.78654"
temperature: "36.5"

正常返回示例

{
    "code": 0,
    "message": "success",
    "data":{
        "photoId": "d8a0e59a-ddeb-11ea-a8c7-6c96cfdfd355"
    }
}

错误码

code

描述

5

人脸照片内容无效

附录查看更多错误码

四、二维码

4.1 二维码识别

门禁机识别通行人员的手机二维码,向边缘服务器发起二维码识别请求。

URL:http://[边缘服务器IP]:[端口]/qrcode
Method:POST
Content-Type:application/json

说明

当有人员通行时,门禁设备向边缘服务器发起二维码识别。边缘认证成功后,返回给门禁设备允许放行,并上报通行事件。如果认证失败,返回失败结果给设备。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

qrCode

String

ALIw***xz6x

长度为32个字节。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "qrCode": "ALI1234567890azxswdfghggfgsgERTG"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

code

描述

1

二维码认证失败。

附录查看更多错误码。

五、门禁卡

5.1 同步卡权限

边缘服务器同步卡权限信息到门禁机。

URL:http://[门禁机IP]:[端口]/cardAC/syncPermissions
Method:POST
Content-Type:application/json

说明

边缘服务器接收云端下发的卡权限信息,调用此接口发送到设备端。每次同步最大200条,同步超时时间为5秒。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

permissions

List

  • type

Integer

1

门禁卡操作类型,枚举如下:

  • 1:增加

  • 2:删除

  • 3:修改

说明:对于增加和修改处理方式相同,如果该卡信息存在则对已有的卡信息做更新处理,如果该卡信息不存在则做新增处理。

  • cardId

String

777342461

门禁卡的卡号。

  • effectiveTime

String

1589472000000

门禁卡生效的时间。以毫秒为单位,需要使用UTC时间。

  • expiryTime

String

1905004800000

门禁卡过期的时间。以毫秒为单位,需要使用UTC时间。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "permissions":[
        {
            "type":1,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        },
        {
            "type":2,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        },
        {
            "type":3,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        }
    ]
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

5.2 刷卡通行事件

门禁机上报刷卡通行事件给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/cardAC/passEvent
Method:POST
Content-Type:application/json

说明

门禁机上报人员刷卡通行的事件给边缘服务器,边缘服务器发送事件到云端。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

cardId

String

777342461

门禁卡的卡号。

time

String

1591069176000

通行事件发生的历史时间,如果无此参数,表示事件发生在当前时间。

时间戳以毫秒为单位,需要使用UTC时间。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "cardId": "777342461",
    "time": "1591069176000"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

六、蓝牙

6.1 同步蓝牙权限

边缘服务器同步蓝牙权限信息到门禁机。

URL:http://[门禁机IP]:[端口]/bleAC/syncPermissions
Method:POST
Content-Type:application/json

说明

边缘服务器接收云端下发的蓝牙权限信息,调用此接口发送到设备端。每次同步最大200条,同步超时时间为5秒。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

permissions

List

  • type

Integer

1

蓝牙卡操作类型,枚举如下:

  • 1:增加

  • 2:删除

  • 3:修改

说明:对于增加和修改处理方式相同,如果该卡信息存在则对已有的卡信息做更新处理,如果该卡信息不存在则做新增处理。

  • cardId

String

777342461

蓝牙卡的卡号。

  • effectiveTime

String

1589472000000

蓝牙卡生效的时间。以毫秒为单位,需要使用UTC时间。

  • expiryTime

String

1905004800000

蓝牙卡过期的时间。以毫秒为单位,需要使用UTC时间。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "permissions":[
        {
            "type":1,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        },
        {
            "type":2,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        },
        {
            "type":3,
            "cardId":"777342461",
            "effectiveTime":"1589472000000",
            "expiryTime":"1905004800000"
        }
    ]
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

6.2 蓝牙通行事件

门禁机上报蓝牙通行事件给边缘服务器。

URL:http://[边缘服务器IP]:[端口]/bleAC/passEvent
Method:POST
Content-Type:application/json

说明

门禁机上报人员蓝牙通行的事件给边缘服务器,边缘服务器发送事件到云端。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

cardId

String

777342461

蓝牙卡的卡号。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token": "6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "cardId":"777342461"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

七、对讲

7.1 颁发门禁机Sip Number

边缘服务器同步SIP Number给门禁机。

URL:http://[门禁机IP]:[端口]/visualIntercom/syncSipNumber
Method:POST
Content-Type:application/json

说明

当云端下发的SIP账号时,边缘服务器推送SIP Number等信息给到门禁机。

每次门禁机与边缘服务器建立连接后,边缘服务器会再次同步SIP Number给门禁机。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

sipNumber

String

MNUt***CBz

连接SIP Server的账号。

password

String

pw36d5

连接SIP Server的密码。

sipServerAddr

String

47.103.*.251

SIP Server的IP地址。

sipServerPort

String

6050

SIP Server的端口。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "sipNumber": "MNUtFSr9soldjp34IxYCBz",
    "password": "pw36d5",
    "sipServerAddr": "47.103.56.251",
    "sipServerPort": "6050"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

7.2 获取GroupId

门禁机向边缘服务器查询房号的SIP组ID。

URL:http://[边缘服务器IP]:[端口]/visualIntercom/getGroupId
Method:POST
Content-Type:application/json

说明

用户输入呼叫的房号时,门禁机向边缘服务器查询房号对应的SIP group ID。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

roomId

String

1-9-3-1202

规则:期号-楼幢号-单元号-房号

例如:

1-9-3-1202

1-10-3A-1709

1-5-767-801

最大位数:1位-3位-4位-5位,规则数字+字母。

期号默认为1。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

groupId

String

4sews***HlbWkjbL

成功时,返回房号对应的SIP组ID。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "roomId": "1-9-3-1202"
}

正常返回示例

{
    "code": 0,
    "message": "success",
    "groupId": "4sewsEXT8ezMnlHlbWkjbL"
}

错误码

附录查看更多错误码

7.3 验证手机号

门禁机向边缘服务器查询房号的SIP组ID。

URL:http://[边缘服务器IP]:[端口]/visualIntercom/checkPhoneNumber
Method:POST
Content-Type:application/json

说明

由门禁机通过边缘服务器向云端发送手机号校验请求。边缘服务器返回给门禁机的结果只能表明边缘服务器是否已成功向云端发起校验请求,并不能代表校验结果。校验结果会通过“7.4 手机号校验结果”接口异步下发,因此设备需要自己处理等待校验结果超时的情况。

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

phoneNumber

String

180****5678

待校验的手机号。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "phoneNumber": "18012345678"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

7.4 手机号校验结果

云端将手机号校验结果,通过边缘服务器下发给门禁机。

URL:http://[门禁机IP]:[端口]/visualIntercom/verifyPhoneResult
Method:POST
Content-Type:application/json

说明

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

phoneNumber

String

180****5678

待校验的手机号。

result

Integer

0

校验结果,枚举如下:

  • 0:成功

  • 1:失败

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "phoneNumber": "18012345678",
    "result": 0
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

7.5 上报开门事件

门禁机向边缘服务器上报对讲开门事件。

URL:http://[边缘服务器IP]:[端口]/visualIntercom/reportOpenDoor
Method:POST
Content-Type:application/json

说明

请求参数

名称

类型

是否必选

示例值

描述

token

String

6f2a-***-128

有效连接标识。

type

Integer

0

对讲类型,枚举如下:

  • 0:云对讲

  • 1:固话对讲

number

String

MNUt***CBz

云对讲类型,值为SipNumber。

固话对讲类型,值为手机号。

roomId

String

1-9-3-1202

对讲类型为云对讲时,提供此参数。

规则:期号-楼幢号-单元号-房号

例如:

1-9-3-1202

1-10-3A-1709

1-5-767-801

最大位数:1位-3位-4位-5位,规则数字+字母。

期号默认为1。

返回参数

名称

类型

示例值

描述

code

Integer

0

调用成功时,返回0。失败时,返回的错误码。详见错误码表。

message

String

success

调用结果描述。

示例

请求示例

{
    "token":"6f2ae65e-d7f3-11ea-9a16-6c96cfdfd355-192-168-1-128",
    "type": 0,
    "number": "MNUtFSr9soldjp34IxYCBz",
    "roomId": "1-9-3-1202"
}

正常返回示例

{
    "code": 0,
    "message": "success"
}

错误码

附录查看更多错误码

附录

错误码列表:

结果码

结果说明

0

成功

success

1

识别认证错误

2

保留字段

3

保留字段

4

token失效

device is offline

5

参数错误

6

签名校验错误

verify sign error

7

设备ip地址未配置

device is illegal

99

其他错误