HTTP对接

会员卡功能

接口说明:

写扇区块数据

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartWriteCardBlock

参数:

参数名层级必选类型说明备注
blockNo1int块号--
data1String数据--
keyA1StringkeyA--

请求示例

{
	"method": "openSmartWriteCardBlock",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"blockNo": 5,
		"data":"478354345465",
		"keyA":"FFFFFFFFFFFF"
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartWriteCardBlock",
	"data": {
	}
}

响应参数说明

异常码

异常码异常描述

接口说明:

激活卡片

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartActiveCard

参数:请求示例

{
	"method": "openSmartActiveCard",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartActiveCard",
	"data": {
	"cardNo":"DB730487"
	}
}

响应参数说明

参数名层级必选类型说明备注
cardNo1String卡号--
异常码
异常码异常描述

接口说明:

设置卡片扇区密钥

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartSetCardKey

参数:

参数名层级必选类型说明备注
keyA1String密钥A--
sectorNo1int扇区1-40

请求示例

{
	"method": "openSmartSetCardKey",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"keyA": "FFFFFFFFFFFF",
		"sectorNo":3
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartSetCardKey",
	"data": {
	}
}

响应参数说明

异常码

异常码异常描述

接口说明:

读卡号

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartReadCardNo

参数:请求示例

{
	"method": "openSmartReadCardNo",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartReadCardNo",
	"data": {
	"cardNo":"DB730487"
	}
}

响应参数说明

参数名层级必选类型说明备注
cardNo1String卡号--
异常码
异常码异常描述

接口说明:

读扇区块数据

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartReadCardBlock

参数:

参数名层级必选类型说明备注
blockNo1int块号--
keyA1StringkeyA--

请求示例

{
	"method": "openSmartReadCardBlock",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"blockNo": 5,
		"keyA":"FFFFFFFFFFFF"
		}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartReadCardBlock",
	"data": {
	"data":"4567654343567843"
	}
}

响应参数说明

异常码

异常码异常描述

接口说明:

验证卡片扇区密钥

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

业务能力:

  • openSmartAuthCardKey

参数:

参数名层级必选类型说明备注
keyA1String密钥A--
sectorNo1int扇区1-40

请求示例

{
	"method": "openSmartAuthCardKey",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"keyA": "FFFFFFFFFFFF",
		"sectorNo":3
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAuthCardKey",
	"data": {
	}
}

响应参数说明

异常码

异常码异常描述

|时间|内容摘要|作者|接口版本|本地服务器版本| |:---- |:---| |2020-12-15|增加开放接口:关联发卡器、授权离线密码钥匙、授权手机钥匙、离线发卡、修改授权到期时间、取消授权、回收卡片、读卡|zzy|V1.0|V1.4.1| |2020-12-30|增加开放接口:设置回调地址、下发卡片、指纹下发|zzy|V1.0|V1.4.5| |2021-01-05|增加开放接口:远程开锁|zzy|V1.0|V1.4.6| |2021-01-22|增加开放接口:待处理入住列表、入住详情、重新下发待处理授权、忽略待处理授权|zzy|V1.0|V1.8.0| |2021-04-15|增加开放接口:退房卡|zzy|V1.0|V1.9.0| |2021-07-15|房间列表返回房间状态|zzy|V1.0|V2.1.0| |2022-11-18|增加房间入住列表同步|zzy|V1.0|V2.3.0| |2023-02-27|下发卡号增加授权通道锁|zzy|V1.0|V2.4.0| |2023-03-15|1.新增图片处理接口
2.新增下发人脸
3.房间入住列表返回Base64图片数据
4.房间入住详情返回Base64图片数据
5.待处理入住列表筛选加二维码、人脸下发|zzy|V1.0|V2.5.0| |2023-06-20|1.房间操作记录列表增加事件开始时间和事件结束时间查询|zzy|V1.0|V2.7.0|

接入说明

必须先把HTLock部署完成。

联系门锁供应商提供账号文件。 然后把账号、卡片等文件导入到HTLock本地系统上。 然后使用注册好的账号对接口进行鉴权,调接口的时候需要注意接口协议

设置回调地址,该地址在网关上报门锁日志时,会推送到该地址设置回调地址。除了门锁日志,还有删除网关的通知、删除门锁的通知、网关下发指纹、人脸的进度和结果通知,都会推送到该地址。

  • ##HTLock添加房源、安装门锁等操作视频

  • 远程操作

完成以上操作后,就可以对门锁调用远程功能API,HTTP接口功能如下: 房间列表查询 授权离线密码 授权手机 下发卡片 远程开锁 房间操作记录 房间入住列表 待处理列表 入住详情

在离线发卡之前需要先在该账号下关联发卡器。 关联成功后把卡片放在发卡器上,调离线发卡接口即可完成发卡操作。 注意:需要退房的时候要把卡片回收后才能继续使用,防止卡片里面的数据发生错误。

想对客户进行续住处理的话可以调修改授权有效期接口进行修改。 注意1:该接口只支持对离线卡片和手机授权进行续住。 注意2:离线卡片需要把卡片放在关联的发卡器上才能完成续住。 注意3:房间封房状态不能进行续住。

在制作多门卡之前需要先在该账号下关联发卡器。 关联成功后把卡片放在发卡器上,调制作多门卡接口即可完成发卡操作。 注意:需要退房的时候要把卡片回收后才能继续使用,防止卡片里面的数据发生错误。

在下发指纹之前需要先在该账号下关联发卡器。 关联成功后需要调发卡器录入指纹模式接口,然后方手指上去进行按压。 按压过程中可以通过回调地址查看到发卡器按压指纹推送。 在推送中拿到指纹标识或指纹特征值给到指纹下发接口进行下发,下发结果可以在回调地址上查看下发指纹结果推送。 注意:发卡器按压指纹的时候只有最后一包才会有指纹标识和指纹特征值推送。

把需要下发的人脸转换成baes64编码,然后调我们的图片处理接口对编码进行处理。 拿到图片处理返回的baes64编码后调下发人脸接口进行下发,下发的结果会通过下发人脸结果通知传到回调地址上。

调用前提是需要在HTLock上先安装梯控,安装完毕后即可调梯控授权

根据业务需求可以分为单个退房和全部退房,这个只需要调取消权限接口即可。 注意:单个退房需要传checkInId参数,该参数可以通过房间入住列表拿到。

接口API

个性化接口

接口说明:

  • 手动续住

业务能力:

  • openSmartExtensionManually

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
pmsRoomName1String必填续住房号--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String必填证件号最大支持100个字符
endTime1int必填结束时间时间戳,单位秒
*list1list必填公共区列表--
pmsRoomName2String必填公共区房号--
addUseNum2int必填增加有效使用次数续住时,新增的使用次数,和剩余的使用次数,总共不能超过254次
endTime2int必填结束时间时间戳,单位秒

请求示例


响应示例


响应参数说明

异常码

异常码异常描述
500001参数异常
500002房间不存在

接口说明:

  • 手动入住

业务能力:

  • openSmartCheckInManually

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
pmsRoomName1String必填入住房号--
customerName1String必填房客名称最大支持100个字符
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String必填证件号最大支持100个字符
countryCode1int可选国家编码如:中国大陆为86
phoneNo1String可选手机号--
beginTime1int必填开始时间时间戳,单位秒
endTime1int必填结束时间时间戳,单位秒
*list1list可选公共区列表--
pmsRoomName2String必填公共区房号--
useNum2int必填有效使用次数addMode=1时有效
0 表示无限次
其他值,最大支持254
不填则默认无限次
beginTime2long必填开始时间时间戳,单位秒
endTime2long必填结束时间时间戳,单位秒
roomState1int可选房间状态本地系统处理完该入住信息后,房间更变的状态
2在住
不填则使用系统默认的逻辑:处理完成后,房间置为在住状态
请求示例
{
    "method": "openSmartCheckInManually",
 "tokenId":"aFqJ9GbjlmX0LHZosmciPOtAbLZe/bfB00uEVTLGOGDpjnI9E6qwh7GmacRpAS4MIjKs1qK1BLnAHFBfNrKTxQ==",
    "data": {
        "pmsRoomName": "测试酒店5",
        "customerName": "张三",
        "idType":1,
        "idNumber":"123456",
        "countryCode":86,
        "phoneNo":18900000000,
        "beginTime":1592206742,
        "endTime":1592465942,
        "list":[
            {
                "pmsRoomName":"PMS公共区1",
                "useNum":3,
                "beginTime":1592206885,
                "endTime":1592293284
            },
            {
                "pmsRoomName":"PMS公共区2",
                "useNum":5,
                "beginTime":1592206885,
                "endTime":1592293284
            },
            {
                "pmsRoomName":"PMS公共区3",
                "useNum":9,
                "beginTime":1592206885,
                "endTime":1592293284
            }
        ]
    }
}

响应示例

{
    "msgId":23011359,
    "resultCode":0,
    "reason":"",
    "method":"openSmartCheckInManually",
    "data":{
    }
}

响应参数说明

异常码

异常码异常描述
500001参数异常
500002房间不存在

接口说明:

  • 手动退房

业务能力:

  • openSmartCheckOutManually

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
pmsRoomName1String必填退房房号--
customerName1String可选房客名称最大支持100个字符
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String必填证件号最大支持100个字符
roomState1int可选房间状态本地系统处理完该退房信息后,房间更变的状态
1空净
5打扫
不填则使用系统默认的状态,该状态也可在WEB管理端上设置
请求示例
{
    "method": "openSmartCheckOutManually",
    "tokenId":"aFqJ9GbjlmX0LHZosmciPOtAbLZe/bfB00uEVTLGOGDpjnI9E6qwh7GmacRpAS4MIjKs1qK1BLnAHFBfNrKTxQ==",
    "data": {
        "pmsRoomName": "测试酒店5",
        "idType":1,
        "idNumber":"123456",
        "roomState":1
    }
}

响应示例

{
    "msgId":106659885,
    "resultCode":0,
    "reason":"",
    "method":"openSmartCheckOutManually",
    "data":{
    }
}

响应参数说明

异常码

异常码异常描述
500001参数异常
500002房间不存在

接口说明:

  • 关联发卡器
  • 关联发卡器时,必须保证发卡器在线
  • 发卡器未被关联使用

业务能力:

  • openSmartBindCredit

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
deviceSeq1String可选发卡器序列号为空,表示解除绑定发卡器
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPy+g==",
	"method": "openSmartBindCredit",
	"data": {
		"deviceSeq": "xxxxxxxxxxxx"
	}
}

响应示例

{
	"msgId": 1620971530,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartBindCredit",
	"data": {}
}

响应参数说明

异常码

异常码异常描述
500213未导入包含当前发卡器文件,请联系供应商处理
500214发卡器已被{0}端关联使用,请选择其他发卡器
500215发卡器不在线

卡片操作

接口说明:

  • 制作多门卡

业务能力:

  • openSmartMultiLockCard

本地服务器版本:

  • V2.9.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件说明备注
multiLockCardId1String可选多门卡ID此参数不为空以下参数可不填
需要挂失的卡片
endDate1long必填结束时间时间戳:秒
remark1string必填持卡人
isLock1int可选是否可开反锁0不允许
1允许
默认不允许
replaceFunction1int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods1list可选可开时间段最多设置2个
beginTime2String可选时间段开始时间格式:HH:mm,如10:03
endTime2String可选时间段结束时间格式:HH:mm,如10:03
floorCode2int必填楼层号--
roomCode2int必填房间号--
subRoomName2String可选套房号--
云端发布Pub(示例):
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QcPyLjF+g==",
	"method": "openSmartMultiLockCard",
    "data": {
        "isLock": 1,
        "replaceFunction": 1,
        "endDate": 1763222399,
		"remark": "xxx",
        "timePeriods": [
            {
                "beginTime": "09:00",
                "endTime": "18:00"
            },
            {
                "beginTime": "19:00",
                "endTime": "20:00"
            }
        ],
        "list": [
            {
                "buildingCode": 1,
                "floorCode": 9,
                "roomCode": 901,
                "subRoomName":"A"
            },
            {
                "buildingCode": 1,
                "floorCode": 9,
                "roomCode": 902
            }
        ]
    }
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"msgId": 345981978,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartMultiLockCard",
	"data": {
	}
}

接口说明:

  • 多门卡列表

业务能力:

  • openSmartMultiLockCardList

本地服务器版本:

  • V2.9.0

Content-Version:

  • 1.0
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QcPyLjF+g==",
	"method": "openSmartMultiLockCardList",
	"data": {
		"startNum":0,
		"getNum":10
	}
}
响应参数说明:
参数名层级类型条件描述备注
totalPages1int必填总页数
multiLockCardId2String必填多门卡ID
cardNo2String必填卡号
remark2String必填持卡人
endDate2long必填结束时间时间戳:秒
isLock2int可选是否可开反锁0不允许
1允许
默认不允许
replaceFunction2int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods2List可选可开时间段最多设置2个
beginTime3String可选时间段开始时间格式:HH:mm,如10:03
endTime3String可选时间段结束时间格式:HH:mm,如10:03
buildingCode3int必填楼栋号
roomCode3int必填房间号
subRoomName3String可选套房号
roomCardState3int必填房间卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
createTime2Long必填创建时间时间戳:秒
边缘网关响应Sub(示例):
{
	"method": "openSmartMultiLockCardList",
	"msgId": 122321323,
	"resultCode": 0,
	"reason": "",
	"data": {
		"listSum": 总数,
		"totalPages":总页数,
		"list":[
			{
				"cardNo":21D4CBFD,
				"endDate":1700035797,
				"isLock":1,
				"remark":"xxx",
				"createTime":1700035797,
				"list":[
					{
						"buildingCode":1,
						"floorCode":1,
						"roomCode":109,
						"subRoomName":"A"
					}
				]
			}
		]
	}
}

房间操作

接口说明:

  • 下发卡片
  • 发卡器读取卡号,调用此接口通过网关将卡号下发到门锁
  • 房间封房状态不能下发卡片
1.需要将卡片放入关联的发卡器
2.门锁绑定网关

业务能力:

  • openSmartDownSendCardKey

本地服务器版本:

  • V1.4.5

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:HH:mm
dayEndTimes1String可选每日结束时间格式:HH:mm
useNum1int可选使用次数不填或0表示无限次
限制次数,最大是254次

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartDownSendCardKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartDownSendCardKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231",
		"cardNo": "DB730487"
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:01:00
dayEndTimes1String可选每日结束时间格式:02:00
useNum1int使用次数每日结束时间不填或255表示无限次
限制次数,最大是254次
cardNo1String必填卡号--

异常码

异常码异常描述
500001参数异常
500204门锁不支持该功能
500209未绑定发卡器
500300房间不存在
500403未读取到卡片信息
500503重复授权
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 下发卡片
  • 如传入参数中,cardNo不为空,则下发该卡号;如果为空,则通过发卡器读取卡号。再调用此接口通过网关将卡号下发到门锁
  • 房间封房状态不能下发卡片
1.卡号为空时,需要将卡片放入关联的发卡器
2.门锁绑定网关

业务能力:

  • openSmartDownSendCardKey

本地服务器版本:

  • V1.5.4

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
如若该门锁号为门禁时,只能选1和2。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:HH:mm
dayEndTimes1String可选每日结束时间格式:HH:mm
useNum1int使用次数每日结束时间不填或0表示无限次
限制次数,最大是254次
cardNo1String可选卡号16进制卡号。调试时,请参考发卡器读出的卡号。如果卡号为空,则取发卡器读取的卡号下发,1.5.4版本新增
authChannel1int可选授权通道0或空 不授权通道锁
1 授权通道锁(不存在通道锁不会授权)
服务器2.4.0版本新增
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.9.0新增

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartDownSendCardKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"cardNo":"DB730487"
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartDownSendCardKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231",
		"cardNo": "DB730487"
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:01:00
dayEndTimes1String可选每日结束时间格式:02:00
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
cardNo1String必填卡号--
auth1list可选授权详情服务器2.4.0版本新增
relaId2String必填联动授权关系ID
channelType2Int必填通道类型5大门
6楼栋
7楼层
8房间
9套房
roomName2String必填房间名称
state2int必填状态1已入住
2待下发退房
3待下发入住
4挂失
5待下发挂失
6待下发续住
sendStatus2int必填状态1成功
2下发失败
3下发中
password2String可选密码authType=2 表示为密码 AES加密
authType=4表示为卡片
useNum2int可选使用次数255或空表示无限次
限制次数,最大是254次

异常码

异常码异常描述
500001参数异常
500204门锁不支持该功能
500209未绑定发卡器
500300房间不存在
500403未读取到卡片信息
500503重复授权
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 下发自定义密码
  • 房间封房状态不能下发密码
1.门锁绑定网关

业务能力:

  • openSmartDownSendPasswordKey

本地服务器版本:

  • V3.2.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
password1String必填密码6~16位数字
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
如若该门锁号为门禁时,只能选1和2。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:HH:mm
dayEndTimes1String可选每日结束时间格式:HH:mm
useNum1int使用次数每日结束时间不填或0表示无限次
限制次数,最大是254次
authChannel1int可选授权通道0或空 不授权通道锁
1 授权通道锁(不存在通道锁不会授权)
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartDownSendPasswordKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"password":"123456"
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartDownSendCardKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231",
		"password": "123456"
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
authorMode1int可选有效期授权方式1:有效期授权
2:周期重复时间段授权
默认为1
weeks1int可选星期数AuthorMode = 0x02有效
按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效
例如:二进制1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:01:00
dayEndTimes1String可选每日结束时间格式:02:00
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
cardNo1String必填卡号--
auth1list可选授权详情服务器2.4.0版本新增
relaId2String必填联动授权关系ID
channelType2Int必填通道类型5大门
6楼栋
7楼层
8房间
9套房
roomName2String必填房间名称
state2int必填状态1已入住
2待下发退房
3待下发入住
4挂失
5待下发挂失
6待下发续住
sendStatus2int必填状态1成功
2下发失败
3下发中
password2String可选密码authType=2 表示为密码 AES加密
authType=4表示为卡片
useNum2int可选使用次数255或空表示无限次
限制次数,最大是254次

异常码

异常码异常描述
500001参数异常
500204门锁不支持该功能
500209未绑定发卡器
500300房间不存在
500403未读取到卡片信息
500503重复授权
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 人脸下发
  • Base64数据必须从图片处理获取
  • 人脸下发结果通过回调地址推送给第三方
  • 房间封房状态不能人脸下发
1.门锁绑定网关,门锁和网关都需要支持人脸下发
2.人脸下发结果通过hxjGatewaySendKeyResultPush推送给第三方

业务能力:

  • openSmartDownSendFaceKey

本地服务器版本:

  • V2.5.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
如若该门锁号为门禁时,只能选1和2。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
picture1String必填Base64编码图片必须经过“图片处理接口”获取

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartDownSendFaceKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"picture":"sxcvxvxzcvdfasdfs="
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartDownSendFaceKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231"
		"state":3
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
state1int必填状态1 已入住
3 待下发入住

异常码

异常码异常描述
500001参数异常
500201网关不存在
500204门锁不支持该功能
500207门锁未绑定网关
500300房间不存在
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 人脸识别授权
  • 房间门锁需要绑定人脸识别机
  • 房间封房状态不能人脸授权
  • 人脸图片只支持JPG格式
  • 建议图片小于800KB,以免授权失败

业务能力:

  • openSmartAddFaceKey

本地服务器版本:

  • V2.1.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
picture1String必填人脸图片Base64编码

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartAddFaceKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"picture":"xxxxxxxxxxxxx="
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddFaceKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231"
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒

异常码

异常码异常描述
500001参数异常
500300房间不存在
500228门锁未绑定人脸识别机
500530未开启该功能
500221人脸识别机不存在
501Send msg error(此异常一般图片过大)
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 发卡器进入录指纹模式
  1. 发卡器按压指纹,通过回调推送结果通知给第三方(hxjGatewaySendKeyResultPush)

业务能力:

  • openSmartEnterFingerPrintModel

本地服务器版本:

  • V1.5.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
------------

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartEnterFingerPrintModel",
	"data": {
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartEnterFingerPrintModel",
	"data": {
	}
}

响应参数说明

参数名层级类型条件描述备注
------

异常码

异常码异常描述
500208发卡器不存在
500209未绑定发卡器
500232帐号关联的发卡器没有指纹采集功能,请重新关联发卡器!

接口说明:

  • 取消权限,即退房(单个退房、全部退房)
对单个离线卡片授权退房,将卡片放入关联的发卡器则为有卡退房否则为无卡退房

业务能力:

  • openSmartCheckOut

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号--
checkInId1String可选入住ID不为空则表示对单个房客退房
为空则表示全部退房
可通过房间入住列表查看
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.9.0新增
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartCheckOut",
	"data": {
		"lockCode": "1.2.201A"
	}
}

响应示例

{
	"msgId": 614462509,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartCheckOut",
	"data": {}
}

响应参数说明

参数名层级类型条件描述备注
roomState1int可选房间状态--

异常码

异常码异常描述
500001参数异常
500300房间不存在
500529操作失败,多门卡请在侧边栏操作
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 回收卡片 必须关联发卡器,且发卡器在线

业务能力:

  • openSmartCardRecycle

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartCardRecycle",
	"data": {
	}
}

响应示例

{
	"msgId": 43943955,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartCardRecycle",
	"data": {}
}

响应参数说明

异常码

异常码异常描述
500209未绑定发卡器
500403未读取到卡片信息

接口说明:

  • 图片处理
  • 下发人脸时,图片数据必须较过此接口校验通过获取

业务能力:

  • openSmartFaceImageUpload

本地服务器版本:

  • V2.5.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
picture1String必填Base64编码图片--
lockCode1String可选门锁号V2.7.5新增
可通过房间列表查看

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartFaceImageUpload",
	"data": {
		"picture":"xcvawesdfsadfsdad"
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartFaceImageUpload",
	"data": {
		"picture":"xcvawesdfsadfsdad"
	}
}

响应参数说明

参数名层级类型条件描述备注
picture1String必填Base64数据--

异常码

异常码异常描述
500001参数异常

接口说明:

  • 忽略待处理授权

业务能力:

  • openSmartIgnoreCheckIn

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

参数:

| 参数名 | 层级 | 类型 | 条件 | 说明 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||checkInId| 1| String | 必填 | 授权ID|可通过房间入住列表查看|

请求示例

{
    "method": "openSmartIgnoreCheckIn",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdnUOGWhdPWCSQzJiLVdYT4iqybECMEoq8Nx1GU2tCGVkCZMcrLk7kUQ==",
    "data": {
        "checkInId": "+LD/tJysceg="
    }
}

响应示例

{
	"msgId": 1527377926,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartIgnoreCheckIn",
	"data": {
	}
}

响应参数说明:

参数名层级类型条件描述备注
------------

异常码

异常码异常描述
500001参数异常
500506入住信息不存在

接口说明:

  • 指纹下发
  • 指纹下发结果通过回调地址推送给第三方
  • 房间封房状态不能指纹下发
1.指纹采集仪读取指纹
2.门锁绑定网关,门锁和网关都需要支持指纹下发
3.指纹下发结果通过hxjGatewaySendKeyResultPush推送给第三方

业务能力:

  • openSmartAddFingerPrintKey

本地服务器版本:

  • V1.4.5

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.5版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
如若该门锁号为门禁时,只能选1和2。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
fingerPrint1String可选指纹特征本地服务器V1.5.1版本及之后:
fingerPrint和fingerPrintSign二者必填其一

获取方式:
(1)第三方对接指纹采集仪,获取指纹特征
(2)发卡器录入指纹成功,推送发卡器按压指纹推送通知(hxjUploadFingerPrintNumPush)获取
fingerPrintSign1String可选指纹标识本地服务器V1.5.1版本新增字段:
fingerPrint和fingerPrintSign二者必填其一

获取方式:
发卡器录入指纹成功,推送发卡器按压指纹推送通知(hxjUploadFingerPrintNumPush)获取

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartAddFingerPrintKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"fingerPrint":"qweqweqwwetewtwertwrtwaaaaaaa="
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddFingerPrintKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231"
		"state":3
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
state1int必填状态1 已入住
3 待下发入住

异常码

异常码异常描述
500001参数异常
500201网关不存在
500204门锁不支持该功能
500207门锁未绑定网关
500300房间不存在
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 授权手机钥匙
  • 房间封房状态不能授权手机钥匙
需要设置支持APP和小程序授权

业务能力:

  • openSmartAddPhoneKey

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.1版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
phoneNo1String可选手机号码1.邮箱或手机号码必填其一
2.高级功能设置需要开启APP授权(手机号) 或微信授权(手机号,此参数有效)
email1String可选邮箱1.邮箱或手机号码必填其一
2.高级功能设置需要开启APP授权(邮箱),此参数有效)
3.V2.7.5新增
countryCode1int可选国家编码默认为86
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QcPyLjF+g==",
	"method": "openSmartAddPhoneKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":1,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958,
		"phoneNo":"13515455351"
	}
}

响应示例

{
	"msgId": 345981978,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddPhoneKey",
	"data": {
		"checkInId": "IUMAVJK/7yI=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231",
		"phoneNo": "13535455351",
		"countryCode": 86
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100字符
beginTime1long必填开始时间时间戳:单位秒
endTime1long必填结束时间时间戳:单位秒
phoneNo1String必填手机号码--
countryCode1int可选国家编码--

异常码

异常码异常描述
500001参数异常
500104手机号码格式错误
500300房间不存在
500503重复授权
500504不支持该功能
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 1、如果密码的有效期小于1年,密码的有效期,精确到小时 如: 开始时间:2019-06-21 11:16:14 结束时间:2019-06-21 13:16:14 那么有效时间为:2019-06-21 11:00:00---2019-06-21 13:00:00
  • 2、如果密码的有效期大于1年,密码的有效期精确到月 如: 开始时间:2019-06-21 11:16:14 结束时间:2020-09-21 11:16:14 那么有效时间为:2019-06-01 00:00:00---2020-09-01 00:00:00

如果密码开不了锁,在三方面进行排查 1、门锁时间是否正确(通过同步门锁时间来解决) 2、生成密码的aesKey、鉴权码是否和门锁上的一致(门锁初始化后,aesKey和鉴权码都会重新生成) 3、同一个时间生成的第一个密码输入可以开门,删除后再次相同开始结束时间生成的密码是无法开门的

  • 授权离线密码钥匙 限制:
  • 有效时间不能超过3年
  • 有效时间超过1年,精确到月;有效时间小于1年,精确到小时
  • 房间封房状态不能授权离线密码钥匙

业务能力:

  • openSmartAddOffLineKey

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称--
copyCheckIn1int必填复制入住本地服务器V1.4.1版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
如若该门锁为门禁时,只能选1和2。
房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLLjF+g==",
	"method": "openSmartAddOffLineKey",
	"data": {
		"lockCode": "1.1.103",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1603265958,
		"endTime":1608265958
	}
}

响应示例

{
	"msgId": 2107619328,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddOffLineKey",
	"data": {
		"checkInId": "vKucPeOPw54=",
		"checkInName": "zzy",
		"beginTime": 1603263600,
		"endTime": 1608265958,
		"idType": 1,
		"idNumber": "1231231",
		"password": "ryizXPc1I8ZNzusrM8MnMw=="
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1long必填开始时间时间戳:单位秒
endTime1long必填结束时间时间戳:单位秒
password1String必填密码AES加密

异常码

异常码异常描述
500001参数异常
500300房间不存在
500316房间未关联门锁
500508PMS入住不允许直接退房,请前往PMS页面操作

接口说明:

  • 梯控二维码
  • 楼栋安装了梯控,调用此接口生成二维码授权,梯控扫码可到达对应楼层
  • 梯控二维码生成后1小时内有效

业务能力:

  • openSmartElevatorQrCode

本地服务器版本:

  • V2.1.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
list1List必填list最多10层,允许为不同楼栋
buildingCode2int必填楼栋码--
floorCode2int必填楼层--

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartElevatorQrCode",
	"data": {
		"list":[
			{
				"buildingCode":1,
				"floorCode":2
			},
			{
				"buildingCode":2,
				"floorCode":4
			}
		]
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartElevatorQrCode",
	"data": {
		"qrCode":"xxxxxxx=",
		"createTime":1623313206
	}
}

响应参数说明

参数名层级类型条件描述备注
qrCode1String必填梯控数据--
createTime1long必填创建时间时间戳 单位:秒

异常码

异常码异常描述
500001参数异常
500002生成失败

接口说明:

  • 离线发卡
  • 房间封房状态不能授权离线发卡
需要将卡片放入关联的发卡器

业务能力:

  • openSmartAddCardKey

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看
customerName1String必填房客名称1.6.1版本,改为可选,当为空时, 默认取卡号为房客名
copyCheckIn1int必填复制入住本地服务器V1.4.1版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
1.房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
2.房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
isLock1int可选是否允许开反锁1.6.1版本新增字段:0不允许开反锁,1允许开反锁,不填默认为0
floorList1list可选可开楼层2.7.3新增
floorCode2int可选楼层码2.7.3新增
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartAddCardKey",
	"data": {
		"lockCode": "1.2.201A",
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddCardKey",
	"data": {
		"checkInId": "h0JYf4V93p4=",
		"checkInName": "zzy",
		"beginTime": 1602165600,
		"endTime": 1608965958,
		"idType": 1,
		"idNumber": "1231231",
		"cardNo": "DB730487"
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号--
beginTime1int必填开始时间时间戳:单位秒
endTime1int必填结束时间时间戳:单位秒
cardNo1String必填卡号--

异常码

异常码异常描述
500001参数异常
500209未绑定发卡器
500300房间不存在
500400非法卡片
500402卡片已使用,请回收后再制卡
500403未读取到卡片信息
500503重复授权
500508PMS入住不允许直接操作,请前往PMS页面操作

接口说明:

如果密码开不了锁,在三方面进行排查 1、门锁时间是否正确(通过同步门锁时间来解决) 2、生成密码的aesKey、鉴权码是否和门锁上的一致(门锁初始化后,aesKey和鉴权码都会重新生成) 3、同一个时间生成的第一个密码输入可以开门,删除后再次相同开始结束时间生成的密码是无法开门的

  • 离线发卡
  • 房间封房状态不能授权离线发卡
  • 最多选择4个房间
需要将卡片放入关联的发卡器

业务能力:

  • openSmartAddCardKey

本地服务器版本:

  • V3.2.0

Content-Version:

  • 1.1

参数:

参数名层级类型条件描述备注
lockCodes1list<String>必填门锁号最多选择4个
可通过房间列表查看
customerName1String必填房客名称1.6.1版本,改为可选,当为空时, 默认取卡号为房客名
copyCheckIn1int必填复制入住本地服务器V1.4.1版本:
0 不复制入住,开始时间取推送过来入住的当前时间,且对房间做退房逻辑
1 复制入住,存在房客入住以房客最早开始时间为准

本地服务器V1.5.0版本:
0 退房后入住
先将对应房源内的所有房客退房(删除授权)再入住(执行当前的新授权),取入参开始时间作为本次入住授权的起始时间(时间精度为小时)
1 立即入住
不删除对应房源内的原有授权,以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取当前时间作为本次入住授权的开始时间(时间精度为小时)
2 其他时间入住
不删除对应房源内的原有授权,取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
1.房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
2.房间开启顶替的情况下,该接口只能选0进行入住。
idType1int可选证件类型1身份证
2护照
9其他
idNumber1String可选证件号最大支持100个字符
beginTime1long必填开始时间时间戳,单位秒
endTime1long必填结束时间时间戳,单位秒
isLock1int可选是否允许开反锁1.6.1版本新增字段:0不允许开反锁,1允许开反锁,不填默认为0
floorList1list可选可开楼层2.7.3新增
floorCode2int可选楼层码2.7.3新增
请求示例
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartAddCardKey",
	"data": {
		"lockCodes": ["1.2.201A","1.2.210"],
		"customerName":"zzy",
		"copyCheckIn":0,
		"idType":1,
		"idNumber":"1231231",
		"beginTime":1602165958,
		"endTime":1608965958
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartAddCardKey",
	"list": [
		{
			"checkInId": "h0JYf4V93p4=",
			"checkInName": "zzy",
			"beginTime": 1602165600,
			"endTime": 1608965958,
			"idType": 1,
			"idNumber": "1231231",
			"cardNo": "DB730487"
		}
	]
}

响应参数说明

参数名层级类型条件描述备注
list1list必填--
checkInId2String必填入住ID--
checkInName2String必填用户姓名--
idType2int可选证件类型1身份证
2护照
9其他
idNumber2String可选证件号--
beginTime2int必填开始时间时间戳:单位秒
endTime2int必填结束时间时间戳:单位秒
cardNo2String必填卡号--

异常码

异常码异常描述
500001参数异常
500209未绑定发卡器
500300房间不存在
500400非法卡片
500402卡片已使用,请回收后再制卡
500403未读取到卡片信息
500503重复授权
500508PMS入住不允许直接操作,请前往PMS页面操作

接口说明:

  • 续住(修改授权到期时间)
  1. 离线密码,不支持续住
  2. 离线卡片授权,续住需要连接发卡器
  3. 只支持手机授权和离线卡片授权续住
  4. 房间封房状态不能修改授权到期时间
离线卡片租住需要将卡片放入关联的发卡器

业务能力:

  • openSmartExtension

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
checkInId1String必填入住ID可通过房间入住列表查看
endTime1long必填结束时间时间戳,单位秒
请求示例
{
	"method": "openSmartExtension",
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"data": {
		"checkInId": "M7Dy61IRzGs=",
		"endTime": 1608985958
	}
}

响应示例

{
	"msgId": 111135744,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartExtension",
	"data": {
		"checkInId": "M7Dy61IRzGs=",
		"checkInName": "zzy",
		"beginTime": 1605164400,
		"endTime": 1608985958
	}
}

响应参数说明

参数名层级类型条件描述备注
checkInId1String必填入住ID--
checkInName1String必填用户姓名--
beginTime1long必填开始时间时间戳:单位秒
endTime1long必填结束时间时间戳:单位秒

异常码

异常码异常描述
500001参数异常
500209未绑定发卡器
500403未读取到卡片信息
500504不支持该功能
500508PMS入住不允许直接操作,请前往PMS页面操作
500509请放置相应的卡片进行操作
500510授权不存在

接口说明:

  • 续住(修改授权到期时间)
  1. 离线密码,不支持续住
  2. 离线卡片授权,续住需要连接发卡器
  3. 房间封房状态不能修改授权到期时间
  4. 离线卡片多个房间授权,操作类型选择卡片续住
离线卡片租住需要将卡片放入关联的发卡器

业务能力:

  • openSmartExtension

本地服务器版本:

  • V3.2.0

Content-Version:

  • 1.1

参数:

参数名层级类型条件描述备注
operType1int必填操作类型1 单个续住
2 卡片续住
checkInId1String可选入住IDoperType=1必填
可通过房间入住列表查看
cardNo1String可选卡号operType=2必填
endTime1long必填结束时间时间戳,单位秒
请求示例
{
	"method": "openSmartExtension",
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"data": {
		"checkInId": "M7Dy61IRzGs=",
		"endTime": 1608985958,
		"operType": 1
	}
}

响应示例

{
	"msgId": 111135744,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartExtension",
	"data": {
	}
}

响应参数说明

参数名层级类型条件描述备注
------------

异常码

异常码异常描述
500001参数异常
500209未绑定发卡器
500403未读取到卡片信息
500504不支持该功能
500508PMS入住不允许直接操作,请前往PMS页面操作
500509请放置相应的卡片进行操作
500510授权不存在

接口说明:

  • 读卡 必须关联发卡器,且发卡器在线

业务能力:

  • openSmartReadCard

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

参数:

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartReadCard",
	"data": {
	}
}

响应示例

{
	"msgId": 1990118400,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartReadCard",
	"data": {
		"cardType": 4,
		"list": [{
			"key": "安装卡状态",
			"value": "未刷安装卡"
		}, {
			"key": "门锁号",
			"value": "1.2.202"
		}, {
			"key": "常开模式",
			"value": "关闭"
		}, {
			"key": "顶替功能",
			"value": "禁用"
		}, {
			"key": "安装位置",
			"value": "A-2层-A202"
		}],
		"isblank": 2,
		"cardNo": "DB730487"
	}
}

响应参数说明

参数名层级类型条件描述备注
isblank1int必填是否白卡0表示白卡
1表示异常卡
2正常卡
3空卡
cardNo1String必填物理卡号--
cardType1int可选卡片类型为空则表示未知卡片类型
0加密卡
1系统设置卡
2系统设置验证卡
3清除卡
4安装卡
5校时卡
6入网卡
7退网卡
32宾客卡
33总卡
34楼栋卡
35楼层卡
list1List可选--
key2String可选标题--
value2String可选内容--
异常码
异常码异常描述
500209未绑定发卡器
500403未读取到卡片信息

#####isblank=2正常卡,list格式如下 1.cardType=1系统设置卡

keyvalue
常开模式不更改
常开打开,常开模式
常开关闭,正常模式
开锁语音不更改
打开
关闭
密码使能不更改
使能
禁用
下压把手关锁不更改
使能
禁止
顶替功能不更改
开启
关闭
电机转动方向不更改
正转
反转
检卡灵敏度等级+具体参数
蓝牙灵敏度等级+具体参数
设置按键功能禁用该按键
当作机械钥匙检测开关使用
当作初始化按键功能使用
默认功能
到期提前提醒具体参数+天
备注具体参数

2.cardType=2系统设置验证卡

keyvalue
常开模式不更改
常开打开,常开模式
常开关闭,正常模式
开锁语音不更改
打开
关闭
密码使能不更改
使能
禁用
下压把手关锁不更改
使能
禁止
顶替功能不更改
开启
关闭
电机转动方向不更改
正转
反转
检卡灵敏度等级+具体参数
蓝牙灵敏度等级+具体参数
设置按键功能禁用该按键
当作机械钥匙检测开关使用
当作初始化按键功能使用
默认功能
到期提前提醒具体参数+天

3.cardType=3清除卡

keyvalue
备注具体参数

4.cardType=4安装卡

keyvalue
安装卡状态未刷安装卡
已刷安装卡
已刷门锁和取电开关
未知
设备类型电梯控制器

门禁
未知
门锁号具体参数
常开模式打开
不更改
关闭
顶替功能使能
禁用
不更改
MAC具体参数
软件版本具体参数
硬件版本具体参数
安装位置具体参数
公共楼层具体参数
电梯控制器具体参数
扩展板具体参数

5.cardType=5校时卡

keyvalue
卡片时间具体参数
锁刷卡间隔时具体参数+秒

6.cardType=6入网卡

keyvalue
备注具体参数

7.cardType=7退网卡

keyvalue
备注具体参数

8.cardType=32宾客卡

多门卡、在线入住离线入住等可能会出现多个房间和门锁号
keyvalue
房间具体参数
开始时间具体参数
结束时间具体参数
门锁号具体参数
持卡人具体参数
常开模式开启
关闭
可开反锁
可开楼层具体参数

9.cardType=33总卡

keyvalue
是否允许开反锁允许
不允许
通道模式打开
关闭
有效期具体参数
是否有效无效
有效
顶替前卡顶替
不顶替

9.cardType=34楼栋卡

keyvalue
是否允许开反锁允许
不允许
通道模式打开
关闭
有效期具体参数
有效时间段1具体参数
有效时间段2具体参数
楼栋具体参数
是否有效无效
有效
顶替前卡顶替
不顶替

9.cardType=35楼栋层

keyvalue
是否允许开反锁允许
不允许
通道模式打开
关闭
有效期具体参数
有效时间段1具体参数
有效时间段2具体参数
楼层具体参数
是否有效无效
有效
顶替前卡顶替
不顶替

接口说明:

  • 远程开锁

业务能力:

  • openSmartOpenLock

本地服务器版本:

  • V1.4.6

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
lockCode1String必填门锁号可通过房间列表查看

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartOpenLock",
	"data": {
		"lockCode": "1.2.201A"
	}
}

响应示例

{
	"msgId": 77568002,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartOpenLock",
	"data": {
	}
}

响应参数说明

参数名层级类型条件描述备注
------

异常码

异常码异常描述
500001参数异常
500201网关不存在
500207门锁未绑定网关
500300房间不存在
500316房间未关联门锁

退出发卡器录指纹模式

业务能力:

  • openSmartCancelFingerPrintModel

本地服务器版本:

  • V2.7.5

Content-Version:

  • 1.0
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号V2.7.5新增
云端发布Pub(示例):
{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLLjF+g==",
    "method": "openSmartCancelFingerPrintModel",
	"data": {
		"cardDispenserSeq": "MNR63218751FB5"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
    "msgId": 2107619328,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartAddOffLineKey",
	"data":{}
}

接口说明:

  • 退房卡
注意:只支持宾客卡制作退房卡,且授权已退房,门锁刷退房卡后宾客卡失效。

业务能力:

  • operSmartCheckOutCard

本地服务器版本:

  • V1.9.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件说明备注
lockCode1String必填门锁号可通过房间列表查看
cardDispenserSeq1String必填发卡器序列号唯一
checkInId1String必填授权ID--

请求示例

{
    "tokenId": "aFqJ9GbjlmX0LHZosmciPO7eUZd1KOag3yXrf3XwewiOD3jz0YXIcyE715XqIMK8rbRD0bM47W1TFtZLsJHbJA==",
    "method": "operSmartCheckOutCard",
    "data": {
       "lockCode":"1.2.204",
		"cardDispenserSeq": "MNR63218751FB5",
		"checkInId":"Di5Wj2CJGtk="
    }
}

响应示例

{
	"msgId": 1527377926,
	"resultCode": 0,
	"reason": "",
	"method": "operSmartCheckOutCard",
	"data": {
	}
}

响应参数说明:

参数名层级类型条件描述备注
------------

异常码

异常码异常描述
500001参数异常
500506入住信息不存在

接口说明:

  • 重新下发待处理授权

业务能力:

  • openSmartRoomResetSendKey

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

参数:

| 参数名 | 层级 | 类型 | 条件 | 说明 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||relaId| 1| String | 必填 | 联动授权关系ID|可通过入住详情查看|

请求示例

{
    "method": "openSmartRoomResetSendKey",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdnUOGWhdPWCSQzJiLVdYT4iqybECMEoq8Nx1GU2tCGVkCZMcrLk7kUQ==",
    "data": {
        "relaId": "ycMbDLEtfXY="
    }
}

响应示例

{
	"msgId": 1527377926,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartRoomResetSendKey",
	"data": {
	}
}

响应参数说明:

参数名层级类型条件描述备注
------------

异常码

异常码异常描述
500001参数异常
500010授权不存在

推送事件

接口说明:

  • 使能禁止钥匙事件推送

业务能力:

  • hxjEnableKeyEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=28 表示使能进制设置事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int使能禁止flaglogTypeFlag=1按钥匙ID使能
logTypeFlag=2按钥匙类型使能
logTypeFlag=3按用户ID使能
logTypeFlag=4按钥匙ID禁止
logTypeFlag=5按钥匙类型禁止
logTypeFlag=6按用户ID禁止
keyType1int钥匙类型logTypeFlag=2 和 logTypeFlag=5 生效
lockKeyId1int钥匙IDlogTypeFlag=1 和 logTypeFlag=4 生效
keyGroupId1int用户IDlogTypeFlag=3 和 logTypeFlag=6 生效
keyGroupName1String用户名logTypeFlag=3 和 logTypeFlag=6 生效

示例

{
	"requestId": "619158573",
	"method": "hxjEnableKeyEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 28,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"logTypeFlag":6,
		"keyGroupId":2001,
		"keyGroupName":"zzy"
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 修改密码事件推送

业务能力:

  • hxjUpdatePwEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=24 表示修改密码事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
lockKeyId1int钥匙ID-

示例

{
	"requestId": "619158573",
	"method": "hxjUpdatePwEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 24,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"keyGroupId":2001,
		"keyGroupName":"Test",
		"keyType":1,
		"lockKeyId":11
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 修改钥匙有效期事件推送

业务能力:

  • hxjUpdateKeyValidityEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=34 表示修改钥匙有效期事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int修改方式1 按钥匙ID修改
2 按用户ID修改
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次

示例

{
	"requestId": "619158573",
	"method": "hxjUpdateKeyValidityEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 34,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"logTypeFlag":1,
		"authorMode":1,
		"keyGroupId":2001,
		"keyGroupName":"Test",
		"keyType":1,
		"beginTime":1632120896,
		"endTime":1632122537,
		"useNum":255
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 删除钥匙事件推送

业务能力:

  • hxjDeleteKeyEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=9 表示删除钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int删除方式0 按编号删除
1 按类型删除
2 按内容删除
3 按用户ID删除
keyGroupId1int钥匙所属用户IDlogTypeFlag=3有效
keyGroupName1String钥匙所属用户名logTypeFlag=3有效
keyType1int钥匙类型logTypeFlag=1 按位域置1,则删除指定钥匙类型钥匙
logTypeFlag=2 结合lockKeyId固定一个钥匙删除
lockKeyId1int钥匙IDlogTypeFlag=0有效
keyContent1int钥匙内容适用离线密码未使用 按内容删除

示例

{
	"requestId": "619158573",
	"method": "hxjDeleteKeyEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 9,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"logTypeFlag":3,
		"keyGroupId":2001,
		"keyGroupName":"Test"
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

发卡器按压指纹推送通知

业务能力:

  • hxjUploadFingerPrintNumPush

本地服务器版本:

  • V1.5.0

参数:

参数名层级必选类型说明备注
resultCode1int确认码0 成功
其他失败
reason1String原因--
indexNum1int当前次数成功:必填
totalNum1int总次数成功:必填
indexNum = totalNum表示按压完成
fingerPrintSign1String指纹标识indexNum = totalNum必填
1 小时内有效
V2.0.0版本永久有效
fingerPrint1String指纹特征值indexNum = totalNum必填
V2.7.3新增
示例
{
	"requestId": "619158573",
	"method": "hxjUploadFingerPrintNumPush",
	"uploadTime": 1569317324,
	"data": {
		"resultCode": 0,
		"indexNum": 1,
		"totalNum": 4,
		"fingerPrintSign":"1692774079148466712"
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 告警事件推送(废弃)

推送的事件有: 低电量告警 故障告警 强拆报警

业务能力:

  • hxjWarnEventPush

本地服务器版本:

  • V1.5.2 (V1.6.0废弃)

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int告警类型1 强拆告警,3 低电量告警,18 故障告警
logTypeFlag1int故障类型当eventType=18时有效,为空时,表示未知异常,0 按键短路,1 存储器异常,2 触摸芯片异常,3 低压检测电路异常,4 读卡电路异常,5 检卡电路异常,6 指纹通讯异常,7 RTC晶振电路异常
electricNum1int门锁电量--

示例

{
	"requestId": "619158573",
	"method": "hxjWarnEventPush",
	"uploadTime": 1569317324,
	"data": {
		"lockCode": "1.1.2",
		"eventType": 1,
		"electricNum":30
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 周期关闭事件推送

业务能力:

  • hxjCycleCloseEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=49 表示周期关闭事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示关闭当天的周期开锁,bit0=1 星期一

示例

{
	"requestId": "619158573",
	"method": "hxjCycleCloseEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 49,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"keyGroupId":2001,
		"keyGroupName":"Test",
		"weeks":1
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 周期开启事件推送

业务能力:

  • hxjCycleOpenEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=48 表示周期开锁开启事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks2int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天周期开启
例如:bit0=1 星期一
dayEndTimes3String每日结束时间-

示例

{
	"requestId": "619158573",
	"method": "hxjCycleOpenEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 48,
		"electricNum": 30,
		"eventTime": 1632120896,
		"operKeyGroupId": 900,
		"operKeyGroupName": "zzy",
		"beginTime": 1632120896,
		"endTime": 1632122537,
		"timeList": [{
			"weeks": 1,
			"timePeriods": [{
					"dayStartTimes": "12:00",
					"dayEndTimes": "14:00"
				},
				{
					"dayStartTimes": "16:00",
					"dayEndTimes": "18:00"
				}
			]
		}]
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 开锁事件推送

业务能力:

  • hxjOpenLockEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=4 表示开锁事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
combine1int是否组合0非组合
1组合
normalOpen1int是否常开0非常开
1常开
insideOpen1int是否门内开锁0门外
1门内
keyContent11String钥匙内容keyType=2 keyContent1为密码
keyType=4 keyContent1为卡号
keyGroupId21int用户IDcombine=1有效
keyGroupName21String用户名combine=1有效
keyType21int钥匙类型combine=1有效
lockKeyId21int钥匙IDcombine=1有效
useNum21int剩余有效次数combine=1有效

示例

{
	"requestId": "619158573",
	"method": "hxjOpenLockEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 4,
		"electricNum":30,
		"eventTime":1632120896,
		"normalOpen":0,
		"normalOpen":0,
		"insideOpen":0,
		"keyGroupId1":2001,
		"keyGroupName1":"Test",
		"keyType1":1,
		"lockKeyId1":11
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 按内容修改钥匙事件推送

业务能力:

  • hxjUpdateKeyByContentEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=46 表示按内容修改钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次

示例

{
	"requestId": "619158573",
	"method": "hxjUpdateKeyByContentEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 46,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"authorMode":1,
		"keyGroupId":2001,
		"keyGroupName":"Test",
		"keyType":1,
		"beginTime":1632120896,
		"endTime":1632122537,
		"useNum":255
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

说明:

  • 推送通知格式描述

  • 当联网工程所平台,有数据要推送到第三方时,会按该协议推送数据

参数:

参数名层级必选类型说明备注
requestId1string关联消息的Id消息的序列号,唯一标识该消息
uploadTime1Long上报时间设备上报数据的时间,时间戳,单位:秒
sign1string签名--

示例

{
	"requestId": "619158573",
	"method": "hxjGatewaySendKeyResultPush",
	"uploadTime": 1569317324,
	"data": {
		"checkInId": "1sdfsdf=",
		"resultCode": 1
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 添加钥匙事件推送

业务能力:

  • hxjAddKeyEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=8 表示添加钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次

示例

{
	"requestId": "619158573",
	"method": "hxjAddKeyEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 8,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"authorMode":1,
		"keyGroupId":2001,
		"keyGroupName":"Test",
		"keyType":1,
		"beginTime":1632120896,
		"endTime":1632122537,
		"useNum":255
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 系统参数设置推送

业务能力:

  • hxjSystemSetEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=27 表示系统参数事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
lockOpen1可选int开锁模式1~2,1-单一开锁; 2-组合开锁
normallyOpen1可选int常开模式1~2,1-常开模式启用; 2-常开模式关闭
isSound1可选int语音启闭1~2,1开关门语音打开; 2开关门语音关闭
sysVolume1可选int系统音量0~5,0-表示音量不可调节,其他表示音量大小
isTamperWarn1可选int防撬报警启闭0无防撬报警功能; 1防撬报警启动; 2防撬报警功能关闭
isLockCoreWarn1可选int锁芯报警启闭0无锁芯报警功能;1锁芯报警启动; 2锁芯报警功能关闭
isLock1可选int反锁功能启闭0~2 0无反锁开关;1-反锁功能启用; 2-反锁功能关闭
isLockCap1可选int锁头盖报警启闭1~2,1-启用,2关闭
sysLanguage1可选int系统语言1~5,1:简体中文 2:繁体中文 3:英文 4:越南文 5:泰文

示例

{
	"requestId": "619158573",
	"method": "hxjAddKeyEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 27,
		"electricNum":30,
		"eventTime":1632120896,
		"operKeyGroupId":900,
		"operKeyGroupName":"zzy",
		"lockOpen":1
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

网关下发指纹、人脸结果推送通知

业务能力:

  • hxjGatewaySendKeyResultPush

参数:

参数名层级必选类型说明备注
checkInId1String入住ID
resultCode1int结果码1成功
其他失败
reason1String原因失败原因
示例
{
	"requestId": "619158573",
	"method": "hxjGatewaySendKeyResultPush",
	"uploadTime": 1569317324,
	"data": {
		"checkInId": "1sdfsdf=",
		"resultCode": 1
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 通用事件推送

业务能力:

  • hxjCommonEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
logTypeFlag1int事件Flag当eventType=18时有效,为空时,表示未知异常,0 按键短路,1 存储器异常,2 触摸芯片异常,3 低压检测电路异常,4 读卡电路异常,5 检卡电路异常,6 指纹通讯异常,7 RTC晶振电路异常
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒

示例

{
	"requestId": "619158573",
	"method": "hxjCommonEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 1,
		"electricNum":30,
		"eventTime":1632120896
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

接口说明:

  • 错误开锁事件推送

业务能力:

  • hxjErrorOpenEventPush

本地服务器版本:

  • V1.6.0

参数:

参数名层级必选类型说明备注
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=41 表示错误开锁事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int钥匙校验结果1钥匙在门锁端无法通过校验, 开锁失败
2钥匙在门锁端可以通过校验, 但门锁反锁, 钥匙无法开反锁, 开锁失败
keyContent1int钥匙内容keyType=2 keyContent为密码
keyType=4 keyContent为卡号

示例

{
	"requestId": "619158573",
	"method": "hxjErrorOpenEventPush",
	"data": {
		"lockCode": "1.1.2",
		"eventType": 41,
		"electricNum":30,
		"eventTime":1632120896,
		"logTypeFlag":1,
		"keyType":2,
		"keyContent":"123456"
	},
	"sign": "CC0A449F66A4A226474FE74BEBBC2E4F"
}

查询

接口说明:

  • 入住详情

业务能力:

  • openSmartCheckInDetail

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件说明备注
checkInId1String必填授权ID--

请求示例

{
    "method": "openSmartCheckInDetail",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdnUOGWhdPWCSQzJiLVdYT4iqybECMEoq8Nx1GU2tCGVkCZMcrLk7kUQ==",
    "data": {
        "checkInId":"+LD/tJysceg="
    }
}

响应示例

{
	"msgId": 1527377926,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartCheckInDetail",
	"data": {
		"checkInId": "+LD/tJysceg=",
		"checkInName": "QWEQWE",
		"buildingName": "A栋",
		"floorCode": 1,
		"roomName": "A103",
		"endTime": 1642896000,
		"beginTime": 1642748400,
		"state": 3,
		"authType": 2,
		"authorMode": 1,
		"addMode": 1,
		"idType": 1,
		"useNum": 255,
		"password": "WW2CW+hvrInkRrKAgRp4HQ==",
		"auth": [{
			"relaId": "q9vK01P2lmg=",
			"channelType": 5,
			"state": 3,
			"password": "WW2CW+hvrInkRrKAgRp4HQ==",
			"sendStatus": 2,
			"local": "Hotel gate"
		}, {
			"relaId": "XgHdpL5KyGI=",
			"channelType": 8,
			"channelName": "A103",
			"buildingName": "A栋",
			"floorCode": 1,
			"roomName": "A103",
			"state": 1,
			"password": "WW2CW+hvrInkRrKAgRp4HQ==",
			"sendStatus": 1,
			"local": "Room"
		}]
	}
}

响应参数说明:

参数名层级类型条件描述备注
checkInId1String必填授权ID--
buildingName1String必填楼栋名称
roomName1String必填房间名称
state1int必填状态1正常
3 待下发生效
4 挂失
5 待下发挂失
6待下发续住
7冻结
authType1int必填授权类型1.指纹
2密码
4卡片
16二维码
64人脸下发
128 APP远程
129微信授权
256 人脸授权
authorMode1int必填有效期类型1有效时间段
2周期
3永久
4临时
addMode1int可选授权添加方式1远程下发
3离线生成
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间authorMode = 0x02有效
格式:hh:mm
dayEndTimes1String可选每日结束时间authorMode = 0x02有效
格式:hh:mm
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
countryCode1int可选国家编码
appKey1int可选手机APP授权0或不填 ,表示不授权
1授权
miniProgramKey1int可选微信授权0或不填,表示不授权
1授权
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
normallyOpen1int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock1int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
password1String可选密码AES加密
picture2String可选Base64图片authType = 64 或 authType = 256 有效
2.5.0版本新增
auth1list可选授权详情
relaId2String必填联动授权关系ID
channelType2Int必填通道类型5大门
6楼栋
7楼层
8房间
9套房
roomName2String必填房间名称
state2int必填状态1已入住
2待下发退房
3待下发入住
4挂失
5待下发挂失
6待下发续住
sendStatus2int必填状态1成功
2下发失败
3下发中
password2String可选密码authType=2 表示为密码 AES加密
authType=4表示为卡片
useNum2int可选使用次数255或空表示无限次
限制次数,最大是254次
picture2String可选人脸图片base64编码
异常码
异常码异常描述
500001参数异常

接口说明:

  • 待处理入住列表

业务能力:

  • openSmartDealCheckInList

本地服务器版本:

  • V1.8.0

Content-Version:

  • 1.0

参数:

参数名层级类型条件描述备注
startNum1int开始记录数默认为0
getNum1int分页大小默认10,最大50
buildingCode1int楼栋码--
floorCode1int楼层码--
roomName1String房间名称--
customerName1String房客名称--
cardNo1String卡号--
checkInAuthType1int入住类型1 指纹
2自定义密码
3离线卡片
4手机授权
5离线密码
6下发卡片
7人脸识别
8二维码(V2.5.0新增)
9人脸下发 (V2.5.0新增)
state1int状态2待下发退房
3待下发入住
5待下挂失
6待下发续住
请求示例
{
    "method": "openSmartDealCheckInList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdnUOGWhdPWCSQzJiLVdYT4iqybECMEoq8Nx1GU2tCGVkCZMcrLk7kUQ==",
    "data": {
        "startNum": 0,
        "getNum": 10
    }
}

响应示例

{
	"msgId": 738318385,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartDealCheckInList",
	"data": {
		"listSum": 1,
		"totalPages": 1,
		"list": [{
			"checkInId": "+LD/tJyceg=",
			"lockCode": "1.1.103",
			"updateTime": 1642750740,
			"buildingName": "A栋",
			"floorCode": 1,
			"roomName": "A103",
			"checkInName": "QWEQWE",
			"checkInAuthType": 2,
			"state": 3
		}]
	}
}

响应参数说明

参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
checkInId2String可选入住ID--
lockCode2String可选门锁号--
updateTime2long可选时间--
buildingName2String可选楼栋名--
floorCode2int可选楼层码--
roomName2String可选房间名--
checkInName2String可选姓名--
checkInAuthType2int可选授权类型1 指纹
2自定义密码
3离线卡片
4手机授权
5离线密码
6下发卡片
7人脸识别
8二维码(V2.5.0新增)
9人脸下发 (V2.5.0新增)
state2int可选状态2待下发退房
3待下发入住
5待下发挂失
6待下发续住
keyContent2String可选钥匙内容--
异常码异常描述
----

接口说明:

  • 房间入住列表

业务能力:

  • openSmartCheckInList

本地服务器版本:

  • V2.3.0

Content-Version:

  • 1.0
参数:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一

请求示例

{
	"tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53Fdt/AX7/to/I8IDaYsFkk1cIkz5Ez2Y/PvhDDKWppSuXv1QLcPyLjF+g==",
	"method": "openSmartCheckInList",
	"data": {
		"lockCode":"1.1.202"
	}
}

响应示例

{
	"msgId": 1462340629,
	"resultCode": 0,
	"reason": "",
	"method": "hotelToolsCheckInList",
	"data": {
		"list": [{
				"checkInId": "lbtKa+ZuQ=",
				"checkInName": "黄",
				"beginTime": 1668736800,
				"endTime": 1668949200,
				"state": 1,
				"authType": 16,
				"authorMode": 1,
				"addMode": 1,
				"phoneNo": "15815839999",
				"countryCode": 86,
				"useNum": 255
			}
		}
	}
响应参数说明:
参数名层级类型条件描述备注
list1List可选--
checkInId2String必填授权ID
state2int必填状态1正常
3 待下发生效
4 挂失
5 待下发挂失
6待下发续住
7冻结
authType2int必填授权类型1.指纹
2密码
4卡片
16二维码
64 人脸下发
128 APP远程
129微信授权
256 人脸识别授权
authorMode2int必填有效期类型1有效时间段
2周期
3永久
4临时
addMode2int可选授权添加方式1远程下发
3离线生成
weeks2int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes2String可选每日起始时间格式:hh:mm
dayEndTimes2String可选每日结束时间格式:hh:mm
idType2int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
countryCode2int可选国家编码
appKey2int可选手机APP授权0或不填 ,表示不授权
1授权
miniProgramKey2int可选微信授权0或不填,表示不授权
1授权
useNum2int可选使用次数不填或255表示无限次
限制次数,最大是254次
normallyOpen2int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock2int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
password2String可选密码--
picture2String可选Base64图片authType = 64 或 authType = 256 有效
2.5.0版本新增

异常码

异常码异常描述
----

接口说明:

  • 房间列表查询

业务能力:

  • openSmartRoomList

本地服务器版本:

  • V1.5.1

Content-Version:

  • 1.0

参数:

参数名层级必选类型说明备注
startNum1int开始记录数默认为0
pageSize1int分页大小默认10,最大50
请求示例
{
    "method": "openSmartRoomList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdqhmpCsliBF5FkEoCQ7gSlijO9DTm8aZl/xV6UpARSkWSy/Go4HfWaA==",
    "data": {
        "startNum": 0,
        "pageSize": 10
    }
}

响应示例

{
    "msgId": 27232299,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomList",
    "data": {
        "roomList": [{
                "roomName": "0216",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 101,
                "lockCode": "1.1.101",
                "isVisible": 1,
                "lockMac": "6077712264da",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000444",
                "aesKey": "5JgpPPi8M+jWhUaIljzcjyKI8T0quSSVyhzTu5Lak24=",
                "adminAuthCode": "ZK/Mv2Gu8swTwsZWIlEuYw==",
                "generalAuthCode": "wJdwEgeSS1LcR/IMJd49uQ==",
                "tempAuthCode": "tlwfBTQe3azLEOC4ctFZKQ=="
            }, {
                "roomName": "103",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "lockCode": "1.1.103",
                "isVisible": 1,
                "lockMac": "0cec80e804d0",
                "hardwareVersion": "M157-9905BCT-FKHF V1",
                "softwareVersion": "01000444",
                "aesKey": "WVbBneUskUcbmz5lUJSv5PLa/gDXG7VZsAk6HIB05NI=",
                "adminAuthCode": "hPm9zXdXcLq2NmcDvQ4dzw==",
                "generalAuthCode": "HLA1l+XQAl2fuf7rlPIYfA==",
                "tempAuthCode": "dD4lHk/zk3Bqd+l6VuR1Lw=="
            }, {
                "roomName": "103A",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "subRoomName": "A",
                "lockCode": "1.1.103A",
                "isVisible": 1,
                "lockMac": "806fb0517c47",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V2A",
                "softwareVersion": "01000433",
                "aesKey": "A6426qo8zJPuRX1axoh3avx1eLixFBl8buykQkFTuv8=",
                "adminAuthCode": "uUGILDQ+DmG9AVHfMa9J3g==",
                "generalAuthCode": "VdxRF2p9SgJ9SI7IopzuLw==",
                "tempAuthCode": "RmFeAIKTeqDhoCzA20pQ2g=="
            }, {
                "roomName": "330",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 330,
                "lockCode": "1.1.330",
                "isVisible": 1,
                "lockMac": "e4e112d62a67",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "Io7yX8gn+WpPDO5GeqfnDNdlcrbM5rQqGaMoUx9oAxE=",
                "adminAuthCode": "MAq4jkq8z9992dMSa1Y99Q==",
                "generalAuthCode": "f3DZmMfYojq+5E08nDiCQA==",
                "tempAuthCode": "k2BbsyEzI5Bd22rPt5KsIQ=="
            }, {
                "roomName": "1011",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 1011,
                "lockCode": "1.1.1011",
                "isVisible": 1,
                "lockMac": "806fb0518534",
                "hardwareVersion": "MTBL-HXJ01-HFKF V2A",
                "softwareVersion": "01000444",
                "aesKey": "AETaEfDq/ZGXZAmKVKf8aPrscKUsAC61GxLcSh1Z9Ks=",
                "adminAuthCode": "i9B4i8kVfoiUgBuIEAVTMA==",
                "generalAuthCode": "gAUUZ8hKyNcU3jwOJYGE1A==",
                "tempAuthCode": "SMGGUOlFXfv/ZNahhjOe2w=="
            }, {
                "roomName": "201",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "lockCode": "1.2.201",
                "isVisible": 1,
                "lockMac": "806fb051887b",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "tx8Uao7D435CQiGz93Tawk0HFyMp1p9iCzzYcKP4evg=",
                "adminAuthCode": "CAqgmyGBP0FSmWz4kuvwJg==",
                "generalAuthCode": "ajmRDLwUyn2XMRVbjGQM6g==",
                "tempAuthCode": "ddp1VIgmiS8Yx5dW3kb2zw=="
            }, {
                "roomName": "201A",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "A",
                "lockCode": "1.2.201A",
                "isVisible": 1,
                "lockMac": "806fb0518514",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "zkcTTWK85O0L/D/aA5Cfqgg1isbCvonk7PuULQDg35I=",
                "adminAuthCode": "7mzT908VeuvJYDZwxU3OWw==",
                "generalAuthCode": "N1WbpqqRhXnkpVc/X3iKkA==",
                "tempAuthCode": "xcbBYa8ewZmoY6zJDl05lA=="
            }, {
                "roomName": "201B",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "B",
                "lockCode": "1.2.201B",
                "isVisible": 1,
                "lockMac": "e4e112d62a57",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "S23pdqLU2iIatrt5xwP7Z5/vIn0q0Mwa3KIAcwVHQ6Y=",
                "adminAuthCode": "v/d8wctHujKgfe8fi+nveA==",
                "generalAuthCode": "Sp0G/P3/ZaoVXu4vObVbKg==",
                "tempAuthCode": "cdnyOPUJxlGCDfxTXMNv3A=="
            }, {
                "roomName": "202-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 202,
                "lockCode": "1.2.202",
                "isVisible": 1
            }, {
                "roomName": "203-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 203,
                "lockCode": "1.2.203",
                "isVisible": 1
            }
        ],
        "listSum": 13,
        "totalPages": 2
    }
}

响应参数说明

参数名层级类型条件描述备注
subRoomName2String套房号A-Z大写
isVisible2int是否显示到房态图1表示显示,0表示不显示
adminAuthCode2String管理员鉴权码通过AES加密,有权限调用所有蓝牙接口
generalAuthCode2String普通用户鉴权码通过AES加密,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。
tempAuthCode2String临时鉴权码通过AES加密,与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。

接口说明:

  • 房间列表查询

业务能力:

  • openSmartRoomList

本地服务器版本:

  • V1.5.4

Content-Version:

  • 1.0

参数:

参数名层级必选类型说明备注
startNum1int开始记录数默认为0
pageSize1int分页大小默认10,最大50
请求示例
{
    "method": "openSmartRoomList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdqhmpCsliBF5FkEoCQ7gSlijO9DTm8aZl/xV6UpARSkWSy/Go4HfWaA==",
    "data": {
        "startNum": 0,
        "pageSize": 10
    }
}

响应示例

{
    "msgId": 27232299,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomList",
    "data": {
        "roomList": [{
                "roomName": "0216",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 101,
                "lockCode": "1.1.101",
                "isVisible": 1,
                "lockMac": "6077712264da",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000444",
                "aesKey": "5JgpPPi8M+jWhUaIljzcjyKI8T0quSSVyhzTu5Lak24=",
                "adminAuthCode": "ZK/Mv2Gu8swTwsZWIlEuYw==",
                "generalAuthCode": "wJdwEgeSS1LcR/IMJd49uQ==",
                "tempAuthCode": "tlwfBTQe3azLEOC4ctFZKQ=="
            }, {
                "roomName": "103",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "lockCode": "1.1.103",
                "isVisible": 1,
                "lockMac": "0cec80e804d0",
                "hardwareVersion": "M157-9905BCT-FKHF V1",
                "softwareVersion": "01000444",
                "aesKey": "WVbBneUskUcbmz5lUJSv5PLa/gDXG7VZsAk6HIB05NI=",
                "adminAuthCode": "hPm9zXdXcLq2NmcDvQ4dzw==",
                "generalAuthCode": "HLA1l+XQAl2fuf7rlPIYfA==",
                "tempAuthCode": "dD4lHk/zk3Bqd+l6VuR1Lw=="
            }, {
                "roomName": "103A",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "subRoomName": "A",
                "lockCode": "1.1.103A",
                "isVisible": 1,
                "lockMac": "806fb0517c47",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V2A",
                "softwareVersion": "01000433",
                "aesKey": "A6426qo8zJPuRX1axoh3avx1eLixFBl8buykQkFTuv8=",
                "adminAuthCode": "uUGILDQ+DmG9AVHfMa9J3g==",
                "generalAuthCode": "VdxRF2p9SgJ9SI7IopzuLw==",
                "tempAuthCode": "RmFeAIKTeqDhoCzA20pQ2g=="
            }, {
                "roomName": "330",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 330,
                "lockCode": "1.1.330",
                "isVisible": 1,
                "lockMac": "e4e112d62a67",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "Io7yX8gn+WpPDO5GeqfnDNdlcrbM5rQqGaMoUx9oAxE=",
                "adminAuthCode": "MAq4jkq8z9992dMSa1Y99Q==",
                "generalAuthCode": "f3DZmMfYojq+5E08nDiCQA==",
                "tempAuthCode": "k2BbsyEzI5Bd22rPt5KsIQ=="
            }, {
                "roomName": "1011",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 1011,
                "lockCode": "1.1.1011",
                "isVisible": 1,
                "lockMac": "806fb0518534",
                "hardwareVersion": "MTBL-HXJ01-HFKF V2A",
                "softwareVersion": "01000444",
                "aesKey": "AETaEfDq/ZGXZAmKVKf8aPrscKUsAC61GxLcSh1Z9Ks=",
                "adminAuthCode": "i9B4i8kVfoiUgBuIEAVTMA==",
                "generalAuthCode": "gAUUZ8hKyNcU3jwOJYGE1A==",
                "tempAuthCode": "SMGGUOlFXfv/ZNahhjOe2w=="
            }, {
                "roomName": "201",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "lockCode": "1.2.201",
                "isVisible": 1,
                "lockMac": "806fb051887b",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "tx8Uao7D435CQiGz93Tawk0HFyMp1p9iCzzYcKP4evg=",
                "adminAuthCode": "CAqgmyGBP0FSmWz4kuvwJg==",
                "generalAuthCode": "ajmRDLwUyn2XMRVbjGQM6g==",
                "tempAuthCode": "ddp1VIgmiS8Yx5dW3kb2zw=="
            }, {
                "roomName": "201A",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "A",
                "lockCode": "1.2.201A",
                "isVisible": 1,
                "lockMac": "806fb0518514",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "zkcTTWK85O0L/D/aA5Cfqgg1isbCvonk7PuULQDg35I=",
                "adminAuthCode": "7mzT908VeuvJYDZwxU3OWw==",
                "generalAuthCode": "N1WbpqqRhXnkpVc/X3iKkA==",
                "tempAuthCode": "xcbBYa8ewZmoY6zJDl05lA=="
            }, {
                "roomName": "201B",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "B",
                "lockCode": "1.2.201B",
                "isVisible": 1,
                "lockMac": "e4e112d62a57",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "S23pdqLU2iIatrt5xwP7Z5/vIn0q0Mwa3KIAcwVHQ6Y=",
                "adminAuthCode": "v/d8wctHujKgfe8fi+nveA==",
                "generalAuthCode": "Sp0G/P3/ZaoVXu4vObVbKg==",
                "tempAuthCode": "cdnyOPUJxlGCDfxTXMNv3A=="
            }, {
                "roomName": "202-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 202,
                "lockCode": "1.2.202",
                "isVisible": 1
            }, {
                "roomName": "203-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 203,
                "lockCode": "1.2.203",
                "isVisible": 1
            }
        ],
        "listSum": 13,
        "totalPages": 2
    }
}

响应参数说明

参数名层级类型条件描述备注
subRoomName2String套房号A-Z大写
isVisible2int是否显示到房态图1表示显示,0表示不显示
gatewayState2int关联的网关状态,3表示在线,4表示离线,为空表示未关联网关1.5.4版本增加
1.9.0版本后改为onlineStatue
aesKey2String门锁AES128密钥通过AES加密
adminAuthCode2String管理员鉴权码通过AES加密,有权限调用所有蓝牙接口
generalAuthCode2String普通用户鉴权码通过AES加密,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。
tempAuthCode2String临时鉴权码通过AES加密,与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。

接口说明:

  • 房间列表查询

业务能力:

  • openSmartRoomList

本地服务器版本:

  • V2.1.0

Content-Version:

  • 1.0

功能变化:

  • 1.增加房间状态返回

参数:

参数名层级必选类型说明备注
startNum1int开始记录数默认为0
pageSize1int分页大小默认10,最大50
请求示例
{
    "method": "openSmartRoomList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdqhmpCsliBF5FkEoCQ7gSlijO9DTm8aZl/xV6UpARSkWSy/Go4HfWaA==",
    "data": {
        "startNum": 0,
        "pageSize": 10
    }
}

响应示例

{
    "msgId": 27232299,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomList",
    "data": {
        "roomList": [{
                "roomName": "0216",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 101,
                "lockCode": "1.1.101",
                "isVisible": 1,
                "lockMac": "6077712264da",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000444",
                "aesKey": "5JgpPPi8M+jWhUaIljzcjyKI8T0quSSVyhzTu5Lak24=",
                "adminAuthCode": "ZK/Mv2Gu8swTwsZWIlEuYw==",
                "generalAuthCode": "wJdwEgeSS1LcR/IMJd49uQ==",
                "tempAuthCode": "tlwfBTQe3azLEOC4ctFZKQ==",
				"roomState":1
            }, {
                "roomName": "103",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "lockCode": "1.1.103",
                "isVisible": 1,
                "lockMac": "0cec80e804d0",
                "hardwareVersion": "M157-9905BCT-FKHF V1",
                "softwareVersion": "01000444",
                "aesKey": "WVbBneUskUcbmz5lUJSv5PLa/gDXG7VZsAk6HIB05NI=",
                "adminAuthCode": "hPm9zXdXcLq2NmcDvQ4dzw==",
                "generalAuthCode": "HLA1l+XQAl2fuf7rlPIYfA==",
                "tempAuthCode": "dD4lHk/zk3Bqd+l6VuR1Lw==",
				"roomState":1
            }, {
                "roomName": "103A",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 103,
                "subRoomName": "A",
                "lockCode": "1.1.103A",
                "isVisible": 1,
                "lockMac": "806fb0517c47",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V2A",
                "softwareVersion": "01000433",
                "aesKey": "A6426qo8zJPuRX1axoh3avx1eLixFBl8buykQkFTuv8=",
                "adminAuthCode": "uUGILDQ+DmG9AVHfMa9J3g==",
                "generalAuthCode": "VdxRF2p9SgJ9SI7IopzuLw==",
                "tempAuthCode": "RmFeAIKTeqDhoCzA20pQ2g==",
				"roomState":1
            }, {
                "roomName": "330",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 330,
                "lockCode": "1.1.330",
                "isVisible": 1,
                "lockMac": "e4e112d62a67",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "Io7yX8gn+WpPDO5GeqfnDNdlcrbM5rQqGaMoUx9oAxE=",
                "adminAuthCode": "MAq4jkq8z9992dMSa1Y99Q==",
                "generalAuthCode": "f3DZmMfYojq+5E08nDiCQA==",
                "tempAuthCode": "k2BbsyEzI5Bd22rPt5KsIQ==",
				"roomState":1
            }, {
                "roomName": "1011",
                "buildingCode": 1,
                "floorCode": 1,
                "roomCode": 1011,
                "lockCode": "1.1.1011",
                "isVisible": 1,
                "lockMac": "806fb0518534",
                "hardwareVersion": "MTBL-HXJ01-HFKF V2A",
                "softwareVersion": "01000444",
                "aesKey": "AETaEfDq/ZGXZAmKVKf8aPrscKUsAC61GxLcSh1Z9Ks=",
                "adminAuthCode": "i9B4i8kVfoiUgBuIEAVTMA==",
                "generalAuthCode": "gAUUZ8hKyNcU3jwOJYGE1A==",
                "tempAuthCode": "SMGGUOlFXfv/ZNahhjOe2w==",
				"roomState":1
            }, {
                "roomName": "201",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "lockCode": "1.2.201",
                "isVisible": 1,
                "lockMac": "806fb051887b",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "tx8Uao7D435CQiGz93Tawk0HFyMp1p9iCzzYcKP4evg=",
                "adminAuthCode": "CAqgmyGBP0FSmWz4kuvwJg==",
                "generalAuthCode": "ajmRDLwUyn2XMRVbjGQM6g==",
                "tempAuthCode": "ddp1VIgmiS8Yx5dW3kb2zw==",
				"roomState":1
            }, {
                "roomName": "201A",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "A",
                "lockCode": "1.2.201A",
                "isVisible": 1,
                "lockMac": "806fb0518514",
                "hardwareVersion": "MTBL-HXJ01-HF-FK V20",
                "softwareVersion": "01000448",
                "aesKey": "zkcTTWK85O0L/D/aA5Cfqgg1isbCvonk7PuULQDg35I=",
                "adminAuthCode": "7mzT908VeuvJYDZwxU3OWw==",
                "generalAuthCode": "N1WbpqqRhXnkpVc/X3iKkA==",
                "tempAuthCode": "xcbBYa8ewZmoY6zJDl05lA==",
				"roomState":1
            }, {
                "roomName": "201B",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 201,
                "subRoomName": "B",
                "lockCode": "1.2.201B",
                "isVisible": 1,
                "lockMac": "e4e112d62a57",
                "hardwareVersion": "FMTBL-01LP-HDKFX V2A",
                "softwareVersion": "01000442",
                "aesKey": "S23pdqLU2iIatrt5xwP7Z5/vIn0q0Mwa3KIAcwVHQ6Y=",
                "adminAuthCode": "v/d8wctHujKgfe8fi+nveA==",
                "generalAuthCode": "Sp0G/P3/ZaoVXu4vObVbKg==",
                "tempAuthCode": "cdnyOPUJxlGCDfxTXMNv3A==",
				"roomState":1
            }, {
                "roomName": "202-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 202,
                "lockCode": "1.2.202",
                "isVisible": 1,
				"roomState":1
            }, {
                "roomName": "203-未顶替",
                "buildingCode": 1,
                "floorCode": 2,
                "roomCode": 203,
                "lockCode": "1.2.203",
                "isVisible": 1,
				"roomState":1
            }
        ],
        "listSum": 13,
        "totalPages": 2
    }
}

响应参数说明

参数名层级类型条件描述备注
subRoomName2String套房号A-Z大写
roomState2int房间状态1 闲置
2.出租
3.预定
4.到期
5.打扫
6.维护
7封房
V2.1.0版本新增
isVisible2int是否显示到房态图1表示显示,0表示不显示
onlineStatue2int关联的网关状态,3表示在线,4表示离线,为空表示未关联网关1.5.4版本增加
aesKey2String门锁AES128密钥通过AES加密
adminAuthCode2String管理员鉴权码通过AES加密,有权限调用所有蓝牙接口
generalAuthCode2String普通用户鉴权码通过AES加密,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。
tempAuthCode2String临时鉴权码通过AES加密,与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限。

接口说明:

  • 房间操作记录列表

业务能力:

  • openSmartRoomLogList

本地服务器版本:

  • V1.5.2

Content-Version:

  • 1.0

参数:

参数名层级必选类型说明备注
lockCode1String房间门锁号
beginTime1long事件开始时间时间戳 单位:秒
2.7.0版本新增
endTime1long事件结束时间时间戳 单位:秒
2.7.0版本新增
startNum1int开始记录数默认为0
pageSize1int分页大小默认10,最大50
请求示例
{
    "method": "openSmartRoomLogList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdqhmpCsliBF5FkEoCQ7gSlijO9DTm8aZl/xV6UpARSkWSy/Go4HfWaA==",
    "data": {
		"lockCode": "1.1.101",
        "startNum": 0,
        "pageSize": 10
    }
}

响应示例

{
    "msgId": 27133985,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomLogList",
    "data": {
        "list": [{
                "logType": 4,
                "electricNum": 20,
                "eventTime": 1623313593,
                "combine": 0,
                "normalOpen": 0,
                "insideOpen": 0,
                "keyGroupName": "肖诗强",
                "keyGroupId": 2002,
                "lockKeyId": 11,
                "keyType": 1
            }, {
                "logType": 34,
                "electricNum": 20,
                "eventTime": 1623313591
            }, {
                "logType": 8,
                "electricNum": 30,
                "eventTime": 1623313557,
                "logTypeFlag": 0,
                "keyType": 1,
                "lockKeyId": 11,
                "keyGroupId": 2002,
                "keyGroupName": "肖诗强",
                "vaildNumber": 255,
                "operUserName": "富贵饭店",
                "operUserId": 900
            }, {
                "logType": 9,
                "electricNum": 20,
                "eventTime": 1623313423,
                "logTypeFlag": 3,
                "keyGroupId": 2001,
                "keyGroupName": "肖诗强",
                "operUserName": "富贵饭店",
                "operUserId": 900
            }, {
                "logType": 4,
                "electricNum": 20,
                "eventTime": 1623313341,
                "combine": 0,
                "normalOpen": 0,
                "insideOpen": 0,
                "keyGroupName": "肖诗强",
                "keyGroupId": 2001,
                "lockKeyId": 11,
                "keyType": 1
            }, {
                "logType": 34,
                "electricNum": 20,
                "eventTime": 1623313339
            }, {
                "logType": 8,
                "electricNum": 20,
                "eventTime": 1623313334,
                "logTypeFlag": 0,
                "keyType": 1,
                "lockKeyId": 11,
                "keyGroupId": 2001,
                "keyGroupName": "肖诗强",
                "vaildNumber": 255,
                "operUserName": "富贵饭店",
                "operUserId": 900
            }, {
                "logType": 9,
                "electricNum": 20,
                "eventTime": 1623313210,
                "logTypeFlag": 3,
                "keyGroupId": 2002,
                "keyGroupName": "肖诗强",
                "operUserName": "富贵饭店",
                "operUserId": 900
            }, {
                "logType": 9,
                "electricNum": 20,
                "eventTime": 1623313206,
                "logTypeFlag": 3,
                "keyGroupId": 2001,
                "keyGroupName": "肖诗强",
                "operUserName": "富贵饭店",
                "operUserId": 900
            }, {
                "logType": 4,
                "electricNum": 20,
                "eventTime": 1623313170,
                "combine": 0,
                "normalOpen": 0,
                "insideOpen": 0,
                "keyGroupName": "肖诗强",
                "keyGroupId": 2001,
                "lockKeyId": 11,
                "keyType": 1
            }
        ],
        "listSum": 104,
        "totalPages": 11
    }
}



响应参数说明

参数名层级类型条件描述备注
eventTime2long事件触发时间时间戳,单位:秒
electricNum2int电量--
logType2int日志类型--
logData2--日志内容不同日志类型,日志内容不同
当logType为
4 开锁事件
41 开锁失败
10 门锁反锁
11 门锁解除
30 门已上锁
32 机械钥匙开锁
17 常开:关锁
43 周期常开:开锁

logData定义如下:

参数名类型条件描述备注
combineint是否组合开锁当logType=4有效,1表示组合开锁
normalOpenint是否常开当logType=4有效,1表示常开
insideOpenint是否门内开锁当logType=4有效,1表示内门开锁
keyGroupNameString可选用户名--
keyGroupIdint可选用户ID--
lockKeyIdint可选钥匙ID--
keyTypeint可选钥匙类型 1 指纹2 密码4 卡片8 遥控128 电子钥匙--

当logType为 8添加钥匙 9删除钥匙 24修改钥匙 28使能钥匙

logData定义如下:

参数名类型条件描述备注
logTypeFlagint日志类型标志logType=8添加:
logTypeFlag=0自定义下发
logTypeFlag=1算法生成

logType=9删除:
logTypeFlag=0按钥匙ID
logTypeFlag=1按钥匙类型
logTypeFlag=2按钥匙内容
logTypeFlag=3按用户ID

logType=24修改密码:
logTypeFlag=0修改密码
logTypeFlag=1按钥匙ID
logTypeFlag=2按用户
logTypeFlag=3按内容

logType=28使能:
logTypeFlag=1按钥匙ID
logTypeFlag=2按钥匙类型
logTypeFlag=3按用户ID

logType=28禁止:
logTypeFlag=4按钥匙ID
logTypeFlag=5按钥匙类型
logTypeFlag=6按用户ID
keyTypeint钥匙类型--
lockKeyIdint可选钥匙ID--
keyGroupIdint可选用户ID--
keyGroupNameString可选用户名--
beginTimeint可选钥匙有效期开始时间时间戳:秒
endTimeint可选钥匙有效期结束时间时间戳:秒
weeksint可选周期按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。bit0表示周一,bit6表示日。如周二、周三有效,weeks=6,6=0000110
dayStartTimeString可选周期时间段开始时间
dayEndTimeString可选周期时间段结束时间
vaildNumberint可选剩余次数空或255表示无限 ,0-254表示相应的次数
operUserNameString可选操作人--
operUserIdint可选操作人ID--

当logType为 1强拆 2非法操作 3低电量 12撬锁芯报警 14门未关好 15未关门报警 18故障报警 21系统锁定状态解除 35两天未开锁 47未验证开锁

logData定义如下:

参数名类型条件描述备注
logTypeFlagint日志类型标志logType=18时
为空时,表示未知异常
logTypeFlag=0按键短路
logTypeFlag=1存储器异常
logTypeFlag=2触摸芯片异常
logTypeFlag=3低压检测电路异常
logTypeFlag=4读卡电路异常
logTypeFlag=5检卡电路异常
logTypeFlag=6指纹通讯异常
logTypeFlag=7RTC晶振电路异常

当logType为 27门锁系统设置 5布防 6撤防 19状态更新事件 20切换系统语言 22申请时间同步 48 周期性门锁开启 49 周期性门锁关闭

logData定义如下:

参数名类型条件描述备注
openModeint开锁模式logType=27有效,0不改变、1单一开锁、2组合开锁--
normallyOpenModeint常开模式logType=27有效 0不改变、1启用、2关闭--
volumeEnableint语音启闭logType=27有效 0不改变、1启用、2关闭--
volumeint音量大小logType=27有效--
preventionAlramint防撬报警logType=27有效 0不改变、1启用、2关闭--
lockCylinderAlramint锁芯报警logType=27有效 0不改变、1启用、2关闭--
antiLockFunctionint反锁功能logType=27有效 0不改变、1启用、2关闭--
lockCoverAlarmint锁头盖报警锁头盖报警logType=27有效 0不改变、1启用、2关闭--
languageint系统语言logType=27有效 1简体中文 2繁体中文 3英文 4越南语 5泰语--

接口说明:

  • 获取房间电量

获取所有房间的电量

业务能力:

  • openSmartElectricNumList

本地服务器版本:

  • V1.5.2

Content-Version:

  • 1.0

参数:

请求示例

{
    "method": "openSmartElectricNumList",
    "tokenId": "aFqJ9GbjlmX0LHZosmciPH3Ewt4S53FdqhmpCsliBF5FkEoCQ7gSlijO9DTm8aZl/xV6UpARSkWSy/Go4HfWaA==",
    "data": {
    }
}

响应示例

{
    "msgId": 43968528,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartElectricNumList",
    "data": {
        "roomList": [{
                "lockCode": "1.1.101",
                "electricNum": 20
            }, {
                "lockCode": "1.1.103",
                "electricNum": 50
            }, {
                "lockCode": "1.1.103A"
            }, {
                "lockCode": "1.1.330"
            }, {
                "lockCode": "1.1.1011"
            }, {
                "lockCode": "1.2.201"
            }, {
                "lockCode": "1.2.201A",
                "electricNum": 20
            }, {
                "lockCode": "1.2.201B"
            }
        ]
    }
}

响应参数说明

参数名层级类型条件描述备注

接口说明:

读宾客卡

本地服务器版本:

  • V1.6.1

Content-Version:

  • 1.0

业务能力:

  • openSmartReadGuestCard

参数:

请求示例

{
	"method": "openSmartReadGuestCard",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartReadGuestCard",
	"data": {
	"cardNo":"DB730487",
	"lockCode": "1.2.201A",
	"beginTime":1602165958,
    "endTime":1608965958,
	"isLock":0,
	"replaceFunction":0
	}
}

响应参数说明

参数名层级必选类型说明备注
cardNo1String卡号--
lockCode1String门锁号如:1.1.1
beginTime1int开始时间时间戳:单位秒
endTime1int结束时间时间戳:单位秒
isLock1int可选是否允许开反锁0不允许,1允许
replaceFunction1int可选是否顶替前卡0顶替,1不顶替

异常码

异常码异常描述
500709非宾客卡

登录鉴权V1.4.1

设备操作

接口说明:

  • 取电开关全局设置服务
  • 不满足取电条件的延时断电时间

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartSwitchGlobalSet

参数:

参数名层级类型条件说明备注
powerOffTime1int必填不满足取电条件的延时断电时长单位:秒
不填表示不设置
请求示例
{
	"method": "openSmartSwitchGlobalSet",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"powerOffTime": 12
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartSwitchGlobalSet",
	"data": {}
}

响应参数说明

异常码

异常码异常描述
500001参数异常
400041权限不足

接口说明:

  • 取电开关取电模式设置

本地服务器版本:

  • V3.3.0

Content-Version:

  • 1.0

业务能力:

  • openSmartSetSwitchMode

参数:

参数名层级类型条件说明备注
lockCode1String必填门锁号可通过房间列表获取

请求示例

  {
    "method": "openSmartSetSwitchMode",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {
      "lockCode": "1.1.1",
      "switchMode": 1
    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartSetSwitchMode",
    "data": {
    }
}

响应参数说明

参数名层级必选类型说明备注
------------
异常码
异常码异常描述
500001参数异常

接口说明:

  • 取电开关白名单设置
  • 暂只支持卡片,授权白名单后卡片能直接取电

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartSetSwitchWhite

参数:

参数名层级类型条件说明备注
lockCode1string必填门锁号可通过房间列表获取
addType1int必填添加类型1 新增
2 删除
3 覆盖
keyType1int必填授权类型4 卡片
authList1List<String>卡号格式:["23FDAA43","23FDAF13"]
addType!=2必填
一个取电开关最多下发20张卡号,如若超过将不做保存并且无法对该取电开关生效
请求示例
  {
    "method": "openSmartSetSwitchWhite",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {
      "lockCode": "1.1.1",
      "addType": 1,
	  "keyType": 4,
	  "authList": ["23FDAA43","23FDAF13"]
    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartSetSwitchWhite",
    "data": {
    }
}

响应参数说明

参数名层级必选类型说明备注
------------
异常码
异常码异常描述
500001参数异常

接口说明:

  • 异常取电记录

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartGetExceptionUseElectricRecords

参数:

参数名层级类型条件说明备注
startNum1int可选开始记录数默认为0
pageSize1int可选分页大小默认10,最大50
buildingCode1int可选楼栋码--
floorCode1int可选楼层码--
roomName1String可选房间名称--
beginTime1long可选开始时间单位: 秒
endTime1long可选结束时间单位: 秒
请求示例
  {
    "method": "openSmartGetExceptionUseElectricRecords",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {

    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomElectricSwitchOper",
    "data": {
    }
}

响应参数说明

参数名层级类型条件说明备注
list1long可选--单位: 秒
eventTime2long可选操作时间时间戳,单位:秒
operUserName2string可选操作人--
logContent2string可选操作内容--
subRoomName2String套房号A-Z大写
keyContent2string可选钥匙内容--

异常码

异常码异常描述
500001参数异常

接口说明:

  • 房间取电记录

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartUseElectricLogList

参数:

参数名层级类型条件说明备注
startNum1int可选开始记录数默认为0
pageSize1int可选分页大小默认10,最大50
switchState1int可选状态1 正常
2 异常
不传全部
beginTime1long可选开始时间单位: 秒
endTime1long可选结束时间单位: 秒
lockCode1string必填门锁号可通过房间列表获取
填了此参数下方参数无效
buildingCode1int可选楼栋码--
floorCode1int可选楼层码--
roomName1String可选房间名称--
请求示例
  {
    "method": "openSmartUseElectricLogList",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {
      "lockCode": "1.1.1",
    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openRoomElectricSwitchOper",
    "data": {
    }
}

响应参数说明

参数名层级类型条件说明备注
list1long可选--单位: 秒
subRoomName2String套房号A-Z大写
eventTime2long可选操作时间时间戳,单位:秒
currentState2int可选当前状态1远程送电
2远程断电
3供电
4断电
5开锁后,临时取电1分钟
lastState2int可选上一个状态1远程送电
2远程断电
3供电
4断电
5开锁后,临时取电1分钟
stateChangeMode2int可选状态切换方式1计时结束
2前台操作
3宾客卡
4反锁
5管理卡
keyContent2string可选钥匙内容--
switchState2int可选状态1:正常
2:异常

异常码

异常码异常描述
500001参数异常

接口说明:

  • 房间的取电状态

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartGetRoomElectricState

参数:

参数名层级类型条件说明备注
lockCode1string必填门锁号可通过房间列表获取

请求示例

  {
    "method": "openSmartGetRoomElectricState",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {
      "lockCode": "1.1.1",
    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartGetRoomElectricState",
    "data": {
    }
}

响应参数说明

参数名层级类型条件说明备注
electricState1int可选状态1:断电
2:供电

异常码

异常码异常描述
500001参数异常

接口说明:

  • 房间送电/断电/恢复设置

本地服务器版本:

  • V3.1.1

Content-Version:

  • 1.0

业务能力:

  • openSmartRoomElectricSwitchOper

参数:

参数名层级类型条件说明备注
lockCode1string必填门锁号可通过房间列表获取
operMode1int必填模式类型1 送电
2 断电
3 恢复正常模式
endTime1long必填模式类型operType=1 送电结束时间
operType=2 断电结束时间
单位: 秒
请求示例
  {
    "method": "openSmartRoomElectricSwitchOper",
	"tokenId":"Y0IFV96ntTMVlfElMC6TGWZAQP4VUrTbfT7ILkYb+X1iwwKMVoVLPSegij6L/31sRj9KGzdjAVxRfAg3WAVvmg==",
    "data": {
      "lockCode": "1.1.1",
      "operMode": 1,
	  "endTime": 1714622990
    }
  }

响应示例

{
    "msgId": 149907492,
    "resultCode": 0,
    "reason": "",
    "method": "openSmartRoomElectricSwitchOper",
    "data": {
    }
}

响应参数说明

参数名层级必选类型说明备注
------------
异常码
异常码异常描述
500001参数异常

接口说明:

设置回调地址

  • 当设备上报数据时,通过回调地址,推送到第三方服务器
  • 如果需要修改回调地址,重新调用设置为新的回调即可
  • 主账号才有权限

本地服务器版本:

  • V1.4.1

Content-Version:

  • 1.0

业务能力:

  • openSmartCallbackUrlSet

参数:

参数名层级必选类型说明备注
callbackUrl1String回调地址
请求示例
{
	"method": "openSmartCallbackUrlSet",
	"tokenId": "9/byy8/mfaIC2RbBYeDZul5xXv3Qolc6oH+cw81+j7ykRxuYZU0ajgkv/ZRVZXbb9w0yf99iuhrQ\nbH44QJ4lOg==",
	"data": {
		"callbackUrl": "https://xxxx.com/callbackUrl"
	}
}

响应示例

{
	"msgId": 249806905,
	"resultCode": 0,
	"reason": "",
	"method": "openSmartCallbackUrlSet",
	"data": {}
}

响应参数说明

异常码

异常码异常描述
500001参数异常
400041权限不足

接口规范

请求方式:

  • POST

请求头:

  • Content-Type: text/json;charset=utf-8
  • Content-Version: 1.0 Content-Version表示接口版本,不填则默认获取1.0版本。

请求体: JSON字符串

  {
    "msgId":123456,
    "method": "xxxxxx",
	"tokenId":"xxxxxxxxxxxxxxxxxx",
    "data": {
    }
  }

参数说明

参数名类型说明
msgIdint消息ID
methodstring访问的业务方法
tokenIdstring从平台获取的tokenId
datastring业务字段

响应头:

  • Content-Type=text/json;
  • charset=utf-8

响应体: JSON字符串

  {
  "msgId":123456,
    "method": "xxxxxx",
	"resultCode":0,
	"reason":"xxxxx",
    "data": {
    }
  }

参数说明

参数名类型说明
msgIdint消息ID
methodstring访问的业务方法
resultCodeint系统错误码
reasonstring系统错误描述
datastring业务字段

http://酒店本地部署服务IP:8090

附录

AES加密说明

如密码123456 账号当前的tokenId为: Y0IFV96ntTMVlfElMC6TGUAE0HQ5ftc2G4GCeZTFM4JhmcmnxXRkiehpFYog+mK2jqGiGjvlwrWU/P1232mMog==

  1. 对tokenId取MD5:3042B5D38733951FDC3A4F23493E931F(大写)

  2. 对tokdnId的MD5,截取第9至25位:8733951FDC3A4F23,即substring(8, 24)

  3. 把 8733951FDC3A4F23 当作AES加密的向量以及加密的KEY,填充模式为”AES/CBC/PKCS5Padding”,对123456进行加密

  4. 把最后的加密结果进行base64编码

最后结果为: AY7/ot5BG7UrozYYWiDOYA==

注: Java MD5的实现,使用的是自带的MessageDigest类,java对转义字符处理时,是把转义字符当普通字符处理。如\r,\n

public static String md5(String obj) {
        return BytesUtils.bytesToHex(md5(obj.getBytes()));
}
    public static byte[] md5(byte[] plainBytes) {
        try {
            return MessageDigest.getInstance("MD5").digest(plainBytes);
        } catch (NoSuchAlgorithmException ex) {
            return null;
        }
    }

房间状态

描述
1闲置、空净
2入住
3预定(暂未用到该状态)
4到期
5打扫
6维护

房间状态流转图

日志类型eventType

注意:第三方可以根据需求解析eventType处理
描述
01强拆报警
02非法操作报警(错误次数超限等),系统已 锁定
03低电量报警
04开锁
05布防
06撤防
07胁迫开锁
08添加授权
09删除授权
10反锁
11反锁解除
12撬锁芯报警
13门铃事件
14门未关好(假锁报警)
15未关门报警
17门锁已关闭常开
18故障报警
20切换系统语言
21系统锁定状态解除
22时间同步
24修改密码
25未拔钥匙事件
26打开锁头盖事件
27系统参数设置事件
28使能与禁止
30上锁事件
31斜舌缩进事件(压把手事件)
32机械钥匙开锁事件
34修改钥匙有效期
41错误开锁事件
43自动开锁
46按照钥匙内容修改钥匙信息事件
47未验证开锁
48周期开启事件
49周期关闭事件

钥匙类型keyType

描述
1指纹
2密码
4卡片
8遥控器
128APP远程
129微信
256人脸识别

MQTT对接

###EMQX安装向导

版本推荐4.2.6

方式一:

参照官方网址安装(https://docs.emqx.cn/broker/v4.3/getting-started/install.html#shell-%E8%84%9A%E6%9C%AC%E4%B8%80%E9%94%AE%E5%AE%89%E8%A3%85-linux)

方式二:

操作系统:Centos7

步骤:

1.下载中心下载 [emqx-centos7-4.2.6-x86_64.zip][1],下载后上传Centos系统

2.解压 unzip emqx-centos7-4.2.6-x86_64.zip

3.启动 ./bin/emqx start

4.查看状态 ./bin/emqx_ctl status

5.重启 ./bin/emqx restart

6.停止 ./bin/emqx stop

7.卸载 直接删除EMQX目录既可

配置(用户连接认证)

1.修改配置文件/emqx/etc/emqx.conf allow_anonymous = true 改为 allow_anonymous = false 不允许任何用户都能连接

2.配置插件启动开启用户认证 /emqx/data/loaded_plugins 文件加入 {emqx_auth_username,true}.

3.配置连接用户名和密码 /emqx/etc/plugins/emqx_auth_username.conf 例如: auth.user.1.username = zzy auth.user.1.password = 123456

4.重启EMQX生效

进行发布和订阅获取和更新密钥主题之前得先在自己所在HTLock主账号的账号中心下拿到appId,然后根据格式作成发布主题和订阅主题的格式(格式详情可以看TOPIC格式)。

MQTT鉴权接口说明:

获取密钥:这不是第三方服务器向本地部署服务器获取密钥的接口,而是由本地部署服务器(HTLock)调取的接口,更新密钥有个设定密钥有效期的参数expireTime,当时间超过了expireTime后服务器就会调取获取密钥接口给到MQTT这边向你获取密钥,这时候需要再次调更新密钥接口把密钥给到本地部署服务器。

更新密钥:第一次使用MQTT对接的时候需要调用的接口,desKey是自己定义的8位字符,然后经过AES加密后经过更新密钥接口给到本地部署服务器这边记录,后续传送的数据进行加密和解密都需要用到desKey,这个接口可以设置desKey的使用有效期,如若有效期过了之后调用功能接口,本地部署服务器会调用失败并且向MQTT这边发送一个获取密钥的接口进行获取密钥,这时候需要再次调用更新密钥接口给到本地部署服务器这边记录。

重要:

如果是第一次使用MQTT的话,在进行发布和订阅主题之前,得先更新密钥。

1.根据生成AES密钥生成规则文档使用APPID进行异或算法生成AES密钥。 2.生成了AES密钥后看向AES加密的文档,对desKey进行加密。 3.根据AES加密代码对desKey进行加密。(需要用到自己定义的8位数以上的desKey和用APPID生 成的AES密钥) 4.把经过加密的desKey给到更新密钥的desKey那里进行调用。

更新密钥的时候设置了时长,当密钥使用时间超过了设置时长的时候,那么下一次发布主题的时候就会发送一个获取密钥的请求来进行获取密钥。

DES加密和解密说明:

需要对数据安全,针对房源管理、设备操作、授权操作、卡片操作、日志同步的data数据进行加密。

DES加密需要用到发布的请求里面的data数据(包括{}符号)和没有经过加密的自定义8位字符的desKey给到代码里面进行加解密。

第三方服务MQTT部署说明

条件:

部署MQTT最少需用用到两台电脑进行部署,一台部署HTLock,还有一台部署MQTT连接软件以及EMQX单独服务。

第三方服务要部署MQTT服务,然后HTLock需要配置服务信息才可以进行发布或订阅主题(发布和订阅主题详情请看TOPIC格式)。

1.需要一台服务器部署MQTT服务后打开HTLock本地服务(也可以在别的电脑上打开),进入服务系统页面后点击右上角五下。

2.在输入密码那输入666666点击确定。

3.进入到系统设置页面后点击左边的MQTT设置。

4.进入MQTT设置页面后配置好对应信息。

HTLock本机MQTT服务配置说明

1.安装好EMQX后(安装详情请看EMQX安装向导文档),进入EMQX的bin目录在路径那输入cmd进入小黑窗输入emqx.cmd start按回车运行EMQX服务(停止的话是emqx.cmd stop)。

2.打开MQTT.FX(可以去官网下),点击设置进行MQTT服务配置。

3.配置好MQTT的IP和端口等信息。

4.点击Connect进行连接即可进行发布和订阅主题,最右边图标红色说明失败,绿色说明连接成功。

TOPIC内容

#####注意:
1.本地服务器V1.9.0支持接口版本version,不传默认为1.0版本,version为Double类型。
2.发送数据前请确认数据JSON格式是否正确,错误边缘网关服务解析失败不会应答。

请求格式
{
	"cmd": 命令值,
	"msgId": 122321323,
	"version":1.0,
	"data": {
	}
}
响应格式
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码",
	"rsn": "原因",
	"data": {
    }
}

rslt = 0表示请求成功,其他失败

TOPIC格式

1.发布
第三方发布主题:/localhost_hotel/酒店AppId/dev_pub
例如:

######/localhost_hotel/b5d0769c550d4f6699c8ecbd668f8132/dev_pub

2.订阅
第三方订阅主题:/ localhost_hotel /酒店AppId/dev_sub
例如:

######/localhost_hotel/b5d0769c550d4f6699c8ecbd668f8132/dev_sub

会话msgId

每次会话某段时间内唯一,int类型,每次请求和响应msgId相同。

JAVA参考代码

import java.io.IOException;
import java.net.Inet6Address;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.UnknownHostException;
import java.util.Enumeration;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;


public class NetworkUtil {

	private static final Logger LOGGER = LoggerFactory.getLogger(NetworkUtil.class);

	public static String getHostAddress() {
		return getHostAddress(getLocalAddress());
	}

	public static String getHostAddress(byte[] addr) {
		try {
			return InetAddress.getByAddress(addr).getHostAddress();
		} catch (UnknownHostException ex) {
			LOGGER.error("Unexpected exception: ", ex);
		}
		return InetAddress.getLoopbackAddress().getHostAddress();
	}

	public static byte[] getLocalAddress() {
		try {
			for (Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces(); interfaces
					.hasMoreElements();) {
				NetworkInterface networkInterface = interfaces.nextElement();
				if (networkInterface.isLoopback() || networkInterface.isVirtual() || !networkInterface.isUp()
						|| networkInterface.isPointToPoint()) {
					continue;
				}
				Enumeration<InetAddress> addresses = networkInterface.getInetAddresses();
				while (addresses.hasMoreElements()) {
					InetAddress addr = addresses.nextElement();
					if (addr instanceof Inet6Address) {
						continue;
					}
					return addr.getAddress();
				}
			}
		} catch (IOException ex) {
			LOGGER.error("Unexpected exception: ", ex);
		}
		return InetAddress.getLoopbackAddress().getAddress();
	}

}

import java.util.concurrent.ThreadLocalRandom;
import java.util.concurrent.atomic.AtomicInteger;

public class MsgIdUtil {
    private MsgIdUtil(){
    }
    private static AtomicInteger atomicInt = new AtomicInteger(0);
    private static int NET_WORK = 0;
    static{
        String ip = NetworkUtil.getHostAddress();
        NET_WORK=Integer.valueOf(ip.substring(ip.lastIndexOf(".")+1));
    }

    public static Integer createMsgId() {
        return (getAtomicInt()<<24) | (getHostInt()<<16)
            | (getTimeInt()<<6) | getRandomInt();
    }

    private synchronized static int getAtomicInt() {
        if(atomicInt.get()>=127){
            atomicInt.set(0); 
        }
        return atomicInt.getAndIncrement();
    }


    private static int getHostInt() {
        return ThreadLocalRandom.current().nextInt(: 255);
    }

    private static int getTimeInt() {
        return (int)(System.currentTimeMillis()%1000);
    }

    private static int getRandomInt() {
        return ThreadLocalRandom.current().nextInt(63);
    }
    public static void main(String[] args) {
        for(int i=0;i<150;i++){
            System.out.println(MsgIdUtil.createMsgId()); 
        }
    }
}

|时间|内容摘要|作者|本地服务器版本| |:---- |:---| |2020-08-27|初稿|zzy|V1.5.3| |2020-11-02|楼栋添加、修改、删除,房间添加、修改、删除,房间类型添加、修改、删除|zzy|V1.6.0| |2022-01-02|远程开锁|zzy|V1.7.0| |2022-01-22|待处理授权列表、重新下发待处理授权、忽略待处理授权、门禁/梯控列表|zzy|V1.8.0| |2021-04-15|1.优化所有日志都推送
2.新增开放接口能力
3.宾客卡、退房支持1.1接口版本|zzy|V1.9.0| |2021-07-15|1.手机授权增加邮箱授权
2.增加发卡器退出录指纹模式
3.部分接口返回授权参数
4.增加房间封房、解封
5.增加入住冻结、解冻|zzy|V2.1.0| |2021-08-18|1.增加下发挂失接口|zzy|V2.1.0| |2023-03-15|1.新增图片处理接口
2.新增下发人脸
3.房间入住列表返回Base64图片数据
4.房间入住详情返回Base64图片数据
5.待处理入住列表筛选加二维码、人脸下发|zzy|V2.5.0| |2023-06-20|1.房间日志列表增加事件开始时间和事件结束时间查询|zzy|V2.7.0|

卡片操作

制作多门卡

本地服务器版本:

  • V2.9.0

命令值(cmd):

  • 409
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
multiLockCardId1String可选被挂失的多门卡ID填写该参数下面参数可不填
remark1String必填持卡人
endDate1long必填结束时间时间戳:秒
isLock1int可选是否可开反锁0不允许
1允许
默认不允许
replaceFunction1int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods1list可选可开时间段最多设置2个
beginTime2String可选时间段开始时间格式:HH:mm,如10:03
endTime2String可选时间段结束时间格式:HH:mm,如10:03
floorCode2int必填楼层号--
roomCode2int必填房间号--
subRoomName2String可选套房号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
    "data": {
        "cardDispenserSeq":"MNR6321DC83CC8",
        "cardNo": "0B2574A3",
        "isLock": 1,
        "replaceFunction": 1,
        "endDate": 1763222399,
		"remark":"ded",
        "timePeriods": [
            {
                "beginTime": "09:00",
                "endTime": "18:00"
            },
            {
                "beginTime": "19:00",
                "endTime": "20:00"
            }
        ],
        "list": [
            {
                "buildingCode": 1,
                "floorCode": 9,
                "roomCode": 901,
                "subRoomName":"A"
            },
            {
                "buildingCode": 1,
                "floorCode": 9,
                "roomCode": 902
            }
        ]
    }
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
400041权限不足
500400非法卡片,不是酒店加密卡
500504不支持该功能
500710当前卡片最多写入xx个房间
500711卡片不支持
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
--其他异常

制作总卡

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 401
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
totalCardId1String可选被挂失总卡IDV3.2.0新增,填写该参数下面参数可不填
endDate1long可选结束时间时间戳:秒
remark1String可选持卡人
isLock1int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen1int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
replaceFunction1int可选顶替前卡1顶替
2不顶替
默认不顶替
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
    "data": {
		"cardDispenserSeq":"MNR6321DC83CC8",
		"cardNo": "0B2574A3",
        "isLock": 1,
        "replaceFunction": 1,
        "normallyOpen": 0,
        "endDate": 1721318399,
        "remark": "ede"
    }
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500400非法卡片,不是酒店加密卡
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
500537操作失败,房间xxx已存在xxx二维码授权
--其他异常

制作楼层卡

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 405
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
floorCardId1long可选被挂失楼层卡IDV3.2.0新增,填写该参数下面参数可不填
remark1String必填持卡人
endDate1long必填结束时间时间戳:秒
isLock1int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen1int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
replaceFunction1int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods1list可选可开时间段最多设置2个
beginTime2String可选时间段开始时间格式:HH:mm,如10:03
endTime2String可选时间段结束时间格式:HH:mm,如10:03
floorCode2int必填楼层号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq":"MNR6321DC83CC8",
        "cardNo": "0B2574A3",
        "isLock": 0,
        "replaceFunction": 2,
        "normallyOpen": 0,
        "endDate": 1721059199,
        "list": [
            {
                "buildingCode": "1",
                "floorCode": "1"
            },
            {
                "buildingCode": "1",
                "floorCode": "6"
            },
            {
                "buildingCode": "1",
                "floorCode": "10"
            }
        ],
        "remark": "得的",
        "timePeriods": [
            {
                "beginTime": "16:03",
                "endTime": "19:03"
            },
            {
                "beginTime": "22:03",
                "endTime": "23:03"
            }
        ]
    }
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500400非法卡片,不是酒店加密卡
500711卡片不支持
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
--其他异常

制作楼栋卡

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 403
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
buildingCardId1String必填被挂失楼栋卡IDV3.2.0新增,填写该参数后下面的参数可不填
endDate1long必填结束时间时间戳:秒
isLock1int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen1int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
replaceFunction1int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods1List可选可开时间段最多设置2个
beginTime2String可选时间段开始时间格式:HH:mm,如10:03
endTime2String可选时间段结束时间格式:HH:mm,如10:03
list1list必填最多10个楼栋
buildingCode2int必填楼栋号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq":"MNR6321DC83CC8",
        "cardNo": "0B2574A3",
        "isLock": 1,
        "replaceFunction": 1,
        "normallyOpen": 1,
        "endDate": 1721059199,
        "list": [
            {
                "buildingCode": "1"
            },
            {
                "buildingCode": "2"
            },
            {
                "buildingCode": "8"
            }
        ],
        "remark": "楼栋卡",
        "timePeriods": [
            {
                "beginTime": "15:17",
                "endTime": "16:17"
            },
            {
                "beginTime": "17:18",
                "endTime": "19:18"
            }
        ]
    }
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500400非法卡片,不是酒店加密卡
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
--其他异常

卡片加密

本地服务器版本:

  • V3.2.0

命令值(cmd):

  • 411
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq":"xxxxxxxxxxx",
		"cardNo":"E354AB12"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

卡片还原

本地服务器版本:

  • V3.2.0

命令值(cmd):

  • 412
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq":"xxxxxxxxxxx",
		"cardNo":"E354AB12"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

回收卡片(还原扇区)

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 407
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq":"xxxxxxxxxxx",
		"cardNo":"E354AB12"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

多门卡列表

本地服务器版本:

  • V2.9.0

命令值(cmd):

  • 410
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum":0,
		"getNum":10
	}
}
响应参数说明:
参数名层级类型条件描述备注
totalPages1int必填总页数
multiLockCardId2String必填多门卡ID
cardNo2String必填卡号
lossCardNo2String可选挂失卡号
endDate2long必填结束时间时间戳:秒
remark2string必填持卡人
isLock2int可选是否可开反锁0不允许
1允许
默认不允许
replaceFunction2int可选顶替前卡1顶替
2不顶替
默认不顶替
state2int可选卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
timePeriods2List可选可开时间段最多设置2个
beginTime3String可选时间段开始时间格式:HH:mm,如10:03
endTime3String可选时间段结束时间格式:HH:mm,如10:03
buildingCode3int必填楼栋号
roomCode3int必填房间号
subRoomName3String可选套房号
roomCardState3int必填房间卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
createTime2Long必填创建时间时间戳:秒
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总数,
		"totalPages":总页数,
		"list":[
			{
				"multiLockCardId":"fsdkvin="
				"cardNo":"21D4CBFD",
				"endDate":1700035797,
				"remark":"xxx",
				"isLock":1,
				"createTime":1700035797,
				"list":[
					{
						"buildingCode":1,
						"floorCode":1,
						"roomCode":109,
						"subRoomName":"A"
					}
				]
			}
		]
	}
}

总卡列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 402
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum":0,
		"getNum":10
	}
}
响应参数说明:
参数名层级类型条件描述备注
totalPages1int必填总页数
totalCardId2String必填总卡ID
lossCardNo2String可选挂失卡号
remark2String可选持卡人
cardNo2String必填卡号
endDate2long必填结束时间时间戳:秒
isLock2int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen2int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
state2int可选卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
replaceFunction2int可选顶替前卡1顶替
2不顶替
默认不顶替
createTime2Long必填创建时间时间戳:秒
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总数,
		"totalPages":总页数,
		"list":[
			{
				"totalCardId":"evvtwfbo=",
				"cardNo":卡号,
				"endDate":结束时间,
				"isLock":是否可开反锁,
				"createTime":创建时间,
				"remark":"wfr"
			}
		]
	}
}

楼栋卡列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 406
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum":0,
		"getNum":10
	}
}
响应参数说明:
参数名层级类型条件描述备注
totalPages1int必填总页数
floorCardId2String必填楼层卡ID
lossCardNo2String可选挂失卡号
cardNo2String必填卡号
remark2String必填持卡人
endDate2long必填结束时间时间戳:秒
isLock2int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen2int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
state2int可选卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
replaceFunction2int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods2List可选可开时间段最多设置2个
beginTime3String可选时间段开始时间格式:HH:mm,如10:03
endTime3String可选时间段结束时间格式:HH:mm,如10:03
buildingCode3int必填楼栋号
createTime2Long必填创建时间时间戳:秒
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总数,
		"totalPages":总页数,
		"list":[
			{
				"cardNo":卡号,
				"endDate":结束时间,
				"isLock":是否可开反锁,
				"createTime":创建时间
				"list":[
					{
						"buildingCode":楼栋号,
						"floorCode":楼层号
					}
				]
			}
		]
	}
}

楼栋卡列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 404
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum":0,
		"getNum":10
	}
}
响应参数说明:
参数名层级类型条件描述备注
totalPages1int必填总页数
buildingCardId2String必填楼栋卡ID
lossCardNo2String可选挂失卡号
cardNo2String必填卡号
remark2String必填持卡人
endDate2long必填结束时间时间戳:秒
isLock2int可选是否可开反锁0不允许
1允许
默认不允许
normallyOpen2int可选常开模式0常开关闭,正常模式
1常开打开,常开模式
默认常开关闭
state2int可选卡片状态0: 回收
1: 正常
2: 挂失
3: 顶替
replaceFunction2int可选顶替前卡1顶替
2不顶替
默认不顶替
timePeriods2List可选可开时间段最多设置2个
beginTime3String可选时间段开始时间格式:HH:mm,如10:03
endTime3String可选时间段结束时间格式:HH:mm,如10:03
buildingCode3int必填楼栋号
createTime2Long必填创建时间时间戳:秒
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总数,
		"totalPages":总页数,
		"list":[
			{
				"buildingCardId":"fdsmxmeo=",
				"cardNo":卡号,
				"endDate":结束时间,
				"isLock":是否可开反锁,
				"createTime":创建时间
				"list":[
					{
						"buildingCode":楼栋号
					}
				]
			}
		]
	}
}

退房卡

注意:只支持宾客卡制作退房卡,且授权已退房,门锁刷退房卡后宾客卡失效。

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 408
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号
cardDispenserSeq1String必填发卡器序列号唯一
checkInId1String必填授权ID
cardNo1String必填卡号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		总卡数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500300房间不存在
500502状态异常,操作失败
500400非法卡片,不是酒店加密卡
500504不支持该功能
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
--其他异常

应用场景

前提
第三方部署MQTT服务(推荐使用EMQX),工程锁系统MQTT host连接地址协议tcp://IP:端口,端口默认1883,第三方可根据需求调整端口
场景
通过MQTT对接,进行工程锁系统房间、设备操作等

房源管理

修改房间

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 108
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
isVisible1int可选是否房态图可见1可见
0不可见
roomTypeNum1int可选房间类型编号
pmsRoomName1String可选PMS房间名--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode": 门锁号,
		"roomName": 房间名
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

修改房间类型

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 111
入参说明:
参数名层级类型条件说明备注
roomTypeNum1int必填房间类型编号列表唯一
roomTypeName1String可选类型名称--
remark1String可选备注--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"roomTypeNum":房间类型编号,
		"roomTypeName": 类型名称,
		"remark": 备注
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

修改楼栋

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 105
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)1-255
floorNum1int可选楼层数量
buildingAddr1String可选地址--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode": 楼栋码,
		"buildingName": 楼栋名,
		"floorNum": 楼层数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

删除房间

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 109
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode": 门锁号
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

删除房间类型

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 112
入参说明:
参数名层级类型条件说明备注
roomTypeNum1int必填房间类型编号列表唯一
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"roomTypeNum":房间类型编号
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

删除楼栋

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 106
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)1-255
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode": 楼栋码
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 102
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode":楼栋号,
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
roomName2String必填房号房间名
subRoomName2String可选套房号A-Z大写
lockCode2String必填门锁号每个房间的门锁号都是唯一
isVisible2int必填是否显示到房态图1表示显示
0表示不显示
lockMac3String必填门锁MAC唯一
lockName3String可选门锁名称
hardwareVersion3String必填硬件版本号
softwareVersion3String必填软件版本号
gatewaySeq3String可选关联网关序列号该参数存在表示关联了网关,网关/网络取电开关类型为[1.2.3]此参数必填,网络取电开关没有序列号则需要gatewayMac判断
gatewayState3int可选网关/网络取电开关状态3 在线
4 离线
V1.9.0新增
gatewayMac3String可选网关/网络取电开关MAC该参数存在,表示门锁关联了网关或网络取电开关
V2.0.0新增
gatewayType1int可选网关/网络取电开关类型1:433+蓝牙网关
2:433网关
3:单蓝牙网关
5:网络取电开关
V2.0.0新增
bleProtocolVer3int可选蓝牙协议版本
adminAuthCode3String必填管理员鉴权码有权限调用所有蓝牙接口
generalAuthCode3String必填普通用户鉴权码没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
tempAuthCode3String必填临时鉴权码与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
roomTypeId2String必填房间类型ID--
electricNum2int可选门锁电量V1.9.0新增
supportCycleNormallyOpen2int可选是否支持周期常开设置1 支持
空或0不支持
V2.0.0新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			房间数据
		}]
	}
}

房间列表

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 102

功能变化:

  • 1.增加房间状态(roomState)返回
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode":楼栋号,
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
roomName2String必填房号房间名
subRoomName2String可选套房号A-Z大写
roomState2int必填房间状态1 闲置
2.出租
3.预定
4.到期
5.打扫
6.维护
7封房
V2.1.0版本新增
lockCode2String必填门锁号每个房间的门锁号都是唯一
isVisible2int必填是否显示到房态图1表示显示
0表示不显示
lockMac3String必填门锁MAC唯一
lockName3String可选门锁名称
hardwareVersion3String必填硬件版本号
softwareVersion3String必填软件版本号
gatewaySeq3String可选关联网关序列号该参数存在表示关联了网关,网关/网络取电开关类型为[1.2.3]此参数必填,网络取电开关没有序列号则需要gatewayMac判断
gatewayState3int可选网关/网络取电开关状态3 在线
4 离线
V1.9.0新增
gatewayMac3String可选网关/网络取电开关MAC该参数存在,表示门锁关联了网关或网络取电开关
V2.0.0新增
gatewayType1int可选网关/网络取电开关类型1:433+蓝牙网关
2:433网关
3:单蓝牙网关
5:网络取电开关
V2.0.0新增
bleProtocolVer3int可选蓝牙协议版本
adminAuthCode3String必填管理员鉴权码有权限调用所有蓝牙接口
generalAuthCode3String必填普通用户鉴权码没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
tempAuthCode3String必填临时鉴权码与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
roomTypeId2String必填房间类型ID--
electricNum2int可选门锁电量V1.9.0新增
supportCycleNormallyOpen2int可选是否支持周期常开设置1 支持
空或0不支持
V2.0.0新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			房间数据
		}]
	}
}

房间电量

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 113
入参说明:
参数名层级类型条件说明备注
------------
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
	}
}
响应参数说明:
参数名层级类型条件描述备注
roomList1List可选----
lockCode2String必填门锁号--
electricNum2int可选电量--
gatewayState2int可选网关状态3在线
4离线
门锁绑定网关有此参数
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"roomList":[
			{
				"lockCode":"1.0.2",
				"electricNum":20,
				"gatewayState":3
			}
		]
	}
}

房间类型列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 103
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
roomTypeName2String必填类型名称
roomTypeNum2int必填房间类型编号列表唯一
remark2String可选备注--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			房间类型数据
		}]
	}
}

房间门锁网关信号

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 114
注意:房间必须绑定网关
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.0"
	}
}
响应参数说明:
参数名层级类型条件描述备注
lockCode1String必填门锁号--
lockMac1String可选门锁MAC--
gatewaySeq1String可选网关序列号--
gatewayMac1String可选网关MAC--
gatewayChannel1int可选网关信道--
uplinkRssi1int可选上行信号--
downlinkRssi1int可选下行信号--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"lockCode":"1.0.2",
		"lockMac":"A3DF11113",
		"gatewaySeq":"2131231FFF",
		"gatewayMac":"AD341241",
		"gatewayChannel":6,
		"uplinkRssi":-80,
		"downlinkRssi":-20
	}
}

楼栋列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 101
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
buildingName2String必填楼栋名--
buildingCode2int必填楼栋码(唯一)--
floorNum2int必填楼层数--
buildingAddr2String可选楼栋地址--

边缘网关响应Sub(示例):

{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			楼栋数据
		}]
	}
}

添加房间

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 107
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)1-255
floorCode1int必填楼层码1-255
roomCode1int必填房间码1-3000000
isChannelMode1int必填是否通道模式1是
0否
isVisible1int必填是否房态图可见1可见
0不可见
roomTypeNum1int必填房间类型编号
replaceFunction1int必填顶替功能1使能
2禁用
pmsRoomName1String可选PMS房间名--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode": 楼栋码,
		"floorCode": 楼层码,
		"roomName": 房间名,
		"roomCode": 房间码,
		"isChannelMode": 是否通道模式,
		"isVisible": 是否房态图可见,
		"roomTypeNum":"房间类型编号",
		"replaceFunction":"顶替功能"
	}
}
响应参数说明:
参数名层级类型条件描述备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"lockCode":"门锁号"
	}
}

添加房间类型

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 110
入参说明:
参数名层级类型条件说明备注
roomTypeName1String必填类型名称--
remark1String可选备注--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"roomTypeName": 类型名称,
		"remark": 备注
	}
}
响应参数说明:
参数名层级类型条件描述备注
roomTypeNum1int必填房间类型编号列表唯一
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"roomTypeNum": 房间类型编号
	}
}

添加楼栋

本地服务器版本:

  • V1.6.0

命令值(cmd):

  • 104
入参说明:
参数名层级类型条件说明备注
buildingCode1int必填楼栋码(唯一)1-255
floorNum1int必填楼层数量
buildingAddr1String可选地址--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"buildingCode": 楼栋码,
		"buildingName": 楼栋名,
		"floorNum": 楼层数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间操作

下发挂失V2.1.0

  • cardNo和cardDispenserSeq不为空表示制作挂失卡,制作成功后,刷门锁后之前授权则失效(支持宾客卡授权制作挂失卡)。例如:房卡丢失,制作一张挂失卡刷门锁后,丢失房卡则不能开锁。
  • cardNo和cardDispenserSeq空表示通过网关下发挂失,下发挂失成功后,之前授权则失效(支持离线密码、宾客卡、自定义密码、自定义卡片、指纹、二维码授权下发挂失)
  • 下发挂失,房间门锁需要绑定网关

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 325
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取到房间的入住信息
cardDispenserSeq1String可选发卡器序列号制作挂失卡必填
cardNo1String可选卡号制作挂失卡必填
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增 制作挂失卡不支持延时下发
云端发布Pub(示例):
下发挂失
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"checkInId":"xxxx="
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

下发指纹、人脸结果推送

网关下发指纹、人脸结果推送给第三方

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 319
入参说明:
参数名层级类型条件说明备注
checkInId1String入住ID
resultCode1int结果码1成功
其他失败
reason1String原因失败原因
边缘网关发布Pub(示例):
{
    "cmd":319,
    "msgId":1390450371,
    "data":{
        "checkInId":"7wejyJDSCjc=",
        "resultCode":1
    }
}
云端不需要响应

二维码授权

  • 房间封房状态不允许自定义密码

本地服务器版本:

  • V2.2.0

命令值(cmd):

  • 326
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
注意:填手机号会同步公版APP或小程序授权二维码开锁功能
countryCode1int可选国家编码--
authorMode1int必填有效期授权方式1:有效期授权
2:周期重复时间段授权
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:hh:mm
dayEndTimes1String可选每日结束时间格式:hh:mm
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		二维码授权数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
lockCode1String必填门锁号每个房间的门锁号都是唯一
customerName1String必填房客名称--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID,
		"lockCode":"1.1.201",
		"customerName":"zzy"
	}
}

二维码重新授权(手机号)

  • 房间封房状态不允许重新授权
二维码授权有效,授权手机号码已填且二维码手机号同步公版状态失败(sendStatus=2),调用此接口重新同步二维码授权到公版

本地服务器版本:

  • V2.2.0

命令值(cmd):

  • 327
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		授权ID
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

人脸下发

  • 房间封房状态不允许人脸下发

本地服务器版本:

  • V2.5.0

命令值(cmd):

  • 330
注意:
1.门锁绑定网关,门锁和网关都需要支持指纹下发
2.人脸下发结果通过319命令推送给第三方
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
picture1String必填Base64编码图片必须经过“图片处理接口”获取
云端发布Pub(示例):
{
	"cmd": 330,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.204",
		"customerName":"zzy",
		"beginTime":1649984400,
		"endTime":1649990000,
		"picture":“xxxxxxxxxxxxxxxxxx=”
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
state1int必填状态1 已入住
3 待下发入住
customerName1String必填房客名称
picture1String必填base64数据--
边缘网关响应Sub(示例):
{
    "cmd":329,
    "msgId":122321323,
    "rslt":0,
    "rsn":"Success",
    "data":{
        "checkInId":"NmXMbUhcMk0=",
        "state":3,
		"customerName":"zzy"
		"picture":"xxxxxxx="
    }
}

入住解冻/冻结V2.1.0

  • 离线卡片、离线密码、人脸识别授权不自动解冻、冻结
  • 授权状态正常的支持冻结
  • 房间封房状态不支持冻结
  • 手机授权不绑定网关也支持冻结,指、密、卡、遥控则必须要绑定网关才能解冻、冻结

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 324
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取到房间的入住信息
enableType1int必填操作类型1解冻
2冻结
云端发布Pub(示例):
入住解冻/冻结
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"checkInId":"xxxx=",
		"enableType":1
	}
}
响应参数说明:
参数名层级类型条件描述备注
state1int必填状态1正常
7冻结
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": "xxxx=",
		"state":1
	}
}

入住详情

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 310
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取到房间的入住信息
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"checkInId":授权ID
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
buildingName1String必填楼栋名称
roomName1String必填房间名称
state1int必填状态1正常
3 待下发生效
4 挂失
5 待下发挂失
6待下发续住
7冻结
authType1int必填授权类型1.指纹
2密码
4卡片
16二维码
64人脸下发
128 APP远程
129微信授权
256 人脸识别授权
authorMode1int必填有效期类型1有效时间段
2周期
3永久
4临时
addMode1int可选授权添加方式1远程下发
3离线生成
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间authorMode = 0x02有效
格式:hh:mm
dayEndTimes1String可选每日结束时间authorMode = 0x02有效
格式:hh:mm
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
countryCode1int可选国家编码
appKey1int可选手机APP授权0或不填 ,表示不授权
1授权
miniProgramKey1int可选微信授权0或不填,表示不授权
1授权
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
normallyOpen1int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock1int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
password1String可选密码--
qrCode1String可选二维码图Base64编码,authType=16有效
v2.2.0新增
sendStatus1int可选二维码手机号同步公版状态authType=16 且 手机号码不为空有效
1成功
2失败
3下发中
v2.2.0新增
picture1String可选Base64编码图片authType = 64 或 authType = 256 有效
2.5.0版本新增
auth1list可选授权详情
relaId2String必填联动授权关系ID
channelType2Int必填通道类型5大门
6楼栋
7楼层
8房间
9套房
roomName2String必填房间名称
state2int必填状态1已入住
2待下发退房
3待下发入住
4挂失
5待下发挂失
6待下发续住
sendStatus2int必填状态1成功
2下发失败
3下发中
password2String可选钥匙内容authType = 2 密码
authType = 4 卡片
useNum2int可选使用次数255或空表示无限次
限制次数,最大是254次
picture2String可选人脸图片base64编码
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		授权详情数据
	}
}

删除单个入住

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 305
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取到房间的入住信息
cardDispenserSeq1String可选发卡器序列号删除宾客卡授权,卡片如需要回收,填此参数
cardNo1String可选卡号删除宾客卡授权,卡片如需要回收,填此参数
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"checkInId":授权ID
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

删除小程序(推送)

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 309
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取到房间的入住信息
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":门锁号,
		"checkInId":授权ID
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

制作宾客卡(多门卡)

  • 房间封房状态不允许制作宾客卡

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 301

服务器接口版本(version):

  • 1.1
注意:

1.接口版本1.1支持制作多门卡,多门卡最多支持4个房间 2.多门卡只支持第一个房间为套房,后面出现套房则自动授权主房间

入参说明:
参数名层级类型条件说明备注
lockCode1List<String>必填门锁号每个房间的门锁号都是唯一
最多4个房间,只支持第一个是套房,其他三个不能是套房
通过房间列表获取
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
customerName1String必填房客名称
checkInFlag1int可选入住标记0 立即入住(默认)
以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取入参开始时间(建议为当前时间)作为本次入住授权的开始时间(时间精度为小时)
1 其他时间入住
取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码
normallyOpen1int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock1int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
floorList1list可选可开楼层2.7.3新增
floorCode2int可选楼层码2.7.3新增
云端发布Pub(示例):
{
	"cmd": 301,
	"msgId": 122321323,
	"version":1.1,
	"data": {
		"lockCode":["1.2.202","1.2.204"],
		"cardDispenserSeq": "MNR63218751FB5",
		"customerName":"zzy",
		"beginTime":1649984400,
		"endTime":1650090000,
		"phoneNo":13535455351,
		"cardNo":"E370DE92"
		"floorList" : [{"floorCode" : 1},{"floorCode" :2,},{"floorCode" :3,},{"floorCode" :4,},{"floorCode" :5,}]
	}
}
响应参数说明:
参数名层级类型条件描述备注
list1List必填--
lockCode2String必填门锁号--
checkInId2String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 301,
	"msgId": 122321323,
  	  "version":1.1,
	"data": {
		"lockCode": ["5.2.201"],
		"cardDispenserSeq": "MNR600E48A4A71",
		"customerName": "zzy",
		"beginTime": 1693452689,
		"endTime": 1696044689,
		"phoneNo": 13535455351,
		"cardNo": "E35F81A2",
		"floorList" : [{"floorCode": 1},{"floorCode": 2},{"floorCode": 3},{"floorCode": 4},{"floorCode": 5}]
	}
}

异常码

异常码异常描述
500001参数异常
500300房间不存在
500322制卡失败,xxx房间信息不全
500321制卡失败,xxx没有安装门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500400非法卡片,不是酒店加密卡
500528xxx房间已存在授权
500533操作失败,房间已封房
500404安裝卡,请先进行回收
500405操作失败,加密卡非法
--其他异常

制作宾客卡

  • 房间封房状态不允许制作宾客卡

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 301
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
cardDispenserSeq1String必填发卡器序列号唯一
cardNo1String必填卡号
customerName1String必填房客名称
checkInFlag1int可选入住标记0 立即入住(默认)
以已入住房客授权的开始时间作为本次入住授权的开始时间,如对应房源内没有已入住的房客,则取入参开始时间(建议为当前时间)作为本次入住授权的开始时间(时间精度为小时)
1 其他时间入住
取入参开始时间作为本次入住授权的起始时间(可以为未来时间,时间精度为小时)
备注:
房间门锁开启顶替功能,如果入住时间触发其他授权顶替,服务器则会有异常提示,第三方需要调整入住时间。
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码
normallyOpen1int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock1int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		宾客卡数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

周期常开设置

本地服务器版本:

  • V2.0.0

命令值(cmd):

  • 321
门锁必须绑定网关,门锁必须支持周期常开设置功能
入参说明:
参数名层级类型条件说明备注
lockCode1String可选门锁号每个房间的门锁号都是唯一
门锁号或门锁Mac 二者必填其一
通过房间列表获取
lockMac1String可选门锁Mac门锁号或门锁Mac 二者必填其一
通过房间列表获取
cycleNormallyOpen1int必填周期常开1 开启
2 关闭
beginTime1long可选开始时时间戳,单位:秒
endTime1long可选结束时间时间戳,单位:秒
weeks2int可选星期数据bit位域表示
例如:
bit.0=1 表示周一
bit.1=2 表示周二
bit.2=4 表示周三
timeList2List可选时间段最多设置7个
dayStartTimes3String可选每日起始时间HH:mm
dayEndTimes3String可选每日结束时间HH:mm
serialNumber3String可选序列号1~7
云端发布Pub(示例):
周期常开关闭
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1",
		"cycleNormallyOpen":2
	}
}
周期常开开启
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode": "1.2.1",
		"cycleNormallyOpen": 1,
		"beginTime": 1653494400,
		"endTime": 1653580799,
		"list": [{
			"weeks": "1",
			"timeList": [{
				"dayStartTimes": "11:00",
				"dayEndTimes": "12:10",
				"remark": "1",
				"serialNumber": 1
			}]
		}, {
			"weeks": "2",
			"timeList": [{
				"dayStartTimes": "12:10",
				"dayEndTimes": "13:20",
				"remark": "3",
				"serialNumber": 1
			}]
		}]
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

图片处理

  • 下发人脸时,图片数据必须较过此接口校验通过获取

本地服务器版本:

  • V2.5.0

命令值(cmd):

  • 329
入参说明:
参数名层级类型条件说明备注
picture1String必填Base64编码图片--
lockCode1String可选门锁号V2.7.5新增
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"picture":"xcvawesdfsadfsdad"
	}
}
响应参数说明:
参数名层级类型条件描述备注
picture1String必填Base64编码图片--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"picture":"xcvawesdfsadfsdad"
	}
}

小程序入住

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 308
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
checkInId1String必填授权ID
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String必填手机号码
countryCode1int必填国家编码
miniProgramKey1int可选微信授权0或不填,表示不授权
1授权
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		小程序入住数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

待处理入住列表

本地服务器版本:

  • V1.8.0

命令值(cmd):

  • 312
入参说明:
参数名层级类型条件描述备注
startNum1int开始记录数默认为0
pageSize1int分页大小默认10,最大50
buildingCode1int楼栋码--
floorCode1int楼层码--
roomName1String房间名称--
customerName1String房客名称--
cardNo1String卡号--
checkInAuthType1int入住类型1 指纹
2自定义密码
3离线卡片
4手机授权
5离线密码
6下发卡片
7人脸识别
8二维码(V2.5.0新增)
9人脸下发(V2.5.0新增)
state1int状态2待下发退房
3待下发入住
5待下挂失
6待下发续住
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		 "startNum": 0,
         "pageSize": 10
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
checkInId2String可选入住ID--
lockCode2String可选门锁号--
updateTime2long可选时间--
buildingName2String可选楼栋名--
floorCode2int可选楼层码--
roomName2String可选房间名--
checkInName2String可选姓名--
checkInAuthType2int可选授权类型1.指纹
2自定义密码
3离线卡片
4手机授权
5离线密码
6下发卡片
7人脸识别
8二维码(V2.5.0新增)
9人脸下发(V2.5.0新增)
state2int可选状态2待下发退房
3待下发入住
5待下发挂失
6待下发续住
keyContent2String可选钥匙内容--
响应示例
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 1,
		"totalPages": 1,
		"list": [{
			"checkInId": "+LD/tJyceg=",
			"lockCode": "1.1.103",
			"updateTime": 1642750740,
			"buildingName": "A栋",
			"floorCode": 1,
			"roomName": "A103",
			"checkInName": "QWEQWE",
			"checkInAuthType": 2,
			"state": 3
		}]
	}
}

忽略待处理入住

本地服务器版本:

  • V1.8.0

命令值(cmd):

  • 313
入参说明:
参数名层级类型条件说明备注
checkInId1String必填授权ID通过接口“待处理入住列表”获取
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"checkInId": "+LD/tJysceg="
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
响应示例
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间入住列表同步

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 307
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":门锁号
	}
}
响应参数说明:
参数名层级类型条件描述备注
list1List可选--
checkInId2String必填授权ID
state2int必填状态1正常
3 待下发生效
4 挂失
5 待下发挂失
6待下发续住
7冻结
authType2int必填授权类型1.指纹
2密码
4卡片
16二维码
64人脸下发
128 APP远程
129微信授权
256 人脸识别授权
authorMode2int必填有效期类型1有效时间段
2周期
3永久
4临时
addMode2int可选授权添加方式1远程下发
3离线生成
weeks2int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes2String可选每日起始时间格式:hh:mm
dayEndTimes2String可选每日结束时间格式:hh:mm
idType2int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
countryCode2int可选国家编码
appKey2int可选手机APP授权0或不填 ,表示不授权
1授权
miniProgramKey2int可选微信授权0或不填,表示不授权
1授权
useNum2int可选使用次数不填或255表示无限次
限制次数,最大是254次
normallyOpen2int可选常开模式1常开打开,常开模式
2常开关闭,正常模式
不传默认2,常开关闭
isLock2int可选反锁功能1:反锁功能开启,可开反锁
2:反锁功能关闭,不能开反锁
不传默认2,反锁功能关闭
password2String可选密码--
picture2String可选Base64编码图片authType = 64 或 authType = 256 有效
2.5.0版本新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"list": [
			{
				入住数据
			}
		]
	}
}

房间解封/封房

  • 门锁必须要绑定网关

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 323
入参说明:
参数名层级类型条件说明备注
enableType1int必填操作类型1解封
2封房
云端发布Pub(示例):
房间解封/封房
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1",
		"enableType":1
	}
}
响应参数说明:
参数名层级类型条件描述备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
roomState1int必填房间状态1 闲置
2 出租
3预定
4到期
5打扫
6维护
7封房
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"lockCode": "1.2.1",
		"roomState":1
	}
}

房间退房

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 306
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":门锁号
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间退房

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 306

服务器接口版本(version):

  • 1.1
注意:

1.全部退房,所有的授权直接退房,(宾客卡相当无卡退房) 2.房间退房,先回收宾客卡(多门卡)授权,再退房间授权,房间授权存在其他宾客卡则该房间只删除卡号相关的授权不退房其他授权 3.宾客卡(多门卡)也可使用回收卡片,回收成功后删除宾客卡其房间相关授权达到退房效果

入参说明:
参数名层级类型条件说明备注
lockCode1List<String>必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
operType1int必填操作类型1.全部退房
2.房间退房
cardDispenserSeq1String可选发卡器序列号operType=2有效且必填
cardNo1String可选卡号operType=2 有效且必填
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增
云端发布Pub(示例):
{
	"cmd": 306,
	"msgId": 122321323,
	"version":1.1,
	"data": {
		"operType":2,
		"lockCode":["1.2.202","1.2.204"],
		"cardDispenserSeq": "MNR63218751FB5",
		"cardNo":"E370DE92"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

手机授权

  • 房间封房状态不允许手机授权

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 315
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
countryCode1int可选国家编码
appKey1int可选手机APP授权0或空表示不授权
1 表示授权
appKey和miniProgramKey 二者必填其一
miniProgramKey1int可选微信授权0或空表示不授权
1 表示授权
appKey和miniProgramKey 二者必填其一
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		手机授权数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

异常码

异常码异常描述
500001参数异常
500002授权失败,请稍后再试
500003授权失败,锁已被初始化,请重新添加门锁
500007操作失败
500300房间不存在
500316房间未关联门锁
500503重复授权
500504不支持该功能
500530未开启该功能
500541未开启远程通讯功能,请先开启远程通讯功能

手机授权

  • 房间封房状态不允许制作宾客卡

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 315
支持APP邮箱、APP手机、微信小程序授权
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
email1String可选邮箱1.邮箱或手机号码必填其一
2.高级设置需要开启APP授权(邮箱),此参数有效
3.V2.1.0版本新增
phoneNo1String可选手机号码1.邮箱或手机号码必填其一
2.高级设置需要开启APP授权(手机号)或微信授权,此参数有效
countryCode1int可选国家编码
appKey1int可选手机APP授权0或空表示不授权
1 表示授权
appKey和miniProgramKey 二者必填其一
高级设置需要开启APP授权(邮箱)或APP授权(手机号),此参数有效
miniProgramKey1int可选微信授权0或空表示不授权
1 表示授权
appKey和miniProgramKey 二者必填其一
高级设置需要开启微信授权权限,此参数有效
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		手机授权数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

异常码

异常码异常描述
500001参数异常
500002授权失败,请稍后再试
500003授权失败,锁已被初始化,请重新添加门锁
500007操作失败
500300房间不存在
500316房间未关联门锁
500503重复授权
500504不支持该功能
500530未开启该功能
500541未开启远程通讯功能,请先开启远程通讯功能

手机授权使能/禁用

  • 房间封房状态不允许手机授权使能/禁用
  • 授权冻结状态不允许授权授权使能/进制

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 316
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
checkInId1String必填授权ID可通过接口“房间入住列表同步”获取
authType1int必填授权类型128 APP远程
129微信授权
enableType1int必填操作类型1启用
2禁用
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

指纹下发

  • 房间封房状态不允许指纹下发

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 318
注意:
1.发卡器读取指纹
2.门锁绑定网关,门锁和网关都需要支持指纹下发
3.指纹下发结果通过319命令推送给第三方
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
cardDispenserSeq1String必填发卡器序列号获取指纹标识所在发卡器
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
fingerPrintSign1String可选指纹标识fingerPrint和fingerPrintSign二者必填其一
发卡器获取
云端发布Pub(示例):
{
	"cmd": 318,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.204",
		"cardDispenserSeq": "MNR63218751FB5",
		"customerName":"zzy",
		"beginTime":1649984400,
		"endTime":1649990000,
		"fingerPrintSign":1649990938227
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
state1int必填状态1 已入住
3 待下发入住
customerName1String必填房客名称v2.2.0新增
fingerPrintSign1String必填指纹标识发卡器获取
v2.2.0新增
边缘网关响应Sub(示例):
{
    "cmd":318,
    "msgId":122321323,
    "rslt":0,
    "rsn":"Success",
    "data":{
        "checkInId":"NmXMbUhcMk0=",
        "state":3
    }
}

离线密码

  • 1、如果密码的有效期小于1年,密码的有效期,精确到小时 如: 开始时间:2019-06-21 11:16:14 结束时间:2019-06-21 13:16:14 那么有效时间为:2019-06-21 11:00:00---2019-06-21 13:00:00
  • 2、如果密码的有效期大于1年,密码的有效期精确到月 如: 开始时间:2019-06-21 11:16:14 结束时间:2020-09-21 11:16:14 那么有效时间为:2019-06-01 00:00:00---2020-09-01 00:00:00

如果密码开不了锁,在三方面进行排查 1、门锁时间是否正确(通过同步门锁时间来解决) 2、生成密码的aesKey、鉴权码是否和门锁上的一致(门锁初始化后,aesKey和鉴权码都会重新生成) 3、同一个时间生成的第一个密码输入可以开门,删除后再次相同开始结束时间生成的密码是无法开门的

  • 房间封房状态不允许授权离线密码

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 304
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
phoneNo1String可选手机号码
countryCode1int可选国家编码--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		离线密码数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

续住

  • 房间封房状态不允许续住
  • 授权冻结状态不允许续住

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 317
注意:
  1. 离线密码不支持续住
  2. 单个续住支持手机、指纹、密码、宾客卡(不包括多门卡)、下发卡片授权
  3. 卡号续住支持宾客卡续住(包括多门卡)
入参说明:
参数名层级类型条件说明备注
operType1int必填操作类型1 单个续住
2 卡号续住(包括多门卡)
checkInId1String可选授权IDoperType=1 必填,可通过接口“房间入住列表同步”获取
endTime1long必填结束时间单位:秒
cardDispenserSeq1String可选发卡器序列号operType=2 或者 operType=1且授权为离线开卡 必填
cardNo1String可选卡号operType=2 或者 operType=1且授权为离线开卡 必填
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增
云端发布Pub(示例):
{
	"cmd": 317,
	"msgId": 122321323,
	"data": {
		"checkInId":"09dyHkOYj6Q=",
		"operType":1,
		"endTime":1660525200
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

自定义卡片下发

  • 房间封房状态不允许自定义卡片下发

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 302
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
cardNo1String必填卡号
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码
authorMode1int必填有效期授权方式1:有效期授权
2:周期重复时间段授权
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:hh:mm
dayEndTimes1String可选每日结束时间格式:hh:mm
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		自定义卡片数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

异常码

异常码异常描述
500001参数异常
500008不支持Emoji表情
500104手机号码错误
500204门锁不支持该功能
500300房间不存在
500316房间未关联门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500503重复授权
500533操作失败,房间已封房
500707卡片已被房客xxx录入使用,请从房客xxx的卡片列表删除或更换卡片
--其他异常

自定义卡片下发

  • 房间封房状态不允许自定义卡片下发

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 302
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
cardNo1String必填卡号
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码
authorMode1int必填有效期授权方式1:有效期授权
2:周期重复时间段授权
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
dayStartTimes1String可选每日起始时间格式:hh:mm
dayEndTimes1String可选每日结束时间格式:hh:mm
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		自定义卡片数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
lockCode1String必填门锁号每个房间的门锁号都是唯一
V2.1.0版本新增
cardNo1String必填卡号V2.1.0版本新增
customerName1String必填房客名称V2.1.0版本新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID,
		"lockCode":"1.1.201",
		"cardNo":"AFAFAFAF",
		"customerName":"XXXX"
	}
}

异常码

异常码异常描述
500001参数异常
500008不支持Emoji表情
500104手机号码错误
500204门锁不支持该功能
500300房间不存在
500316房间未关联门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500503重复授权
500533操作失败,房间已封房
500707卡片已被房客xxx录入使用,请从房客xxx的卡片列表删除或更换卡片
--其他异常

自定义密码

  • 房间封房状态不允许自定义密码

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 303
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
password1String必填密码6-16位数字
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		自定义密码数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID
	}
}

异常码

异常码异常描述
500001参数异常
500002文件异常,请联系供应商处理!
500204门锁不支持该功能
500300房间不存在
500316房间未关联门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500533操作失败,房间已封房
--其他异常

自定义密码

  • 房间封房状态不允许自定义密码

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 303
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
password1String必填密码6-16位数字
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码--
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		自定义密码数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
lockCode1String必填门锁号每个房间的门锁号都是唯一
V2.1.0版本新增
customerName1String必填房客名称V2.1.0版本新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID,
		"lockCode":"1.1.201",
		"customerName":"zzy"
	}
}

异常码

异常码异常描述
500001参数异常
500002文件异常,请联系供应商处理!
500204门锁不支持该功能
500300房间不存在
500316房间未关联门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500533操作失败,房间已封房
--其他异常

自定义密码

  • 房间封房状态不允许自定义密码

本地服务器版本:

  • V2.2.0

命令值(cmd):

  • 303
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
password1String必填密码6-16位数字
customerName1String必填房客名称
beginTime1long必填开始时间时间戳:秒
endTime1long必填结束时间时间戳:秒
idType1int可选证件类型1身份证
2护照
3回乡证
4军官证
5士兵证
6学生证
7导游证
8驾驶证
phoneNo1String可选手机号码公寓场景必传
countryCode1int可选国家编码--
authorMode1int必填有效期授权方式1:有效期授权
2:周期重复时间段授权
v2.2.0新增
weeks1int可选周期authorMode = 0x02有效,按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
若authorMode!= 0x02,则Weeks = 0
如1001011就表示周日,周四,周二,周一
v2.2.0新增
dayStartTimes1String可选每日起始时间格式:hh:mm
v2.2.0新增
dayEndTimes1String可选每日结束时间格式:hh:mm
v2.2.0新增
useNum1int可选使用次数不填或255表示无限次
限制次数,最大是254次
v2.2.0新增
delaySend1int可选是否延时下发1: 延时下发
非1 或 空 默认下发方式
V2.8.0新增
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		自定义密码数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
checkInId1String必填授权ID--
lockCode1String必填门锁号每个房间的门锁号都是唯一
V2.1.0版本新增
customerName1String必填房客名称V2.1.0版本新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"checkInId": 授权ID,
		"lockCode":"1.1.201",
		"customerName":"zzy"
	}
}

异常码

异常码异常描述
500001参数异常
500002文件异常,请联系供应商处理!
500204门锁不支持该功能
500300房间不存在
500316房间未关联门锁
500324xxx房间时间段内已有人预约,请调整选择的时间范围
500330非立即入住,开始时间不能小于xxx,避免“在住房客”被顶替掉导致无法开锁
500331入住的时间段内已有人入住,为避免顶替导致有人无法开锁,请调整选择的时间范围
500533操作失败,房间已封房
--其他异常

获取周期常开设置

本地服务器版本:

  • V2.0.0

命令值(cmd):

  • 322
入参说明:
参数名层级类型条件说明备注
lockCode1String可选门锁号每个房间的门锁号都是唯一
门锁号或门锁Mac 二者必填其一
通过房间列表获取
lockMac1String可选门锁Mac门锁号或门锁Mac 二者必填其一
通过房间列表获取
云端发布Pub(示例):
周期常开关闭
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1"
	}
}
响应参数说明:
参数名层级类型条件描述备注
lockMac1String必填门锁Mac--
lockCode1String可选门锁号可选,门锁未绑定房间则门锁号为空
cycleNormallyOpen1int必填周期常开1 开启
2 关闭
beginTime1long可选开始时时间戳,单位:秒
endTime1long可选结束时间时间戳,单位:秒
weeks2int可选星期数据bit位域表示
例如:
bit.0=1 表示周一
bit.1=2 表示周二
bit.2=4 表示周三
timeList2List可选时间段最多设置7个
dayStartTimes3String可选每日起始时间HH:mm
dayStartTimes3String可选每日结束时间HH:mm
serialNumber3String可选序列号1~7
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"lockCode": "1.2.1",
		"lockMac": "AAAA123132"
		"cycleNormallyOpen": 1,
		"beginTime": 1653494400,
		"endTime": 1653580799,
		"list": [{
			"weeks": 1,
			"timeList": [{
				"dayStartTimes": "11:00",
				"dayEndTimes": "12:10",
				"serialNumber": 1,
				"remark": "1"
			}]
		}, {
			"weeks": 2,
			"timeList": [{
				"dayStartTimes": "12:10",
				"dayEndTimes": "13:20",
				"serialNumber": 1,
				"remark": "3"
			}]
		}]
	}
}

获取门锁系统参数和状态V3.0.0

本地服务器版本:

  • V3.0.0

命令值(cmd):

  • 332
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.1.111"
	}
}
响应参数说明:
参数名层级类型条件描述备注
lockTime1long可选门锁系统当前时间时间戳,单位秒
electricNum1int可选最新电量--
electricNumTime1long可选最后上报电量时间时间戳,单位秒
isSound1int可选语音启闭0: 无关门启闭设置功能
1: 开关门语音打开
2: 开关门语音关闭
sysVolume1int可选系统音量0: 表示音量不可调节
其他表示正常系统音量
sysLanguage1int可选系统语言1: 简体中文
2: 繁体中文
3: 英文
4: 越南语
5: 泰语
lockOpen1int可选开锁模式0: 无开锁模式设置功能
1: 单一开锁
2: 组合开锁
normallyOpen1int可选软件版本0: 无常开模式设置功能
1: 常开模式启用
2: 常开模式关闭
isLock1int可选反锁功能启闭0: 无反锁功能
1: 反锁功能启用
2: 反锁功能关闭
isTamperWarn1int可选防撬报警启闭0: 无防撬报警功能
1: 防撬报警功能启用
2: 防撬报警功能关闭
isLockCoreWarn1int可选锁芯报警启闭0: 无锁芯报警功能
1: 锁芯报警功能启用
2: 锁芯报警功能关闭
isLockCap1int可选锁头盖报警启闭0: 无锁头盖报警功能
1: 锁头盖报警启用
2: 锁头盖报警关闭
initStatus1int可选初始状态标志0: 门锁未初始化状态
1: 非初始状态
timezoneOffset1int时区门锁时区--
noPowerOpenNo1int可选低电量后剩余开锁次数--
normallyOpenFlag1int可选锁常卡状态标志0: 已关锁
1: 已开锁,门锁处于常开状态
isLockFlag1int可选反锁状态标识0: 无反锁开关
1: 未打开反锁
2: 已打开反锁
bigBoltFlag1int可选大方舌标志0: 无大方舌开关
1: 大方舌缩进状态
2 :大方舌伸出状态(锁门状态)
boltFlag1int可选斜舌标志0: 无斜舌开关
1: 斜舌缩进状态
2: 斜舌伸出状态
isNoOpenFlag1int可选防撬开关标志0: 无防撬开关检测
1: 防撬开关未动作
2: 防撬开关已动作(可能触发强拆事件)
isCover1int可选锁头盖开关状态0: 无锁头盖开关
1: 锁头盖报警启用
2: 锁头盖报警关闭
isClose1int可选已关门标志0: 无关门开关检测
1: 已开门
2: 已关门
coreFlag1int可选锁芯开关0: 无锁芯检测
1: 锁芯未插入钥匙
2: 锁芯已插入钥匙
replaceFunction1int顶替功能0: 不支持 1:开启 2:关闭
antiCopyFunction1int防复制功能0: 不支持 1:开启 2:关闭
keyTrialErrorAlarmEn1int试错告警0: 不支持 1:开启 2:关闭
noneCloseVoiceAlarmEn1int未关门告警语音使能0: 不支持 1:开启 2:关闭
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

设置门锁系统参数V3.0.0

本地服务器版本:

  • V3.0.0

命令值(cmd):

  • 331
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
sysLanguage1int可选门锁语言1简体中文,2繁体中文,3英文,4越南语,5泰语
注意: 如果填了该参数下面参数不建议填
isSound1int可选门锁语音0:不更改设置1:语音开启2:语音关闭
sysVolume1int可选门锁音量1-50:不更改设置1~5:系统音量
lockOpen1int可选开锁模式0:不改变开锁模式,1:单一开锁,2:组合开锁
normallyOpen1int可选常开模式0:不更改常开模式;1:启用常开模式;2:关闭常开模式;
isLock1int可选反锁功能0:不更改设置 1:反锁功能开启 2:反锁功能关闭
isTamperWarn1int可选防撬报警0:不更改设置 1:防撬报警开启 2:防撬报警关闭
isLockCoreWarn1int可选锁芯报警0:不更改设置 1:锁芯报警开启 2:锁芯报警关闭
isLockCap1int可选锁头盖报警0:不更改设置 1:锁头盖报警开启 2:锁头盖报警关闭
replaceFunction1int可选顶替功能0:不更改设置 1:开启 2:关闭
antiCopyFunction1int可选防复制功能0:不更改设置 1:开启 2:关闭
keyTrialErrorAlarmEn1int可选试错告警0:不更改设置 1:开启 2:关闭
noneCloseVoiceAlarmEn1int可选未关门告警语音使能0:不更改设置 1:开启 2:关闭
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode": "1.9.901",
		"isSound": "0",
		"sysVolume": "0",
		"lockOpen": "0",
		"normallyOpen": "0",
		"isLock": "0",
		"isTamperWarn": "0",
		"isLockCoreWarn": "0",
		"isLockCap": "0",
		"replaceFunction": "1",
		"antiCopyFunction": "1",
		"keyTrialErrorAlarmEn": "0",
		"noneCloseVoiceAlarmEn": "0"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

远程开锁

本地服务器版本:

  • V1.7.0

命令值(cmd):

  • 311

####### 门锁必须要绑定网关

入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500110邮箱格式错误
500104手机号码错误
500300房间不存在
500503重复授权
500530未开启该功能
500537操作失败,房间xxx已存在xxx二维码授权
500533操作失败,房间已封房
500504不支持该功能
500316房间未关联门锁
--其他异常

远程开锁

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 311

####### 门锁必须要绑定网关

入参说明:
参数名层级类型条件说明备注
lockCode1String可选门锁号每个房间的门锁号都是唯一
lockCode和lockMac二者必填其一
通过房间列表获取
lockMac1String可选门锁号门锁Mac
lockCode和lockMac二者必填其一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常码

异常码异常描述
500001参数异常
500110邮箱格式错误
500104手机号码错误
500300房间不存在
500503重复授权
500530未开启该功能
500537操作失败,房间xxx已存在xxx二维码授权
500533操作失败,房间已封房
500504不支持该功能
500316房间未关联门锁
--其他异常

重新下发待处理入住

本地服务器版本:

  • V1.8.0

命令值(cmd):

  • 314
入参说明:
参数名层级类型条件说明备注
relaId1String必填联动授权关系ID请在“入住详情”接口中获取该参数
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"relaId": "ycMbDLEtfXY="
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
响应示例
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

HTLock MQTT接入指南

MQTT是一个安全级别很高的接入方式,这个接入可以让客户的信息进行安全的传输,但是这种接入方式会比较困难,最少需要用到两台电脑或两台服务器进行部署HTLock系统和EMQX服务,这两个服务是必须要分开放的,具体如何接入可以看MQTT对接流程

注意:MQTT通常都会有DESKEY进行加解密数据的,如要不加密传输可以去666后台设置那边把DESKEY关闭即可。

发布:/localhost_hotel/酒店AppId/dev_pub 订阅:/localhost_hotel/酒店AppId/dev_sub 例子: /localhost_hotel/b5d0769c550d4f6699c8ecbd668f8132/dev_pub /localhost_hotel/b5d0769c550d4f6699c8ecbd668f8132/dev_sub

MQTT因为跟HTTP的对接方式有点区别,MQTT只需要把需要收到订阅的服务器连接到EMQX服务上并且订阅了HTLock的消息,就会收到订阅。

远程操作是指门锁关联了网关的情况下,对门锁进行的操作。具体功能如下: 自定义下发密码 自定义下发卡片 离线密码 房间入住列表 入住详情 远程开锁 待处理列表 手机授权 续住 周期常开设置 获取周期常开信息 设置门锁系统参数 读取门锁系统参数和状态

HTLock MQTT对接支持两种方式删除授权,一种是只对单个入住进行退房的删除单个授权。 还有一种是房间退房,该接口可以把一个房间里面的所有授权都退房处理,也可以对离线卡片的授权进行退房操作。

HTLock MQTT是支持对授权进行续住操作的,续住只需要调续住接口即可。

下发的授权是在HTLock是支持冻结/解冻的,只需要调入住冻结/解冻接口即可。

在房间关联网关的情况下,可以对房间进行封房/解封的操作,已经封房的房间是无法进行下发授权等操作的,只能解封后才能下发。

找不到宾客卡的情况下,可以通过制作挂失卡让丢失的宾客卡进行挂失处理,调挂失卡片接口即可。

当门锁下发失败的时候可以通过看待处理列表进行确认哪个授权是下发失败的,然后调重新下发待处理接口。 如若是想下发新授权,不想对待处理列表的授权进行处理的话,可以调忽略待处理入住接口。

首先需要把发卡器指纹采集仪添加到该HTLock下。 然后通过发卡器MAC调发卡器录入指纹模式接口,然后方手指上去进行按压。 按压过程中可以通过订阅发卡器按压指纹推送查看按压次数和相关推送。 在推送中拿到指纹标识或指纹特征值给到指纹下发接口进行下发,订阅后即可收到成功下发指纹推送。 注意:发卡器按压指纹的时候只有最后一包才会有指纹标识和指纹特征值推送。

把需要下发的人脸转换成baes64编码,然后调我们的图片处理接口对编码进行处理。 拿到图片处理返回的baes64编码后调下发人脸接口进行下发,订阅后能看到下发结果。

二维码授权是只有个别门锁才支持的功能,调二维码授权接口成功后会返回baes64编码,把编码转换成图片后扫二维码即可开门。

MQTT对接是支持对HTLock的房源进行操作的。具体功能如下: 楼栋列表 房间列表 房间类型列表 添加楼栋 修改楼栋 删除楼栋 添加房间 修改房间 删除房间 添加房间类型 修改房间类型 删除房间类型 房间电量 房间网关信号

想要一张卡开HTLock所有的门锁可以通过制作总卡接口制作出来,该卡片可以开HTLock下所有的房间。 楼栋卡是对指定楼栋制作一张开门的卡,该卡片可以开指定楼栋的所有房间,可通过制作楼栋卡接口完成。 楼层卡是对指定楼栋楼层制作一张开门卡,该卡片可以对指定的楼栋楼层进行开锁的卡片,可通过制作楼层卡接口完成。

查看房间操作日志可以通过房间日志列表进行查询。 HTLock事件推送会通过事件推送接口进行推送。

数据加密

####服务器版本V2.4.0开始由HTLock本地设置开启MQTT加密并设置DES秘钥,本地不开启对接则以明文模式(JSON)通讯。

保证数据安全,针对房源管理、设备操作、授权操作、卡片操作、日志同步,data里数据进行DES加密
请求格式:
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": "xxxxxxxxxxxxxxx"
}
响应格式:
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码",
	"rsn": "原因",
	"data": "xxxxxxxxxxxxxxx"
}

日志同步

事件推送

注意:method参数为固定值,第三方可以根据该参数做对应格式解析

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 501

####1.通用事件推送

入参说明:
参数名层级必选类型说明备注
method1String标识方法固定值:hxjCommonEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
logTypeFlag1int事件Flag当eventType=18时有效,为空时,表示未知异常,0 按键短路,1 存储器异常,2 触摸芯片异常,3 低压检测电路异常,4 读卡电路异常,5 检卡电路异常,6 指纹通讯异常,7 RTC晶振电路异常
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
####2.添加钥匙事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjAddKeyEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=8 表示添加钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次
####3.删除钥匙事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjDeleteKeyEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=9 表示删除钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int删除方式0 按编号删除
1 按类型删除
2 按内容删除
3 按用户ID删除
keyGroupId1int钥匙所属用户IDlogTypeFlag=3有效
keyGroupName1String钥匙所属用户名logTypeFlag=3有效
keyType1int钥匙类型logTypeFlag=1 按位域置1,则删除指定钥匙类型钥匙
logTypeFlag=2 结合lockKeyId固定一个钥匙删除
lockKeyId1int钥匙IDlogTypeFlag=0有效
keyContent1int钥匙内容适用离线密码未使用 按内容删除
####4.周期关闭事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjCycleCloseEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=49 表示周期关闭事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示关闭当天的周期开锁,bit0=1 星期一
####5.周期开启事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjCycleOpenEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=48 表示周期开锁开启事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks2int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天周期开启
例如:bit0=1 星期一
dayEndTimes3String每日结束时间-
####6.使能禁止钥匙事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjEnableKeyEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=28 表示使能进制设置事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int使能禁止flaglogTypeFlag=1按钥匙ID使能
logTypeFlag=2按钥匙类型使能
logTypeFlag=3按用户ID使能
logTypeFlag=4按钥匙ID禁止
logTypeFlag=5按钥匙类型禁止
logTypeFlag=6按用户ID禁止
keyType1int钥匙类型logTypeFlag=2 和 logTypeFlag=5 生效
lockKeyId1int钥匙IDlogTypeFlag=1 和 logTypeFlag=4 生效
keyGroupId1int用户IDlogTypeFlag=3 和 logTypeFlag=6 生效
keyGroupName1String用户名logTypeFlag=3 和 logTypeFlag=6 生效
####7.错误开锁事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjErrorOpenEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=41 表示错误开锁事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int钥匙校验结果1钥匙在门锁端无法通过校验, 开锁失败
2钥匙在门锁端可以通过校验, 但门锁反锁, 钥匙无法开反锁, 开锁失败
keyContent1int钥匙内容keyType=2 keyContent为密码
keyType=4 keyContent为卡号
####8.开锁事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjOpenLockEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=4 表示开锁事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
combine1int是否组合0非组合
1组合
normalOpen1int是否常开0非常开
1常开
insideOpen1int是否门内开锁0门外
1门内
keyContent11String钥匙内容keyType=2 keyContent1为密码
keyType=4 keyContent1为卡号
keyGroupId21int用户IDcombine=1有效
keyGroupName21String用户名combine=1有效
keyType21int钥匙类型combine=1有效
lockKeyId21int钥匙IDcombine=1有效
useNum21int剩余有效次数combine=1有效
####9.系统参数设置推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjSystemSetEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=27 表示系统参数事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
lockOpen1可选int开锁模式1~2,1-单一开锁; 2-组合开锁
normallyOpen1可选int常开模式1~2,1-常开模式启用; 2-常开模式关闭
isSound1可选int语音启闭1~2,1开关门语音打开; 2开关门语音关闭
sysVolume1可选int系统音量0~5,0-表示音量不可调节,其他表示音量大小
isTamperWarn1可选int防撬报警启闭0无防撬报警功能; 1防撬报警启动; 2防撬报警功能关闭
isLockCoreWarn1可选int锁芯报警启闭0无锁芯报警功能;1锁芯报警启动; 2锁芯报警功能关闭
isLock1可选int反锁功能启闭0~2 0无反锁开关;1-反锁功能启用; 2-反锁功能关闭
isLockCap1可选int锁头盖报警启闭1~2,1-启用,2关闭
sysLanguage1可选int系统语言1~5,1:简体中文 2:繁体中文 3:英文 4:越南文 5:泰文
####10.按内容修改钥匙事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjUpdateKeyByContentEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=46 表示按内容修改钥匙事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次
####11.修改密码事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjUpdatePwEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=24 表示修改密码事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
lockKeyId1int钥匙ID-
####12.修改钥匙有效期事件推送
入参说明
参数名层级必选类型说明备注
method1String标识方法固定值:hxjUpdateKeyValidityEventPush
lockCode1String房间的门锁号--
eventType1int事件类型详情见附录:事件类型
eventType=34 表示修改钥匙有效期事件
electricNum1int门锁电量--
eventTime1long事件触发时间单位:秒
logTypeFlag1int修改方式1 按钥匙ID修改
2 按用户ID修改
authorMode1int授权方式1 有效期授权
2 周期授权
beginTime1long授权开始时间单位:秒
endTime1long授权结束时间单位:秒
weeks1int星期数bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效,bit0=1 星期一
authorMode=2 有效
dayStartTimes1String每日起始时间
authorMode=2 有效
dayEndTimes1String每日结束时间
authorMode=2 有效
keyContent1String钥匙内容keyType = 2 表示密码
keyType =4 表示卡号
useNum1int使用次数0~254:表示剩余有效次数
255:表示无限次
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		事件数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

事件推送(废弃)

  • V1.5.3起支持
  • V1.9.0废弃

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 501
触发:告警事件上报、电量变动事件
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
eventType1int必填事件类型0x01:强拆报警
0x02:非法操作报警(错误次数超限等),系统已锁定
0x03:低电量报警
0x05:布防
0x06:撤防
0x0a:反锁
0x0b:反锁解除
0x0c:撬锁芯报警
0x12:故障报警
eventFlag1int可选故障类型当eventType=0x12时故障类型为空,表示未知异常
0 按键短路
1 存储器异常
2 触摸芯片异常
3 低压检测电路异常
4 读卡电路异常
5 检卡电路异常
6 指纹通讯异常
7 RTC晶振电路异常
electricNum1int可选电量--
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		事件数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间日志列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 502
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号房间唯一
beginTime1longlong事件开始时间时间戳 单位:秒
2.7.0版本新增
endTime1long事件结束时间时间戳 单位:秒
2.7.0版本新增
startNum1int可选开始节点默认 0
pageSize1int可选获取数量默认 10
最大 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":门锁号,
		"startNum":开始节点,
		"pageSize":"获取数量"
	}
}
响应参数说明:
参数名层级类型条件描述备注
eventTime2long必填事件触发时间单位:秒
ectricNum2int必填电量
logType2int必填日志类型
logData2Map<String,Object> 必填日志内容不同日志类型,日志内容不同
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum":总数,
		"totalPages":总页数,
		"list":[
			{
				"eventTime":日志触发时间,
				"ectricNum":电量,
				"logType":"日志类型",
				"logData":{
					日志内容
				}
			}
		]
	}
}

当logType为 4 开锁事件 41 开锁失败 10 门锁反锁 11 门锁解除 30 门已上锁 32 机械钥匙开锁 17 常开:关锁 43 周期常开:开锁

logData定义如下:

| 参数名 | 层级 | 类型 | 条件 | 描述 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||combine |3| int| 可选| 是否组合开锁| 当logType=4有效
1表示组合开锁

normalOpen3int可选是否常开当logType=4有效
1表示常开
keyGroupName3String可选用户名
keyGroupId3int可选用户ID
keyType3int可选钥匙类型1 指纹
2 密码
4 卡片
8 遥控
128 电子钥匙
8添加钥匙
9删除钥匙
24修改钥匙
28使能钥匙
logData定义如下:

| 参数名 | 层级 | 类型 | 条件 | 描述 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||logTypeFlag| 3| int| 可选 |日志类型标志| logType=8添加:
logTypeFlag=0自定义下发
logTypeFlag=1算法生成
logType=9删除:
logTypeFlag=0按钥匙ID
logTypeFlag=1按钥匙类型
logTypeFlag=2按钥匙内容
logTypeFlag=3按用户ID
logType=24修改密码:
logTypeFlag=0修改密码
logTypeFlag=1按钥匙ID
logTypeFlag=2按用户
logTypeFlag=3按内容
logType=28使能:
logTypeFlag=1按钥匙ID
logTypeFlag=2按钥匙类型
logTypeFlag=3按用户ID
logType=28禁止:
logTypeFlag=4按钥匙ID
logTypeFlag=5按钥匙类型
logTypeFlag=6按用户ID| |keyType| 3| int| 可选| 钥匙类型| | |lockKeyId |3 |int| 可选| 钥匙ID| | |keyGroupId|3 |int |可选| 用户ID| | |keyGroupName |3| String| 可选| 用户名| | |beginTime |3 |int |可选| 钥匙有效期开始时间| 时间戳:秒| |endTime| 3| int| 可选| 钥匙有效期结束时间| 时间戳:秒| |weeks| 3 |int| 可选| 周期| 按位域bit0~bit6分别表示,对应bit位数置1,则表示当天钥匙有效。
bit0表示周一,bit6表示日。如周二、周三有效,weeks=6,6=0000110| |dayStartTime| 3| String |可选 |周期时间段| 开始时间| |dayEndTime |3 |String| 可选| 周期时间段| 结束时间| |vaildNumber |3| int |可选| 剩余次数| 空或255表示无限 ,0-254表示相应的次数| |operUserName| 3 |String |可选 |操作人| | |operUserId |3| int| 可选| 操作人ID|--|

当logType为 1强拆 2非法操作 3低电量 12撬锁芯报警 14门未关好 15未关门报警 18故障报警 21系统锁定状态解除 35两天未开锁 47未验证开锁 ######logData定义如下: | 参数名 | 层级 | 类型 | 条件 | 描述 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||logTypeFlag| 3 |int |可选 |日志类型标志 |logType=18
为空时,表示未知异常
logTypeFlag=0按键短路
logTypeFlag=1存储器异常
logTypeFlag=2触摸芯片异常
logTypeFlag=3低压检测电路异常
logTypeFlag=4读卡电路异常
logTypeFlag=5检卡电路异常
logTypeFlag=6指纹通讯异常
logTypeFlag=7RTC晶振电路异常|

当logType为 27门锁系统设置 5布防 6撤防 19状态更新事件 20切换系统语言 22申请时间同步 48 周期性门锁开启 49 周期性门锁关闭 ######logData定义如下:

| 参数名 | 层级 | 类型 | 条件 | 描述 | 备注 | | ----- | ---- | ---- | ---- | ---- | ---- ||openMode |3 |int| 可选| 开锁模式| logType=27有效
0不改变
1单一开锁
2组合开锁

normallyOpenMode3int可选常开模式logType=27有效
0不改变
1启用
2关闭
volume3int可选音量大小logType=27有效
preventionAlram3int可选防撬报警logType=27有效
0不改变
1启用
2关闭
lockCylinderAlram3int可选锁芯报警logType=27有效
0不改变
1启用
2关闭
antiLockFunction3int可选反锁功能logType=27有效
0不改变
1启用
2关闭
lockCoverAlarm3int可选锁头盖报警logType=27有效
0不改变
1启用
2关闭
language3int可选系统语言logType=27有效
1简体中文
2繁体中文
3英文
4越南语
5泰语

设备异常码

异常码

异常码异常描述
406超时
501设备不在线或未连接云端
30001没有检测到卡片
30002鉴权失败
30003写卡失败
30004读卡失败
30005请放入对应卡片
30006不支持该卡片
30101传感器异常
30102检测不到指纹
30103采集失败
30104接收包有误
30105指令执行有误
30106功能与加密等级不匹配
30201网络繁忙
30202参数错误
30203不支持的命令

异常码

异常码异常描述
403设备正忙,请稍后再试
406超时
501设备不在线或未连接云端
700010扫描超时
700011连接门锁失败
700012协议错误
700013网关没有绑定此设备
700014网关设备已满
700015解密异常
700016网关不存在此设备
700017扫描不到蓝牙设备
700018请重新绑定一下门锁
700019不支持的指令
700020参数错误
700022设备非空
700099未知异常

设备操作

发卡器列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 204
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
cardDispenserMac2String必填发卡器MAC(唯一)
cardDispenserSeq2String必填发卡器序列号(唯一)
cardDispenserName2String必填发卡器名称
hardwareVersion2String必填硬件版本号
softwareVersion2String必填软件版本号
cardDispenserState2int必填状态3在线
4离线
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			发卡器数据
		}]
	}
}

发卡器录指纹模式

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 207
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号--
云端发布Pub(示例):
{
	"cmd": 207,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq": "MNR63218751FB5"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 207,
	"msgId": 122321323,
	"rslt": 0,
	"rsn": "Success"
}

发卡器指纹(推送)

本地服务器版本:

  • V1.9.0

命令值(cmd):

  • 208
入参说明:
参数名层级类型条件说明备注
resultCode1int确认码0 成功
其他失败
reason1String失败原因--
indexNum1int当前次数成功:必填
totalNum1int总次数成功:必填
indexNum = totalNum表示按压完成
fingerPrintSign1String指纹标识indexNum = totalNum必填
1 小时内有效
V2.0.0版本永久有效
cardDispenserSeq1String发卡器序列号V2.0.0版本新增
fingerPrint1String指纹特征值indexNum = totalNum必填
V2.7.3新增
边缘网关发布Pub(示例):
{
	"cmd": 208,
	"msgId": 1108326094,
	"data": {
		"fingerPrintSign": 1649926886723,
		"resultCode": 0,
		"indexNum": 4,
		"totalNum": 4
	}
}
云端不需要响应

发卡器读卡数据上报(推送)

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 205
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号(唯一)
isblank1int必填白卡判断0表示白卡
1表示异常卡
2正常卡
3空卡
4无卡
cardType1int可选卡片类型1 设置卡
2 设置验证卡
3 清除卡
4 安装卡
5 校时卡
6 入网卡
7 退网卡
32 宾客卡
33 总卡
34 楼栋卡
35 楼层
36 挂失卡
37 退房卡
value2String可选--
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		读卡数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------

云端响应Sub(示例):

{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

取电开关全局设置

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 210
房间必须已经添加网络取电开关
不满足取电条件的延时断电时间
入参说明:
参数名层级类型条件说明备注
powerOffTime1int必填不满足取电条件的延时断电时长单位:秒
不填表示不设置
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"powerOffTime":3
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

取电开关取电模式设置

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 211
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1",
		"mode":1
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

取电开关白名单设置

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 212
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
lockCode1string必填门锁号可通过房间列表获取
addType1int必填添加类型1 新增
2 删除
3 覆盖
keyType1int必填授权类型4 卡片
authList1List<String>卡号格式:["23FDAA43","23FDAF13"]
addType!=2必填
一个取电开关最多下发20张卡号,如若超过将不做保存并且无法对该取电开关生效
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
	   "lockCode":"1.2.1",
      "addType": 1,
	  "keyType": 4,
	  "authList": ["23FDAA43","23FDAF13"]
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

异常取电记录

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 213
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始记录数默认为0
pageSize1int可选分页大小默认10,最大50
buildingCode1int可选楼栋码--
floorCode1int可选楼层码--
roomName1String可选房间名称--
beginTime1long可选开始时间单位: 秒
endTime1long可选结束时间单位: 秒
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {

		
	}
}
响应参数说明:
参数名层级类型条件描述备注
list1long可选--单位: 秒
eventTime2long可选操作时间时间戳,单位:秒
operUserName2string可选操作人--
logContent2string可选操作内容--
subRoomName2String套房号A-Z大写
keyContent2string可选钥匙内容--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间取电记录

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 214
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始记录数默认为0
pageSize1int可选分页大小默认10,最大50
switchState1int可选状态1 正常
2 异常
不传全部
beginTime1long可选开始时间单位: 秒
endTime1long可选结束时间单位: 秒
lockCode1string必填门锁号可通过房间列表获取
填了此参数下方参数无效
buildingCode1int可选楼栋码--
floorCode1int可选楼层码--
roomName1String可选房间名称--
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1",
		"mode":1
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
list1long可选--单位: 秒
subRoomName2String套房号A-Z大写
eventTime2long可选操作时间时间戳,单位:秒
currentState2int可选当前状态1远程送电
2远程断电
3供电
4断电
5开锁后,临时取电1分钟
lastState2int可选上一个状态1远程送电
2远程断电
3供电
4断电
5开锁后,临时取电1分钟
stateChangeMode2int可选状态切换方式1计时结束
2前台操作
3宾客卡
4反锁
5管理卡
keyContent2string可选钥匙内容--
switchState2int可选状态1:正常
2:异常
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间的取电状态

本地服务器版本:

  • V3.1.1

命令值(cmd):

  • 215
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1"
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
electricState1int可选状态1:断电
2:供电
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

房间送电/断电/恢复设置

本地服务器版本:

  • V1.9.1

命令值(cmd):

  • 320
房间必须已经添加网络取电开关
入参说明:
参数名层级类型条件说明备注
lockCode1String必填门锁号每个房间的门锁号都是唯一
通过房间列表获取
operMode1INT必填操作方式1 送电
2 断电
3恢复正常模式
endTime1LONG可选结束时间,时间戳,单位:秒operMode=1时,必填,表示送电结束时间
例如endTime=1660299768,1660299768表示的时间为:2022-08-12 18:22:48,表示一直到2022-08-12 18:22:48,房间都是送电的状态
operMode=2时,必填,表进断电结束时间
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"lockCode":"1.2.1",
		"operMode":1,
		"endTime":1650948541
		
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

更新发卡器信息(推送)

发卡器信息发生变化时,边缘网关推送发卡器数据给第三方云端

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 203
入参说明:
参数名层级类型条件说明备注
cardDispenserMac1String必填发卡器MAC(唯一)
cardDispenserSeq1String必填发卡器序列号(唯一)
hardwareVersion1String必填硬件版本号
softwareVersion1String必填软件版本号
cardDispenserState1int必填状态3在线
4离线
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		发卡器数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

更新网关/网络取电开关信息(推送)

网关/网络取电开关信息发生变化时,边缘网关推送数据给第三方云端

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 201
入参说明:
参数名层级类型条件说明备注
gatewaySeq1String可选网关序列号(唯一)类型为1、2、3网关时必填,网络取电开关没序列号
gatewayName1String必填网关/网络取电开关名称
gatewayState1int必填状态3在线
4离线
gatewayType1int必填类型1:433+蓝牙网关
2:433网关
3:单蓝牙网关
5:网络取电开关
V2.0.0新增
边缘网关发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		网关数据
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

网关/网络取电开关列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 202
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
gatewayTypes1List<Integer>可选类型1.网关列表[1,2,3](为空默认查询网关)
2.网络取电开关列表[5]
V2.0.0新增
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
gatewayMac2String必填网关/取电开关MAC(唯一)
gatewaySeq2String可选网关序列号(唯一)类型为1、2、3网关时必填,网络取电开关没序列号
gatewayName2String必填网关/取电开关名称
hardwareVersion2String必填硬件版本号
softwareVersion2String必填软件版本号
gatewayState2int必填状态3在线
4离线
gatewayType2int必填类型1:433+蓝牙网关
2:433网关
3:单蓝牙网关
5:网络取电开关
V2.0.0新增
lockCode2String可选门锁号gatewayType=5有效,lockCode存在表示取电开已关绑定房间
V2.0.0新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			网关数据
		}]
	}
}

退出发卡器录指纹模式

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 209
入参说明:
参数名层级类型条件说明备注
cardDispenserSeq1String必填发卡器序列号--
云端发布Pub(示例):
{
	"cmd": 209,
	"msgId": 122321323,
	"data": {
		"cardDispenserSeq": "MNR63218751FB5"
	}
}
响应参数说明:
参数名层级类型条件描述备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 209,
	"msgId": 122321323,
	"rslt": 0,
	"rsn": "Success"
}

门禁/梯控列表

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 206
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
lockType1int必填类型9门禁
10梯控
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量,
		"lockType":9
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
lockMac2String必填Mac(唯一)
lockName2String必填名称(唯一)
lockType2int必填类型
electricNum2int可选电量
lockState2String必填状态3在线
4离线
hardwareVersion2int必填硬件版本--
softwareVersion2int必填软件版本--
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			门禁/梯控数据
		}]
	}
}

门禁/梯控列表

本地服务器版本:

  • V2.1.0

命令值(cmd):

  • 206
入参说明:
参数名层级类型条件说明备注
startNum1int可选开始节点默认 0
getNum1int可选获取数量默认 50
lockType1int必填类型9门禁
10梯控
云端发布Pub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"startNum": 开始节点,
		"getNum": 获取数量,
		"lockType":9
	}
}
响应参数说明:
参数名层级类型条件描述备注
listSum1int必填总数--
totalPages1int必填总页数--
list1list可选--
lockMac2String必填Mac(唯一)
lockName2String必填名称(唯一)
lockType2int必填类型
electricNum2int可选电量
lockState2String必填状态3在线
4离线
hardwareVersion2int必填硬件版本--
softwareVersion2int必填软件版本--
adminAuthCode2String必填管理员鉴权码有权限调用所有蓝牙接口
V2.1.0版本新增
generalAuthCode2String必填普通用户鉴权码没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
V2.1.0版本新增
tempAuthCode2String必填临时鉴权码与普通授用户权码一样,没有OTA升级和删除蓝牙锁这2个接口权限,其它蓝牙接口都有权限
V2.1.0版本新增
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"listSum": 总条数,
		"totalPages": 总页数,
		"list": [{
			门禁/梯控数据
		}]
	}
}

鉴权

更新秘钥

####服务器版本V2.4.0废弃本接口,由HTLock本地设置开启MQTT加密并设置DES秘钥,本地不开启对接则以明文模式(JSON)通讯。

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 12
入参说明:
参数名层级类型条件描述备注
desKey1String必填Des秘钥由终端服务管理
AES加密(参照附录)
自定义的秘钥长度=8
expireTime1int可选有效时间单位:秒
不填为永久
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {
		"desKey":"xxffff==",
		"expireTime":20000
	}
}
响应参数说明:
参数名层级必选类型说明备注
------------
边缘网关响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
	}
}

获取秘钥

本地服务器连接MQTT服务成功后,随机5-60秒内向终端服务获取Des秘钥

####服务器版本V2.4.0废弃本接口,由HTLock本地设置开启MQTT加密并设置DES秘钥,本地不开启对接则以明文模式(JSON)通讯。

本地服务器版本:

  • V1.5.3

命令值(cmd):

  • 11
入参说明:
参数名层级必选类型说明备注
------------
{
	"cmd": 命令值,
	"msgId": 122321323,
	"data": {}
}
响应参数说明:
参数名层级类型条件描述备注
desKey1String必填Des秘钥由终端服务管理
AES加密后传递给本地服务(参照附录)
终端生成秘钥长度=8
expireTime1int可选有效时间单位:秒
不填为永久
云端响应Sub(示例):
{
	"cmd": 命令值,
	"msgId": 122321323,
	"rslt": "状态码:0成功,其他失败",
	"rsn": "原因",
	"data": {
		"desKey": "xxxxxxx="
	}
}

附录

###AES加密

作用:终端Des秘钥加密,涉及获取秘钥和更新秘钥接口

加密说明:

1.根据规则生成AES秘钥

2.将生成的AES秘钥当作AES加密的向量以及加密的KEY,填充模式为”AES/CBC/PKCS5Padding”,对Des秘钥加密。

3.加密结果进行base64编码。

Java代码:
private static String encrypt(String desKey, String aesKey) throws Exception {
	IvParameterSpec zeroIv = new IvParameterSpec(aesKey.getBytes());
	SecretKeySpec key = new SecretKeySpec(aesKey.getBytes(), "AES");
	Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
	cipher.init(Cipher.ENCRYPT_MODE, key, zeroIv);
	return Base64.getEncoder().encodeToString(cipher.doFinal(desKey.getBytes("UTF-8")));
}

###DES加密

生成DES加密KEY

DES的KEY:abcdefgh 偏移量:abcdefgh 填充模式:DES/CBC/PKCS5Padding

1.先DES加密

2.再base64编码

如123456,进行DES加密,得到byte数组

再进行Base64编码:opfVWWpnmcY=

Java代码:
加密:
public static String encrypt(String data, String desKey) throws Exception {
    if (data == null) return null;
	DESKeySpec dks = new DESKeySpec(desKey.getBytes());
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
    SecretKey securekey = keyFactory.generateSecret(dks);
    Cipher cipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
    cipher.init(Cipher.ENCRYPT_MODE, securekey, new IvParameterSpec(desKey.getBytes()));
	return new BASE64Encoder().encode(cipher.doFinal(data.getBytes()));
}

解密:
public static String decrypt(String data, String desKey) throws Exception {
    if (data == null) return null;
    BASE64Decoder decoder = new BASE64Decoder();
    byte[] buf = decoder.decodeBuffer(data);
	DESKeySpec dks = new DESKeySpec(desKey.getBytes());
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
	SecretKey securekey = keyFactory.generateSecret(dks);
    Cipher cipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
	cipher.init(Cipher.DECRYPT_MODE, securekey, new IvParameterSpec(desKey.getBytes()));
    byte[] bt= cipher.doFinal(buf);
    return new String(bt);
}

命令定义

鉴权

| 功能 | 命令值 |备注| | :------------: | :------------: | |获取秘钥| 11|--| |更新秘钥| 12|--|

房源类

| 功能 | 命令值 |备注| | :------------: | :------------: | |楼栋列表| 101|--| |房间列表 |102 |--| |房间类型列表| 103 |--| |添加楼栋 |104 |--| |修改楼栋| 105 |--| |删除楼栋| 106 |--| |添加房间| 107 |--| |修改房间| 108 |--| |删除房间| 109 |--| |添加房间类型 |110 |--| |修改房间类型| 111 |--| |删除房间类型|112 |--| |房间电量|113 |V1.9.0新增| |房间门锁网关信号|114 |V1.9.0新增|

设备类

| 功能 | 命令值 |备注| | :------------: | :------------: | |添加/更新网关|201 |--| |网关列表| 202 |--| |添加/更新发卡器| 203 |--| |发卡器列表| 204 |--| |发卡器读卡数据上报| 205 |--| |门禁/梯控列表| 206 |--| |发卡器录指纹模式| 207 |V1.9.0新增| |发卡器指纹推送| 208 |V1.9.0新增|

授权类

| 功能 | 命令值 |备注| | :------------: | :------------: | |制作宾客卡| 301 |--| |自定义卡片下发| 302 |--| |自定义密码| 303 |--| |离线密码 |304 |--| |删除单个授权| 305 |--| |房间退房 |306 |--| |房间入住列表同步 |307 |--| |小程序授权 |308 |--| |取消小程序授权 |309 |--| |入住详情 |310 |--| |远程开锁 |311 |--| |待处理入住列表 |312 |--| |忽略待处理入住 |313 |--| |重新下发待处理入住 |314 |--| |手机授权| 315 |V1.9.0新增| |手机授权使能/禁用| 316 |V1.9.0新增| |续住| 317 |V1.9.0新增| |指纹下发| 318 |V1.9.0新增| |下发指纹结果推送| 319 |V1.9.0新增| |送电/断电/恢复设置| 320 |V1.9.1新增|

卡片操作

| 功能 | 命令值 |备注| | :------------: | :------------: | |制作总卡| 401|-- | |总卡列表| 402|-- | |制作楼栋卡| 403|-- | |楼栋卡列表| 404|-- | |制作楼层卡| 405|-- | |楼层卡列表| 406|-- | |收回卡片| 407|-- | |退房卡| 408|V1.9.0新增|

日志同步

| 功能 | 命令值 |备注| | :------------: | :------------: | |事件上报| 501|--| |房间日志列表| 502|--|

日志类型eventType

注意:第三方可以根据需求解析eventType处理
描述
01强拆报警
02非法操作报警(错误次数超限等),系统已锁定
03低电量报警
04开锁
05布防
06撤防
07胁迫开锁
08添加授权
09删除授权
10反锁
11反锁解除
12撬锁芯报警
13门铃事件
14门未关好(假锁报警)
15未关门报警
17门锁已关闭常开
18故障报警
20切换系统语言
21系统锁定状态解除
22时间同步
23恢复出厂设置
24修改密码
25未拔钥匙事件
26打开锁头盖事件
27系统参数设置事件
28使能与禁止
30上锁事件
31斜舌缩进事件(压把手事件)
32机械钥匙开锁事件
34修改钥匙有效期
41错误开锁事件
43自动开锁
46按照钥匙内容修改钥匙信息事件
47未验证开锁
48周期开启事件
49周期关闭事件

生成AES秘钥规则

酒店AppId:b5d0769c550d4f6699c8ecbd668f8132

1.对AppId取MD5:41B35B7B1EC2207533E59E391D39E3B8(大写) md5生成摘要,固定长度32,范围为0-9,A-F

2.将摘要信息 前8个字节后8个字节异或 41 B3 5B 7B 1E C2 20 75 33 E5 9E 39 1D 39 E3 B8 41 ^ 33 = 72 B3 ^ E5 = 56 5B ^ 9E = C5 7B ^ 39 = 42 1E ^ 1D = 03 C2 ^ 39 = FB 20 ^ E3 = C3 75^ B8= CD 得:7256C54203FBC3CD

3.将摘要信息截取12~20 得:207533E5

4.将7256C54203FBC3CD 第2 4 6 8 个字节与 207533E5异或 56 ^ 20 = 76 42 ^ 75 = 37 FB ^ 33 = C8 CD ^ E5 = 28 得:7637C828

5.7637C828替换7256C54203FBC3CD的第 1 3 5 7个字节 72 56 C5 42 03 FB C3 CD 76 37 C8 28 得AES秘钥:76563742C8FB28CD

钥匙类型keyType

描述
1指纹
2密码
4卡片
8遥控器
128APP远程
129微信
256人脸识别

一卡通对接

边缘网关(服务器)通过同步第三方系统中间库人员数据,进行房间操作

接入说明

1.接入方式

便于第三方快速接入,少改动的原则,对接方式采用“中间库的方式”。由第三方提供“数据库”和“人员表”,联网工程锁系统通过第三方提供的“数据库”将“人员表”中的数据同步本地。
增量同步数据:“人员表”中“更新时间”为必填项,联网工程锁系统每次同步中间库数据都是根据“更新时间”,只有“人员表”中发生变化数据的“更新时间”大于上次同步数据的“最大更新时间”才会同步到本地。如未同步过的人员且已注销,则不会同步到师生人员列表里面

2.人员表定义

表名:sync_usercard_all
字段:
字段名类型条件描述备注
userIdString必填人员主键--
userNameString可选人员姓名--
userNumbString必填人员编号编号唯一
sexint可选人员性别0-未知 1-男 2-女
deptNameString可选部门名称--
categoryint可选人员类型第三方自定义
userStatusint可选人员状态0-正常 1-注销
cardNoint可选卡流水号--
factoryFixIdString可选物理卡号userStatus为0或者cardStatus为1有物理卡
userStatus为1或者cardStatus不为1物理卡号就为空
酒店版本v1.6.0开始卡号必须为16进制,同发卡器读卡一致,字段类型由long变更为String
酒店版本v2.2.0开始卡号可自行设置规则
cardStatusint可选卡状态1-正常 2-挂失 3-无卡 4-退卡 7-冻结
createTimedatetime必填创建时间--
updateTimedatetime必填更新时间--

目前边缘服务器,提供了[HTTP]与[MQTT]两种对接方式:

1.若服务器与第三方的应用在同一个局域网内,http的功能接口满足项目功能需求的情况下,建议考虑优先使用HTTP的方式对接。

2.若服务器与第三方的应用不在一个局域网内,类似于云PMS的,建议可以考虑MQTT的对接方式。

关于一卡通对接,指的类似于一卡通、企业员工管理平台等平台将员工的卡号信息同步到边缘服务器的数据库中,可以有效更好的同步更新授权。