ymd-mp-sdk
v1.2.18
Published
``` npm i ymd-mp-sdk ```
Readme
云门道小程序公开版SDK
安装方式
npm i ymd-mp-sdk使用示例
import sdk from 'ymd-mp-sdk';
sdk.load({
appKey: 'xxxx',
appSecret: 'xxx...',
})
sdk.getLockList().then((lockList)=>{
console.log('locklist:', lockList)
})接口说明
- 应用接入和授权
- 接口列表
- 初始化载入 sdk.load
- 登录授权 sdk.login
- 判断登录状态 sdk.checkLogin
- 登出 sdk.logout
- 获取用户详情 sdk.getUserInfo
- 获取锁列表 sdk.getLockList
- 实名认证 sdk.realNameVerify
- E锁APP授权 sdk.authApp
- 获取E锁APP授权列表 sdk.getAuthAppList
- 删除E锁APP授权 sdk.deleteAuthApp
- 蓝牙查找门锁 sdk.findLock
- 蓝牙开门 sdk.openLock
- 获取所有省份 sdk.getProvince
- 根据省份获取城市 sdk.getCity
- 根据城市获取行政区 sdk.getDistrict
- 根据行政区获取街道 sdk.getStreet
- 根据街道获取社区 sdk.getCommunity
- 绑定锁 sdk.bindLock
- 解除门锁绑定 sdk.unbindLock
- 权限转让 sdk.authAssignment
- 归还权限 sdk.giveBackAuthority
- 获取卡片授权列表 sdk.getAuthCardList
- 删除卡片授权 sdk.deleteAuthCard
- 锁前卡片/身份证授权 sdk.authCard
- 锁前密码授权 sdk.authPwd
- 密码授权 sdk.authPwdData
- 锁前数据同步 sdk.syncLock
- 收回权限 sdk.takeBackAuth
- 附录
1. 应用接入和授权
1.1 申请帐号
开发者登录开放平台,根据指引填写信息和提交相应的资料,申请成功后系统会自动返回APPID(APPKEY)和APPSECRET,APPID作为应用的唯一标识,APPSECRET 作为应用的私有授权凭证,请妥善保管切勿泄露。(注:平台如果尚未开放,可以联系线下项目对接人员获取)。
1.2 下载SDK包
SDK包可以在开发平台中下载,如果平台功能未开放可联系项目线下对接人员获取。
1.3 接口授权验签
小程序后台添加合法域名
主接口:https://api.hzbit.com:4443 备用1:https://access1.365ymd.com:16666 备用2:https://access2.365ymd.com:16666 备用3:https://access3.365ymd.com:16666
初始化加载,仅初始化一次。
import sdk from 'sdk' sdk.load({ appKey: '提供的appKey', appSecret: '提供的appSecret' })生成签名,签名由开发者依据开放平台的签名生成规则生成。签名将作为合作伙伴用户的合法鉴权凭证。
// 伪代码 authTime = '1553595995' //参与签名的时间戳 appSecret = '申请的app密钥' mobile = '' // 生成签名 authSign = MD5(appSecret + authTime).toUpperCase() + '-' + MD5(mobile).toUpperCase()授权用户登录
import sdk from 'sdk' await sdk.login({ // 具体参数详见对应接口文档 })
2.1 初始化载入 sdk.load
描述:sdk初始化。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- appKey|string|是|申请的appId/appkey appSecret|string|是|申请的appSecret
success输出格式:{ "state": true, "type": "load" }代码示例:
import sdk from './sdk' // 初始化一次即可 sdk.load({ appKey: '', appSecret: '', })
2.2 登录授权 sdk.login
描述:用户登录授权。
后续所有接口均需要进行用户鉴权,未登录或者登录失效会被拦截,并提示错误码401。输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- mobile|string|是|手机号 authTime|string|是|签名使用的时间戳 authSign|string|是|签名算法生成的签名
success输出格式:{ "state": true, "type": "login" }代码示例:
await sdk.login({
mobile: '',
authTime: '',
authSign: ''
})2.3 判断登录状态 sdk.checkLogin
描述:判断当前用户登录状态是否已过期。
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|---
success输出格式:{ "state": true, "type": "checkLogin" }代码示例:
if (sdk.checkLogin()) { }
2.4 登出 sdk.logout
描述:注销用户登录信息。注销后才能重新登录。
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|---
success输出格式:{ "state": true, "type": "logout" }代码示例:
sdk.logout()
2.5 获取用户详情 sdk.getUserInfo
描述:获取当前登录用户的详情。
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|---
success输出格式:{ "state": true, "type": "getUserInfo", "res": { "isReal": "string, 是否实名,1:实名,0:未实名" "tel": "string, 手机号" } }代码示例:
await sdk.getUserInfo()
2.6 获取锁列表 sdk.getLockList
描述:根据登录用户信息获取有权限的锁列表。
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|---
success输出格式:{ "state": true, "res": [ { "battery": "string,电量百分比", "createTime": "string, 创建日期", "hdVer": "string, 硬件版本", "lockId": "string, 锁id", "lockName": "string, 锁名称", "lockType": "string, 锁类型", "mac": "string, 锁mac地址", "mcu": "string, 锁mcu版本", "officeMode": "string, 办公室模式", "ownerType": "string, 用户类型,1. 所有权+管理权 2.仅所有权 3.仅管理权 4.仅使用权 5.所有权+使用权", "softVersion": "string, 软件版本", "validPeriodStr": "string, 授权时间区间" } ] }代码示例:
await sdk.getLockList()
2.7 实名认证 sdk.realNameVerify
描述:根据身份证、姓名、人脸信息进行实名认证
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- name|string|是|姓名 idCardNo|string|是|身份证号码 userImgBase|string|是|人脸图片的base64格式,去掉base64头
data:image/jpeg;base64,success输出格式:{ "state": true, "type": "realNameVerify" }代码示例:
await sdk.realNameVerify()
2.8 E锁app授权 sdk.authApp
描述:将当前登录用户的锁通过APP授权给另一个人。授权成功后,即可使用SDK/E锁管家/E锁APP等应用进行开门。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- targetMobile|string|是|被授权人手机号 startDate|string|是|授权开始时间,例如2022-05-01 17:28 endDate|string|是|授权结束时间,例如2024-05-01 17:28 lockId|string|是|锁id
success输出格式:{ "state": true, "type": "authApp" }代码示例:
await sdk.authApp()
2.9 获取E锁APP授权列表 sdk.getAuthAppList
描述:获取锁的APP授权列表。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string|是|可以由getLockList获取
success输出格式:{ "state": true, "res": [ { "startDate": "string, 授权开始时间", "endDate": "string, 授权结束时间", "mac": "string, 锁mac地址", "operaterId": "string, 授权人", "targetUserId": "string, 被授权人" } ] }代码示例:
await sdk.getAuthAppList()
2.10 删除E锁APP授权 sdk.deleteAuthApp
描述:删除指定锁的APP授权记录。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- targetMobile|string|是|被授权人手机号 lockId|string|是|锁id
success输出格式:{ "state": true, "type": "deleteAuthApp" }代码示例:
await sdk.getLockList()
2.11 蓝牙查找门锁 sdk.findLock
描述:蓝牙查找附近的设备。注意手机需要蓝牙和定位权限。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- macs|array|是|需要查找的锁mac,可以指定*查找所有锁 findingTimeout|number|否|单次查找设备超时时间,单位ms
代码示例:
sdk.findLock({ macs: ['*'], callbacks: { finding (res, {findMac}) { console.log('广播数据包', res) // factory: "厂商编号"; // isYmd:"true表示该设备适用该SDK; // mac:"设备mac" console.log(findMac()) }, error (res) { // 错误信息 console.log(res) } } })
2.12 蓝牙开门 sdk.openLock
描述:蓝牙在线开门。手机需要打开蓝牙和定位;需要有网络连接;当前登录人需要有当前锁的权限授权; 如果监管安全的锁登录人还需要先实名认证。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- macs|string|是|当前mac地址 id|string|是|锁id
代码示例:
sdk.openLock({ // 填写具体的锁mac,可以从getLockList中获取 macs: 'AAAA', // 填写具体的锁id id: '', callbacks: { //已找到目标设备 found (res) { console.log('广播数据包', res) // deviceMac: "找到的设备mac" }, //已打开目标设备 open (res) { console.log(res.state) }, //结束或者蓝牙关闭,可能会执行多次 close (res) { }, //发生错误 error (res) { console.log('error', res) }, } })
2.13 获取所有省份 sdk.getProvince
描述:获取所有省份
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|---
success输出格式:{ "state": true, "res": [ { "code": "string,地区编码", "value": "string, 地区名" } ] }代码示例:
await sdk.getProvince()
2.14 根据省份获取城市 sdk.getCity
描述:根据省份获取城市
输入参数:无
参数名 | 类型 | 必须 | 描述 ---|---|---|--- code|string|是|省code
success输出格式:{ "state": true, "res": [ { "code": "string,地区编码", "value": "string, 地区名" } ] }代码示例:
await sdk.getCity({ code: '33' })
2.15 根据城市获取行政区 sdk.getDistrict
描述:根据城市获取行政区
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- code|string|是|城市code
success输出格式:{ "state": true, "res": [ { "code": "string,地区编码", "value": "string, 地区名" } ] }代码示例:
await sdk.getDistrict({ code: '3301' })
2.16 根据行政区获取街道 sdk.getStreet
描述:根据行政区获取街道
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- code|string|是|行政区code
success输出格式:{ "state": true, "res": [ { "code": "string,地区编码", "value": "string, 地区名" } ] }代码示例:
await sdk.getStreet({ code: '330102' })
2.17 根据街道获取社区 sdk.getCommunity
描述:根据街道获取社区
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- code|string|是|街道code
success输出格式:{ "state": true, "res": [ { "code": "string,地区编码", "value": "string, 地区名" } ] }代码示例:
await sdk.getCommunity({ code: '330102001' })
2.18 绑定锁 sdk.bindLock
描述:绑定指定门锁到登录账户下。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- addrList|object|是|地址详情 addrList.province|object|是|省份数据
{label:'省份名',code:'省份编码'},从接口获取 addrList.city|object|是|城市数据{label:'城市名',code:'城市编码'}addrList.district|object|是|区划数据{label:'区名',code:'区编码'}addrList.street|object|否|街道,格式同上 addrList.community|object|否|社区,格式同上 addrList.road|object|否|街/路/巷/里,{label:'名称'}addrList.no|object|否|门牌号,格式同上 addrList.estate|object|是|小区(农居点/建筑物),格式同上 addrList.building|object|否|幢,格式同上 addrList.unit|object|否|单元,格式同上 addrList.houseNo|object|否|室(房屋名号),格式同上 addrList.roomNo|object|否|室内编号(房间号),格式同上 mac|string|是|mac地址 lockName|string|是|锁名称success输出格式:{ "state": true }代码示例:
await sdk.bindLock({ addrList: { province: { label: '浙江省', code: '33' }, city: { label: '杭州市', code: '3301' }, district: { label: '上城区', code: '330102' }, street: { label: '清波街道', code: '330102001' }, community: { label: '清波门社区', code: '330102001051' }, road: { label: '某某路' }, no: { label: '某某门牌号' }, estate: { label: '某某小区' }, building: { label: '某幢' }, unit: { label: '某单元' }, houseNo: { label: '101' }, roomNo: { label: '1' }, }, mac: '', lockName: '' })
2.19 解除门锁绑定 sdk.unbindLock
描述:当前账户下,解除门锁绑定。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string|是|锁id
success输出格式:{ "state": true }代码示例:
await sdk.unbindLock()
2.20 权限转让 sdk.authAssignment
描述:将当前登录账户下的指定门锁权限转让给指定用户。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- targetMobile|string|是|被转让人手机号 startDate|string|是|开始时间,格式2022-04-31 16:00 endDate|string|是|结束时间,格式2023-04-31 16:00 lockOwnerType|string|是|1(管理权+所有权);2 所有权;3 管理权 lockId|string|是|锁id
success输出格式:{ "state": true }代码示例:
await sdk.authAssignment()
2.21 归还权限 sdk.giveBackAuthority
描述:归还之前被转让的权限。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string|是|锁id removeAllSubAuthority|string|是|1 归还所有权限,包含关联权限;0 只归还当前权限,关联权限不归还
success输出格式:{ "state": true }代码示例:
await sdk.giveBackAuthority()
2.22 获取卡片授权列表 sdk.getAuthCardList
- 描述:获取所有的卡片授权列表。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string|是|锁id cardType|string|是|1. 身份证 2. A卡(钥匙卡)
success输出格式:{ "state": true, "res":[ { "dnCode": "string,卡片dncode", "uid": "string,卡片nfcid", "mac": "string,设备mac地址", "operaterId": "string,授权人手机号", "operaterName": "string,授权人姓名", "startDate": "string,授权开始时间", "endDate": "string,授权结束时间" } ] }
- 代码示例:
await sdk.getAuthCardList()
2.23 删除卡片授权 sdk.deleteAuthCard
- 描述:删除指定卡片授权记录。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string|是|锁id uid|string|是|卡片nfcid dnCode|string|是|卡片dncode
success输出格式:{ "state": true }
- 代码示例:
await sdk.deleteAuthCard()
2.24 锁前卡片/身份证授权 sdk.authCard
- 描述:卡片授权,操作人在授权前需要打开蓝牙并且应位于指定锁前。
授权过程中数据将通过蓝牙同步给门锁,同步完成后才能使用卡片开门。输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- macs|string|是|锁mac lockId|string|是|锁id startDate|string|是|卡片授权开始时间,例如2022-01-01 16:00 endDate|string|是|卡片授权结束时间,例如2024-01-01 16:00 cardType|string|否|默认2,1.B卡/身份证 2.A卡/钥匙卡
代码示例:
sdk.authCard({ macs: '', lockId: '', startDate: '2022-01-01 16:00', endDate: '2024-01-01 16:00', cardType: '2', callbacks: { found (res) { console.log('found', res) }, // 读取卡片信息 readCard (res) { //dn: "string,卡片dncode" //type: "string,A/B,A卡或B卡" //uid: "string,卡片uid" console.log('readCard', res) }, // 卡片授权结果 authCard (res) { console.log('authCard', res) }, // 卡片同步结果 syncCard (res) { console.log('syncCard', res) }, error (res) { console.log('error', res) }, close (res) { console.log('close', res) } } })
2.25 锁前密码授权 sdk.authPwd
- 描述:密码授权,操作人在授权前需要打开蓝牙并且应位于指定锁前。
授权过程中数据将通过蓝牙同步给门锁,同步完成后才能使用密码开门。输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- macs|string| 是 |锁mac lockId|string| 是 |锁id startDate|string| 是 |密码授权开始时间,例如2022-01-01 16:00 endDate|string| 是 |密码授权结束时间,例如2024-01-01 16:00 targetMobile|string| 是 |被授权用户手机号 targetUserName|string| 是 |被授权用户姓名 lockPwd|string| 是 |锁密码,6位数字密码
代码示例:
sdk.authPwd({ macs: '', lockId: '', startDate: '2022-01-01 16:00', endDate: '2024-01-01 16:00', lockPwd: 'string,6位数字密码', targetMobile: '', targetUserName: '', callbacks: { found (res) { console.log('found', res) }, // 密码授权结果 authPwd (res) { console.log('authPwd', res) }, // 密码同步结果 syncPwd (res) { console.log('syncPwd', res) }, error (res) { console.log('error', res) }, close (res) { console.log('close', res) } } })
2.26 期限密码授权 sdk.authPwdData
- 描述:6位期限密码授权。
密码授权成功后,需要至少通过SDK/E锁APP,做一次数据同步(比如开门),密码才能生效。输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- lockId|string| 是 |锁id startDate|string| 是 |密码授权开始时间,例如2022-01-01 16:00 endDate|string| 是 |密码授权结束时间,例如2024-01-01 16:00 targetMobile|string| 是 |被授权用户手机号 targetUserName|string| 是 |被授权用户姓名 lockPwd|string| 是 |锁密码,6位数字密码
success输出格式:{ "state": true }代码示例:
await sdk.authPwdData()
2.27 锁前数据同步 sdk.syncLock
- 描述:仅同步服务器最新授权数据到门锁,
过程中不触发开门。输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- macs|string|是|当前mac地址 id|string|是|锁id
success输出格式:{ "state": true }代码示例:
sdk.syncLock({ // 填写具体的锁mac,可以从getLockList中获取 macs: 'AAAA', // 填写具体的锁id id: '', callbacks: { //已找到目标设备 found (res) { console.log('广播数据包', res) // deviceMac: "找到的设备mac" }, //卡片同步结果 syncCard (res) { }, //密码同步结果 syncPwd (res) { }, //结束或者蓝牙关闭,可能会执行多次 close (res) { }, //发生错误 error (res) { console.log('error', res) }, } })
2.28 收回管理权 sdk.takeBackAuth
- 描述:强制收回管理权。
输入参数:
参数名 | 类型 | 必须 | 描述 ---|---|---|--- targetMobile|string|是|管理员手机号 lockId|string|是|锁id
success输出格式:{ "state": true }代码示例:
await sdk.takeBackAuth()
3.1 通用正确数据格式
参数名 | 类型 | 描述 ---|---|--- state|boolean|true,正确状态 type|string|数据来源 res|array,object|详情数据
3.2 通用错误数据格式
参数名 | 类型 | 描述 ---|---|--- state|boolean|false,错误状态 type|string|数据来源 res|object|详情数据 code|string|错误编码 msg|string|错误提示
3.3 部分错误编码
其余编码详见接口返回。
编码 | 描述
---|---
401|未登录或者登录已失效
403|login签名错误
500|系统错误
1199999|未知错误
1101000|蓝牙未开启或者初始化异常
1101001|蓝牙不可用或者意外关闭
1101002|未找到指定设备
1101003|蓝牙连接失败
1101004|蓝牙获取所有服务失败
1101005|蓝牙订阅特征值失败
1101006|蓝牙或者定位未打开
1101602|身份证信息读取失败
1101603|卡片授权数据特征相同,忽略同步
1101604|密码授权数据特征相同,忽略同步
1101605|网络离线,忽略卡片数据同步
1101606|网络离线,忽略密码数据同步
1101607|刷卡模块已禁用,忽略卡片数据同步
1101608|键盘模块已禁用,忽略密码数据同步
3300002|AppKey错误
4400001|用户ID错误
4400002|程序包上传失败
4400003|短信已失效,请重新获取
4400004|该锁不存在
4400005|校验位错误
4400006|该锁已被其他用户绑定
4400007|系统暂无用户身份信息
4400008|权限不足
4400009|偏移向量不能为空
4400010|数据格式有误
4400012|您的e锁设备已欠费,无法进行此操作
4400013|分享用户未注册
4400014|普通用户(非管理者权限)只能授权本人身份证
4400015|授权身份证人证不符
4400016|该用户不存在APP分享
4400017|当前用户未实名验证
4400018|系统异常
4400020|强安全认证的锁,被授权对象必须先进行实名认证
4400021|不能给自己授权
4400022|owenerType参数设置错误,只能为:1,2,3
4400023|被授权对象与门锁的管理者不是同一个人,请先收回管理者权限
4400024|系统错误,divisionCode生成长度超过最大值
4400001|用户ID错误
4400006|该锁已被其他用户绑定
4400013|分享用户未注册
4400017|当前用户未实名验证
99990017|系统错误,请联系管理员
3.4 示例代码
import sdk from 'sdk'
async function demo () {
// 初始化并加载配置
const appKey = ''
const appSecret = ''
sdk.load({
appKey,
appSecret
})
const mobile = ''
// 请按照文档说明生成签名
const sign = {
authTime: '',
authSign: ''
}
// 登录
console.log(await sdk.login({
mobile,
authTime: sign.authTime,
authSign: sign.authSign
}))
// 获取用户信息
console.log(await sdk.getUserInfo())
// 其他操作
}