1.4.4.1. 添加设备
新设备投入使用dbs时调用,添加成功后设备将关联应用和公司,同一设备只能被一个公司添加。
Request:
POST /v1.0/device/add
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"timeZone": "+08:00",
"timezone": "EST5EDT",
"alais": "一楼打卡机"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
timeZone | String | N | 设备时区,为空时默认东八区,即+08:00 |
timezone | String | N | 夏令时时区id对应附录中的key,部分常见国家及地区参考附录:夏令时时区ID说明,可通过Java JDK中的时区类获取具体时区信息。 |
alais | String | N | 设备别名,作为方便识别设备使用 |
注意
该接口对设备时区设置有“timeZone”和“timezone”两个入参。若设备所在地区需要使用夏令时,则请传“timezone”,该入参会默认关联夏令时信息并下发给设备;若设备所在地区不需要使用夏令时,则传“timeZone”即可;当二者都为空,则默认设备时区为东八区;当二者都有传时,以“timezone”为准。
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.2. 修改设备
Request:
POST /v1.0/device/modify
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"timeZone": "+08:00",
"timezone": "EST5EDT",
"alais": "一楼打卡机"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
timeZone | String | N | 设备时区,为空时默认东八区,即+08:00 |
timezone | String | N | 夏令时时区id对应附录中的key,部分常见国家及地区参考附录:夏令时时区ID说明,可通过Java JDK中的时区类获取具体时区信息。 |
alais | String | N | 设备别名,作为方便识别设备使用 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
注意事项:
本接口对非必填的属性,仅需要传入需要改动的属性,当不包含某个属性key值时,表示此属性不变动。
1.4.4.3. 删除设备
第三方调用接口删除设备,系统会自动删除设备信息并解绑所有与设备的绑定关系。
Request:
POST /v1.0/device/delete
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
注意事项:
部分设备在被解绑后会自动清除设备上的记录,请谨慎删除。
1.4.4.4. 查询设备信息
查询该企业下符合条件的设备列表,若没有指定查询条件,则默认返回该企业下所有设备列表。
Request:
POST /v1.0/device/query
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"needDetails": 1
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | N | 设备序列号,精确查询 |
needDetails | Integer | N | 是否需要详细信息,当该参数为1,返回基本信息和详细信息;当该参数为空或不为1,则只返回基本信息 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success",
"payload": {
"results": [{
"sn": "33998400021314",
"timezone": "+08:00",
"alais": "一楼打卡机",
"status": 1,
"enable": 1,
"localIp": "192.168.213.18",
"remoteIp": "110.80.38.76",
"fwVersion": "Ver 9.0.0.0-20190613",
"model": "iFace702",
"type": "0",
"details": {
"protocol": "1",
"protocolVer": "2.2.14",
"model": "iFace702",
"macAddress": "00:17:61:11:88:0f",
"verifyRecords": 1,
"userCount": 1,
"faceCount": 1,
"fingerCount": 1,
"palmPrintCount": 1,
"lastRequestTimeStamp": 1571990712,
"supportAcc": "1",
"supportFinger": "1",
"supportFace": "1",
"supportFacePhoto": "1",
"supportPalmPrint": "1",
"supportRemoteFinger": "1",
"supportRemoteFacePhoto": "1",
"supportRemotePalmPrint": "2",
"supportRemoteFace": "2"
}
}]
}
}
参数名 | 类型 | 描述 |
---|---|---|
sn | String | 设备序列号 |
timezone | String | 设备时区 |
alais | String | 设备别名 |
status | Integer | 设备在线状态,1代表在线,0代表离线 |
enable | Integer | 设备启用状态,1代表启用,0代表禁用 |
localIp | String | 设备内网Ip地址 |
remoteIp | String | 设备公网Ip地址 |
fwVersion | String | 设备固件版本号 |
model | String | 设备型号 |
type | String | 设备类型,0代表考勤设备,1代表门禁设备,2代表人证设备,4代表门禁控制器,999代表未知设备 |
details | String | 设备详细信息,其他为设备基本信息 |
protocol | String | 设备通讯协议,“0” pull,“1”push,“2” best,“3” ufo,“4” best-w,“5” best-t |
protocolVer | String | 协议版本 |
model | String | 设备型号 |
macAddress | String | 设备MAC地址 |
verifyRecords | Integer | 核验记录数 |
userCount | Integer | 人员数 |
faceCount | Integer | 人脸数 |
fingerCount | Integer | 指纹数 |
palmPrintCount | Integer | 掌纹数 |
lastRequestTimeStamp | Long | 设备最新请求时间戳 |
supportAcc | String | 是否支持门禁功能,“0”不支持,“1”支持,“2”未知 |
supportFinger | String | 是否支持指纹,“0”不支持,“1”支持,“2”未知 |
supportFace | String | 是否支持近红外人脸,“0”不支持,“1”支持,“2”未知 |
supportFacePhoto | String | 是否支持可见光人脸,“0”不支持,“1”支持,“2”未知 |
supportPalmPrint | String | 是否支持掌纹,“0”不支持,“1”支持,“2”未知 |
supportRemoteFinger | String | 是否支持远程登记指纹,“0”不支持,“1”支持,“2”未知 |
supportRemoteFacePhoto | String | 是否支持远程登记可见光人脸,“0”不支持,“1”支持,“2”未知 |
supportRemotePalmPrint | String | 是否支持远程登记掌纹,“0”不支持,“1”支持,“2”未知 |
supportRemoteFace | String | 是否支持远程登记近红外人脸,“0”不支持,“1”支持,“2”未知 |
1.4.4.5. 禁用设备
禁用设备,不允许设备通讯。当发现设备异常或者设备记录上传异常时调用。
Request:
POST /v1.0/device/disable
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.6. 启用设备
启用设备,允许设备通讯。
Request:
POST /v1.0/device/enable
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.7. 重启设备
重启设备,只有启用并且在线的设备才能重启。
Request:
POST /v1.0/device/reboot
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.8. 重新上传人员信息
上传设备的人员信息到系统,设备启用状态才允许操作。该接口当且仅当设备上登记的人员核验信息因某种异常原因导致没有上传到服务器时,才执行此操作。
Request:
POST /v1.0/device/reloadEmployeeInfo
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"onlineCheck": "1"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
onlineCheck | String | N | 设备在线状态校验。“0”代表不校验设备状态,执行该操作,“1”代表设备在线才执行此操作(默认) |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.9. 重新上传考勤记录
上传设备的考勤记录到系统,设备启用状态才允许操作。该接口当且仅当设备上登记的人员核验信息因某种异常原因导致没有上传到服务器时,才执行此操作。
Request:
POST /v1.0/device/reloadPunchRecord
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"startTime": 1492617600,
"endTime": 1492790400,
"onlineCheck": "1"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备编码 |
startTime | Long | Y | 打卡开始Unix时间戳,精确到秒 |
endTime | Long | Y | 打卡截止Unix时间戳,精确到秒 |
onlineCheck | String | N | 设备在线校验。“0”代表不校验设备状态,执行该操作,“1”代表设备在线才执行此操作(默认) |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.10. 重新上传设备记录
上传设备的考勤记录或者门禁事件记录到系统,设备启用状态才允许操作。该接口当且仅当设备上记录信息因某种异常原因导致没有上传到服务器时,才执行此操作。
Request:
POST /v1.0/device/reloadRecord
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"startTime": 1492617600,
"endTime": 1492790400,
"onlineCheck": "1"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备编码 |
startTime | Long | Y | 记录生成开始Unix时间戳,精确到秒 |
endTime | Long | Y | 记录生成截止Unix时间戳,精确到秒 |
onlineCheck | String | N | 设备在线校验。“0”代表不校验设备状态,执行该操作,“1”代表设备在线才执行此操作(默认) |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.11. 同步所有人员到设备
将系统的人员信息同步到设备,设备启用状态才允许操作。该接口当且仅当服务器上的人员因某种异常原因导致没有成功下发到设备时,才执行此操作。
Request:
POST /v1.0/hr/employee/device/refreshEmployeeInfo
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"onlineCheck": "1"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
onlineCheck | String | N | 设备在线状态校验。0代表不校验设备状态,执行该操作,“1"代表设备在线才执行此操作(默认) |
Response:
{
"code": "00000000",
"mid": "xxxxxxx",
"message": "success"
}
1.4.4.12. 登记生物特征
远程控制设备登记生物特征,设备在接收到该指令后响应打开对应的登记生物特征窗口,人员可直接根据相关提示进行登记。
使用须知:
- 此接口为部分设备才支持,支持的设备会返回执行成功的结果;
- 针对一台设备,不可同时多个用户终端调用此接口,否则后面调用的会直接踢掉前面的会话;
Request:
POST /v1.0/device/registerBiometric
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "5900195100050",
"employeeNo": "2956",
"type": "0",
"no": "",
"isCover": "0"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
employeeNo | String | Y | 人员编号 |
type | String | Y | 生物特征类型,详见生物特征类别说明,如type=1时,表示远程控制登记指纹 |
no | String | N | 生物具体个体编号 【指纹】编号是: 0-9。对应的手指是:左手:小拇指/无名指/中指/食指/拇指,右手:拇指/食指/中指/无名指/小拇指; 【指静脉】和指纹相同; 【面部】no=0; 【虹膜】no 按照 0 为左眼 1为右眼; 【掌静脉】no=0; 如果no 没有明确定义,则默认值为 0。 |
isCover | String | N | 是否覆盖设备该生物特征信息,“0”代表不覆盖(默认),“1”代表覆盖 |
注意事项:
- 选择不覆盖设备该生物特征信息:若该生物特征已存在于设备,则设备端提示生物特征已存在。
- 选择覆盖设备该生物特征信息:dbs会提前删除该设备上对应的该生物特征信息。若后续登记异常,该设备将没有该生物特征信息,请再次完成远程登记。
Response:
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"results": {
"sessionId": "xxxxxxxxxxxxxx"
}
}
}
参数名 | 类型 | 描述 |
---|---|---|
sessionId | String | 会话唯一标识,每次登记生物特征sessionId都不一致 |
1.4.4.13. 取消登记生物特征
与登记生物特征匹配,在登记生物特征过程中调用此接口,设备接收到该指令后会立即终止登记动作。
Request:
POST /v1.0/device/cancelRegisterBiometric
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "5900195100050"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success"
}
1.4.4.14. 分页查询设备命令
分页查询设备命令接口请求,当运维人员需要排查设备问题时调用
接口限制及注意事项【重要】:
- 只能查询3个月之内的数据;
- 查询时间段不能超过31天;
- 查询时间段不能跨月查询;
Request:
POST /v1.0/device/commandListByPage
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"curPage": 1,
"pageSize": 10,
"params": {
"sn": "xxx",
"startTime": 1596252816,
"endTime": 1596259816,
"status": "0"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
curPage | int | N | 分页查询条件,分页页码,默认第1页 |
pageSize | int | N | 分页查询条件,分页大小,默认每页10条,不超过20条 |
sn | String | N | 设备序列号 |
startTime | Long | Y | 开始Unix时间戳,该时间为命令创建时间,精确到秒 |
endTime | Long | N | 截止Unix时间戳,该时间为命令创建时间,精确到秒,为空时默认当前时间 |
status | String | N | 命令状态,“0” 命令失败,“1”命令成功 |
Response:
{
"code": "00000000",
"mid": "xxx",
"message": "success",
"payload": {
"totalRecords": 4,
"curPage": 1,
"totalPages": 1,
"pageSize": 10,
"result": [{
"sn": "6073202900005",
"protocol": "best-w",
"commitTime": 1598428491000,
"content": "{\"funcId\":\"cmd.data.update.bioPhoto\",\"mid\":\"d3025b68509d4faf83bdbc33863ee863\",\"payload\":{\"params\":{\"bioPhotos\":[{\"pin\":\"22\",\"format\":\"1\",\"type\":\"9\",\"url\":\"https://zk-ddopen-bucket-prod-1257511866.cos.ap-guangzhou.myqcloud.com/bioPhotos/60ee14a4747a4e57ab65bc673798f878/22_9.jpg\"}],\"cmdId\":\"282\"}}}",
"returnTime": 1598428492000,
"returnValue": "-1008",
"status": 2
}]
}
}
参数名 | 类型 | 描述 |
---|---|---|
sn | String | 设备序列号 |
protocol | String | 设备协议;push、best |
commitTime | String | 命令创建时间 |
content | String | 命令详情 |
returnTime | String | 设备回复时间 |
returnValue | String | 设备回复值,一般为 “0” 为成功,非“0”为失败 |
status | String | 命令状态;0: 未取走(默认) 1: 已取走未回复 2: 已回复 3: 已清除 |
1.4.4.15. 同步服务器时间到设备
将服务器时间同步到设备,设备启用状态才允许操作。设备已有自动更新时间的机制,该接口当且仅当设备上时间显示异常,才执行此操作。
Request:
POST /v1.0/device/syncTime
Content-Type: application/json
Authorization: ACCESS_TOKEN
Timestamp: 1529223702
{
"lang": "zh-cn",
"usr": "username",
"pwd": "password",
"payload": {
"params": {
"sn": "33998400021314",
"onlineCheck": "1"
}
}
}
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
sn | String | Y | 设备序列号 |
onlineCheck | String | N | 设备在线状态校验。0代表不校验设备状态,执行该操作,“1”代表设备在线才执行此操作(默认) |
Response:
{
"code": "00000000",
"mid": "xxxxxxx",
"message": "success"
}