门禁服务器边缘网关接入API

更新时间：2020-08-11 15:58:25

传统门禁边缘解决方案>>

1、规约信息

1、通信协议基于HTTP，建立双向通道(即先由Edge端发起连接，成功后再由设备端发起， 只有双向通道都建立成功后，才能进行业务通信)。
2、访问格式：http://\:\<相对url>
3、时间字段类型：stirng-utc， 如："1502175700"
4、edge 端的服务端口：10020
5、AC: 门禁， 全称 access control

2、接口说明

2.1 通用接口

2.1.1 连接

  • 相对url: /connect

  • method: POST

  • Content-Type：application/json

  • 描述： 先有Edge端主动发起， 等连接成功后，再由门禁服务系统向边缘网关建立连接

  • 参数：

参数 类型 必选 说明 备注
sn string √ 设备sn N/A
time string-utc √ utc时间戳 例如：1502175700
ip string √ ip地址 格式：192.168.1.110
mac string √ mac地址 格式：11:22:33:44:55:66
version string 版本号 格式：xx.xx.xx
keepalive int √ 保活超时时间 单位：s,
signMethod string √ 签名算法 目前支持的有： md5/sha1/sha256
sign string √ 签名后的内容 需要签名的内容封装格式："TIME{time}MAC{mac}SN{sn}IP{ip}" 大括号内的是具体内容，其外面的是名称。备注：time要转换成string类型
  • 返回值：
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict √ 消息内容 该消息必须包含token字段，该字段的含义：连接成功后，Edge会颁发身份标示信息，在后续的“心跳包活”、“业务请求”时需要携带。

示例：
请求：

{
    "sn": "1234567890",
    "time": "123456789",
    "ip": "192.168.1.110",
    "mac": "11:22:33:44:55:66",
    "keepalive": 10,
    "signMethod": "md5",
    "sign": "sdfdgdsghgfdhfghgfhjdfj"
}

响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "234353455456"
    }
}

2.1.2 心跳

  • 相对url: /keepalive

  • method: POST

  • Content-Type：application/json

  • 描述： http clinet 端发起。每个业务通信都可当作一次心跳，只有链路出现空闲的时候，则发送心跳，若对端长时间未收到心跳，则认为设备掉线，即当前链路通道失效，需要重新做connect操作。建议心跳间隔：30s

  • 参数

参数 类型 说明 备注
token string 设备的标识信息 在建立连接时，由对端下发，在规定的时间内未收到心跳，则token失效。
  • 返回值
{
    "code": 0,
    "message": ""
}

2.2 刷卡门禁-接口

2.2.1 远程开门

  • 相对url: /cardAC/remoteOpen

  • method: POST

  • Content-Type：application/json

  • 描述： 由Edge端发起开门操作。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由门禁服务管理系统下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token": "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

2.2.2 同步刷卡门禁的权限

  • 相对url: /cardAC/syncPermissions

  • method: POST

  • Content-Type：application/json

  • 描述： 由Edge端发起权限下发操作。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由门禁服务管理系统下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
permissions list √ 权限列表
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token": "1234567890",
    "deviceId": "zxcvbnm",
    "permissions":[
        {"cardId": "门禁卡id"， "endTime": "截止时间", "type": 1}, // type 1：增加，2：删除， 3：修改 
        {"cardId": "门禁卡id"， "endTime": "截止时间", "type": 2}, // 截止时间为 UTC string 单位精确到毫秒
        {"cardId": "门禁卡id"， "endTime": "截止时间", "type": 3},
        ...
    ]
}

响应：

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

2.2.3 通行事件

  • 相对url: /cardAC/passEvent

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
cardId string √ 门禁卡ID
time string 通行事件发生时间 格式：UTC时间戳
单位：毫秒
示例："1591069176000"
注意：当此参数不存在时，边缘网关则认定通行事件发生时间为当前时间
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "cardId": "门禁卡ID"
}

响应：

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

{
   "code": 2,
   "message": "Token and deviceId should be string type"
}

{
   "code": 1,
   "message": "Token is invalid"
}

{
   "code": 7,
   "message": "Invalid device"
}

{
   "code": 99,
   "message": "Device is not online"
}

2.2.4 报警事件

  • 相对url: /cardAC/alarmEvent

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
alarmType enum √ 0: 防拆报警
1: 防拆报警解除
2: 无效卡
cardId string √ 门禁卡ID 当alarmType 的类型为2时有效
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "alarmType": 0,
}

响应：

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

2.2.5 运行状态

  • 相对url: /cardAC/runState

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。备注：connect 操作后， 运行状态默认为正常。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
runState enum √ 0: 运行正常
1: 运行异常
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

2.2.6 查询刷卡门禁的权限状态

  • 相对url: /cardAC/queryStatus

  • method: POST

  • Content-Type：application/json

  • 描述： 由边缘网关发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
cards list √ 卡号列表 详见示例
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data list √ 卡权限状态列表 详见说明及示例

说明：

  • data数组中每个元组有且只有两个字段：cardId以及status

  • status类型为字符串，具体取值如下：

    • ADD_PENDING：已下发给设备端的本地缓存，未确认权限在设备端的处理结果
    • ADD_SUCCEEDED：已确认设备端权限下发成功
    • ADD_FAILED：下发给设备端时，设备端报错，下发失败
    • DELETE_PENDING：已下发删除命令给设备端，未确认权限在设备端的处理结果
    • DELETE_SUCCEEDED：已确认设备端权限删除成功
    • DELETE_FAILED：删除设备端权限时，设备端报错，删除失败

示例
请求：

{
  "token": "1234567890",
  "deviceId": "zxcvbnm",
  "cards":[
    "ABCD1001", "ABCD1002"
  ]
}

响应：

{
  "code": 0,
  "message": "",
  "data": [
    {
      "cardId": "ABCD1001",
      "status": "ADD_PENDING"
    },
    {
      "cardId": "ABCD1002",
      "status": "ADD_SUCCEEDED"
    }
  ]
}

2.2.7 刷卡门禁的权限状态上报

  • 相对url: /cardAC/syncStatus

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务器发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
permissions list √ 卡权限状态列表 详见说明和示例
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息

说明：

  • permissions数组中每个元组有且只有两个字段：cardId以及status

  • status类型为字符串，具体取值如下：

    • ADD_PENDING：已下发给设备端的本地缓存，未确认权限在设备端的处理结果
    • ADD_SUCCEEDED：已确认设备端权限下发成功
    • ADD_FAILED：下发给设备端时，设备端报错，下发失败
    • DELETE_PENDING：已下发删除命令给设备端，未确认权限在设备端的处理结果
    • DELETE_SUCCEEDED：已确认设备端权限删除成功
    • DELETE_FAILED：删除设备端权限时，设备端报错，删除失败

示例
请求：

{
  "token": "1234567890",
  "deviceId": "zxcvbnm",
  "permissions": [
    {
      "cardId": "ABCD1001",
      "status": "ADD_SUCCEEDED"
    },
    {
      "cardId": "ABCD1002",
      "status": "ADD_FAILED"
    }
  ]
}

响应：

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

2.3 密码门禁-接口

2.3.1 远程开门

  • 相对url: /passwordAC/remoteOpen

  • method: POST

  • Content-Type：application/json

  • 描述： 由Edge端发起开门操作。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由门禁服务管理系统下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token": "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

2.3.2 密码设置

  • 相对url: /passwordAC/setPassword

  • method: POST

  • Content-Type：application/json

  • 描述： 由Edge端发起密码操作。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由门禁服务管理系统下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
operateType enum √ 0: 设置密码
1: 删除密码
number int √ 密码编号
password string 密码 设置密码时，该参数有效
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "operateType": 0,
    "number": 123,
    "password": "密码"
}

响应：

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

2.3.3 请求通行

  • 相对url: /passwordAC/reqPass

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
number int √ 密码编号
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "number": 123
}

响应：

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

2.3.4 报警事件

  • 相对url: /passwordAC/alarmEvent

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
alarmType enum √ 0: 防拆报警
1: 防拆报警解除
2: 挟持报警
3: 挟持报警解除
4: 三次密码错误报警
5: 三次密码错误报警解除
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "alarmType": 0,
}

响应：

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

2.3.5 运行状态

  • 相对url: /passwordAC/runState

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。备注：connect 操作后， 运行状态默认为正常。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
runState enum √ 0: 运行正常
1: 运行异常
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

2.4 二维码门禁-接口

2.4.1 远程开门

  • 相对url: /qrCodeAC/remoteOpen

  • method: POST

  • Content-Type：application/json

  • 描述： 由Edge端发起开门操作。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由门禁服务管理系统下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token": "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

2.4.2 请求通行

  • 相对url: /qrCodeAC/reqPass

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
qrCode string √ 二维码
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "qrCode": "二维码"
}

响应：

{
    "code": 0,
    "message": "",
    "data":{
        "state": 1   // 0 二维码比对失败，1，二维码比对成功
    }
}

{
    "code": 5,
    "message": "",
    "data":{
        "state": 0   // 0 二维码比对失败，1，二维码比对成功
    }
}

2.4.3 报警事件

  • 相对url: /qrCodeAC/alarmEvent

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
alarmType enum √ 0: 防拆报警
1: 防拆报警解除
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
    "alarmType": 0,
}

响应：

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

2.4.4 运行状态

  • 相对url: /qrCodeAC/runState

  • method: POST

  • Content-Type：application/json

  • 描述： 由门禁服务发起。备注：connect 操作后， 运行状态默认为正常。

  • 参数

参数 类型 必选 说明 备注
token string √ 设备的标识信息 在建立连接时，由edge下发，在规定的时间内未收到心跳，则token失效。
deviceId string √ 设备ID
runState enum √ 0: 运行正常
1: 运行异常
  • 返回值
参数 类型 必选 说明 备注
code int √ 返回值
message string √ 返回消息
data dict 消息内容

示例
请求：

{
    "token" : "1234567890",
    "deviceId": "zxcvbnm",
}

响应：

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

3、错误码表

错误码 说明
0 成功
1 token无效
2 请求参数无效或非法
3 验签失败
4 权限失效
5 无权限
6 传统门禁系统身份无法识别
7 门禁设备身份无法识别
99 未知错误

4、文档发布历史

v1.1.0 2019-06-02

  • 【增加】刷卡通行事件API中，请求报文增加一个可选的参数用于标识事件发生时间。

v1.0.0 2019-08-30

  • 门禁服务器对接API初始版本。

results matching ""

    No results matching ""