1.2.18 • Published 2 years ago

ymd-mp-sdk v1.2.18

Weekly downloads
-
License
ISC
Repository
-
Last release
2 years ago

云门道小程序公开版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)
})

接口说明

  1. 应用接入和授权
  2. 接口列表
    1. 初始化载入 sdk.load
    2. 登录授权 sdk.login
    3. 判断登录状态 sdk.checkLogin
    4. 登出 sdk.logout
    5. 获取用户详情 sdk.getUserInfo
    6. 获取锁列表 sdk.getLockList
    7. 实名认证 sdk.realNameVerify
    8. E锁APP授权 sdk.authApp
    9. 获取E锁APP授权列表 sdk.getAuthAppList
    10. 删除E锁APP授权 sdk.deleteAuthApp
    11. 蓝牙查找门锁 sdk.findLock
    12. 蓝牙开门 sdk.openLock
    13. 获取所有省份 sdk.getProvince
    14. 根据省份获取城市 sdk.getCity
    15. 根据城市获取行政区 sdk.getDistrict
    16. 根据行政区获取街道 sdk.getStreet
    17. 根据街道获取社区 sdk.getCommunity
    18. 绑定锁 sdk.bindLock
    19. 解除门锁绑定 sdk.unbindLock
    20. 权限转让 sdk.authAssignment
    21. 归还权限 sdk.giveBackAuthority
    22. 获取卡片授权列表 sdk.getAuthCardList
    23. 删除卡片授权 sdk.deleteAuthCard
    24. 锁前卡片/身份证授权 sdk.authCard
    25. 锁前密码授权 sdk.authPwd
    26. 密码授权 sdk.authPwdData
    27. 锁前数据同步 sdk.syncLock
    28. 收回权限 sdk.takeBackAuth
  3. 附录
    1. 通用正确数据格式
    2. 通用错误数据格式
    3. 错误格式
    4. 示例代码

1. 应用接入和授权

1.1 申请帐号

开发者登录开放平台，根据指引填写信息和提交相应的资料，申请成功后系统会自动返回APPID（APPKEY）和APPSECRET，APPID作为应用的唯一标识，APPSECRET 作为应用的私有授权凭证，请妥善保管切勿泄露。（注：平台如果尚未开放，可以联系线下项目对接人员获取）。

1.2 下载SDK包

SDK包可以在开发平台中下载，如果平台功能未开放可联系项目线下对接人员获取。

1.3 接口授权验签

  1. 小程序后台添加合法域名

    主接口：https://api.hzbit.com:4443 备用1：https://access1.365ymd.com:16666 备用2：https://access2.365ymd.com:16666 备用3：https://access3.365ymd.com:16666

  2. 初始化加载，仅初始化一次。

    import sdk from 'sdk'
sdk.load({
  appKey: '提供的appKey',
  appSecret: '提供的appSecret'
})
  3. 生成签名，签名由开发者依据开放平台的签名生成规则生成。签名将作为合作伙伴用户的合法鉴权凭证。
    // 伪代码
authTime = '1553595995' //参与签名的时间戳
appSecret = '申请的app密钥'
mobile = ''
//  生成签名
authSign = MD5(appSecret + authTime).toUpperCase() + '-' + MD5(mobile).toUpperCase()
  4. 授权用户登录
    import sdk from 'sdk'
await sdk.login({
// 具体参数详见对应接口文档
})

2.1 初始化载入 sdk.load

  1. 描述：sdk初始化。

  2. 输入参数：

    参数名类型必须描述
    appKeystring是申请的appId/appkey
    appSecretstring是申请的appSecret

  3. success输出格式：

    {
   "state": true,
   "type": "load"
}
  4. 代码示例:
    import sdk from './sdk'
// 初始化一次即可
sdk.load({
  appKey: '',
  appSecret: '',
})

2.2 登录授权 sdk.login

  1. 描述：用户登录授权。后续所有接口均需要进行用户鉴权，未登录或者登录失效会被拦截，并提示错误码401。

  2. 输入参数：

    参数名类型必须描述
    mobilestring是手机号
    authTimestring是签名使用的时间戳
    authSignstring是签名算法生成的签名

  3. success输出格式：

    {
   "state": true,
   "type": "login"
}
  4. 代码示例:
    await sdk.login({
  mobile: '',
  authTime: '',
  authSign: ''
})

2.3 判断登录状态 sdk.checkLogin

  1. 描述：判断当前用户登录状态是否已过期。

  2. 输入参数：无

    参数名类型必须描述

  3. success输出格式：

    {
    "state": true,
    "type": "checkLogin"
}
  4. 代码示例:
    if (sdk.checkLogin()) {
   
}

2.4 登出 sdk.logout

  1. 描述：注销用户登录信息。注销后才能重新登录。

  2. 输入参数：无

    参数名类型必须描述

  3. success输出格式：

    {
    "state": true,
    "type": "logout"
}
  4. 代码示例:
    sdk.logout()

2.5 获取用户详情 sdk.getUserInfo

  1. 描述：获取当前登录用户的详情。

  2. 输入参数：无

    参数名类型必须描述

  3. success输出格式：

    {
    "state": true,
    "type": "getUserInfo",
    "res": {
        "isReal": "string, 是否实名，1:实名，0:未实名"
        "tel": "string, 手机号"
    }
}
  4. 代码示例:
    await sdk.getUserInfo()

2.6 获取锁列表 sdk.getLockList

  1. 描述：根据登录用户信息获取有权限的锁列表。

  2. 输入参数：无

    参数名类型必须描述

  3. 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, 授权时间区间"
        }    
    ]
}
  4. 代码示例:
    await sdk.getLockList()

2.7 实名认证 sdk.realNameVerify

  1. 描述：根据身份证、姓名、人脸信息进行实名认证

  2. 输入参数：

    参数名类型必须描述
    namestring是姓名
    idCardNostring是身份证号码
    userImgBasestring是人脸图片的base64格式，去掉base64头data:image/jpeg;base64,

  3. success输出格式：

    {
    "state": true,
    "type": "realNameVerify"
}
  4. 代码示例:
    await sdk.realNameVerify()

2.8 E锁app授权 sdk.authApp

  1. 描述：将当前登录用户的锁通过APP授权给另一个人。授权成功后，即可使用SDK/E锁管家/E锁APP等应用进行开门。

  2. 输入参数：

    参数名类型必须描述
    targetMobilestring是被授权人手机号
    startDatestring是授权开始时间，例如2022-05-01 17:28
    endDatestring是授权结束时间，例如2024-05-01 17:28
    lockIdstring是锁id

  3. success输出格式：

    {
    "state": true,
    "type": "authApp"
}
  4. 代码示例:
    await sdk.authApp()

2.9 获取E锁APP授权列表 sdk.getAuthAppList

  1. 描述：获取锁的APP授权列表。

  2. 输入参数：

    参数名类型必须描述
    lockIdstring是可以由getLockList获取

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "startDate": "string, 授权开始时间",
            "endDate": "string, 授权结束时间",
            "mac": "string, 锁mac地址",
            "operaterId": "string, 授权人",
            "targetUserId": "string, 被授权人"
        }    
    ]
}
  4. 代码示例:
    await sdk.getAuthAppList()

2.10 删除E锁APP授权 sdk.deleteAuthApp

  1. 描述：删除指定锁的APP授权记录。

  2. 输入参数：

    参数名类型必须描述
    targetMobilestring是被授权人手机号
    lockIdstring是锁id

  3. success输出格式：

    {
    "state": true,
    "type": "deleteAuthApp"
}
  4. 代码示例:
    await sdk.getLockList()

2.11 蓝牙查找门锁 sdk.findLock

  1. 描述：蓝牙查找附近的设备。注意手机需要蓝牙和定位权限。

  2. 输入参数：

    参数名类型必须描述
    macsarray是需要查找的锁mac，可以指定*查找所有锁
    findingTimeoutnumber否单次查找设备超时时间，单位ms

  3. 代码示例:

    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

  1. 描述：蓝牙在线开门。手机需要打开蓝牙和定位；需要有网络连接；当前登录人需要有当前锁的权限授权； 如果监管安全的锁登录人还需要先实名认证。

  2. 输入参数：

    参数名类型必须描述
    macsstring是当前mac地址
    idstring是锁id

  3. 代码示例:

    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

  1. 描述：获取所有省份

  2. 输入参数：无

    参数名类型必须描述

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "code": "string，地区编码",
            "value": "string, 地区名"
        }    
    ]
}
  4. 代码示例:
    await sdk.getProvince()

2.14 根据省份获取城市 sdk.getCity

  1. 描述：根据省份获取城市

  2. 输入参数：无

    参数名类型必须描述
    codestring是省code

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "code": "string，地区编码",
            "value": "string, 地区名"
        }    
    ]
}
  4. 代码示例:
    await sdk.getCity({
  code: '33'
})

2.15 根据城市获取行政区 sdk.getDistrict

  1. 描述：根据城市获取行政区

  2. 输入参数：

    参数名类型必须描述
    codestring是城市code

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "code": "string，地区编码",
            "value": "string, 地区名"
        }    
    ]
}
  4. 代码示例:
    await sdk.getDistrict({
  code: '3301'
})

2.16 根据行政区获取街道 sdk.getStreet

  1. 描述：根据行政区获取街道

  2. 输入参数：

    参数名类型必须描述
    codestring是行政区code

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "code": "string，地区编码",
            "value": "string, 地区名"
        }    
    ]
}
  4. 代码示例:
    await sdk.getStreet({
  code: '330102'
})

2.17 根据街道获取社区 sdk.getCommunity

  1. 描述：根据街道获取社区

  2. 输入参数：

    参数名类型必须描述
    codestring是街道code

  3. success输出格式：

    {
    "state": true,
    "res": [
        {
            "code": "string，地区编码",
            "value": "string, 地区名"
        }    
    ]
}
  4. 代码示例:
    await sdk.getCommunity({
  code: '330102001'
})

2.18 绑定锁 sdk.bindLock

  1. 描述：绑定指定门锁到登录账户下。

  2. 输入参数：

    参数名类型必须描述
    addrListobject是地址详情
    addrList.provinceobject是省份数据{label:'省份名',code:'省份编码'}，从接口获取
    addrList.cityobject是城市数据{label:'城市名',code:'城市编码'}
    addrList.districtobject是区划数据{label:'区名',code:'区编码'}
    addrList.streetobject否街道，格式同上
    addrList.communityobject否社区，格式同上
    addrList.roadobject否街/路/巷/里，{label:'名称'}
    addrList.noobject否门牌号，格式同上
    addrList.estateobject是小区（农居点/建筑物），格式同上
    addrList.buildingobject否幢，格式同上
    addrList.unitobject否单元，格式同上
    addrList.houseNoobject否室（房屋名号），格式同上
    addrList.roomNoobject否室内编号（房间号），格式同上
    macstring是mac地址
    lockNamestring是锁名称

  3. success输出格式：

    {
    "state": true
}
  4. 代码示例:
    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

  1. 描述：当前账户下，解除门锁绑定。

  2. 输入参数：

    参数名类型必须描述
    lockIdstring是锁id

  3. success输出格式：

    {
    "state": true
}
  4. 代码示例:
    await sdk.unbindLock()

2.20 权限转让 sdk.authAssignment

  1. 描述：将当前登录账户下的指定门锁权限转让给指定用户。

  2. 输入参数：

    参数名类型必须描述
    targetMobilestring是被转让人手机号
    startDatestring是开始时间，格式2022-04-31 16:00
    endDatestring是结束时间，格式2023-04-31 16:00
    lockOwnerTypestring是1（管理权+所有权）；2 所有权；3 管理权
    lockIdstring是锁id

  3. success输出格式：

    {
    "state": true
}
  4. 代码示例:
    await sdk.authAssignment()

2.21 归还权限 sdk.giveBackAuthority

  1. 描述：归还之前被转让的权限。

  2. 输入参数：

    参数名类型必须描述
    lockIdstring是锁id
    removeAllSubAuthoritystring是1 归还所有权限，包含关联权限；0 只归还当前权限，关联权限不归还

  3. success输出格式：

    {
    "state": true
}
  4. 代码示例:
    await sdk.giveBackAuthority()

2.22 获取卡片授权列表 sdk.getAuthCardList

  1. 描述：获取所有的卡片授权列表。

    1. 输入参数：

      参数名类型必须描述
      lockIdstring是锁id
      cardTypestring是1. 身份证 2. A卡(钥匙卡)

    2. success输出格式：

      {
    "state": true,
    "res":[
        {
            "dnCode": "string，卡片dncode",
            "uid": "string，卡片nfcid",
            "mac": "string，设备mac地址",
            "operaterId": "string，授权人手机号",
            "operaterName": "string，授权人姓名",
            "startDate": "string，授权开始时间",
            "endDate": "string，授权结束时间"
        }
    ]
}

  2. 代码示例:

    await sdk.getAuthCardList()

2.23 删除卡片授权 sdk.deleteAuthCard

  1. 描述：删除指定卡片授权记录。

    1. 输入参数：

      参数名类型必须描述
      lockIdstring是锁id
      uidstring是卡片nfcid
      dnCodestring是卡片dncode

    2. success输出格式：

      {
    "state": true
}

  2. 代码示例:

    await sdk.deleteAuthCard()

2.24 锁前卡片/身份证授权 sdk.authCard

  1. 描述：卡片授权，操作人在授权前需要打开蓝牙并且应位于指定锁前。授权过程中数据将通过蓝牙同步给门锁，同步完成后才能使用卡片开门。

    1. 输入参数：

      参数名类型必须描述
      macsstring是锁mac
      lockIdstring是锁id
      startDatestring是卡片授权开始时间，例如2022-01-01 16:00
      endDatestring是卡片授权结束时间，例如2024-01-01 16:00
      cardTypestring否默认2，1.B卡/身份证 2.A卡/钥匙卡

    2. 代码示例:

      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

  1. 描述：密码授权，操作人在授权前需要打开蓝牙并且应位于指定锁前。授权过程中数据将通过蓝牙同步给门锁，同步完成后才能使用密码开门。

    1. 输入参数：

      参数名类型必须描述
      macsstring是锁mac
      lockIdstring是锁id
      startDatestring是密码授权开始时间，例如2022-01-01 16:00
      endDatestring是密码授权结束时间，例如2024-01-01 16:00
      targetMobilestring是被授权用户手机号
      targetUserNamestring是被授权用户姓名
      lockPwdstring是锁密码，6位数字密码

    2. 代码示例:

      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

  1. 描述：6位期限密码授权。密码授权成功后，需要至少通过SDK/E锁APP，做一次数据同步（比如开门），密码才能生效。

    1. 输入参数：

      参数名类型必须描述
      lockIdstring是锁id
      startDatestring是密码授权开始时间，例如2022-01-01 16:00
      endDatestring是密码授权结束时间，例如2024-01-01 16:00
      targetMobilestring是被授权用户手机号
      targetUserNamestring是被授权用户姓名
      lockPwdstring是锁密码，6位数字密码

    2. success输出格式：

      {
    "state": true
}
    3. 代码示例:
      await sdk.authPwdData()

2.27 锁前数据同步 sdk.syncLock

  1. 描述：仅同步服务器最新授权数据到门锁，过程中不触发开门。

    1. 输入参数：

      参数名类型必须描述
      macsstring是当前mac地址
      idstring是锁id

    2. success输出格式：

      {
    "state": true
}
    3. 代码示例:
      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

  1. 描述：强制收回管理权。

    1. 输入参数：

      参数名类型必须描述
      targetMobilestring是管理员手机号
      lockIdstring是锁id

    2. success输出格式：

      {
    "state": true
}
    3. 代码示例:
      await sdk.takeBackAuth()

3.1 通用正确数据格式

参数名类型描述
statebooleantrue，正确状态
typestring数据来源
resarray,object详情数据

3.2 通用错误数据格式

参数名类型描述
statebooleanfalse，错误状态
typestring数据来源
resobject详情数据
codestring错误编码
msgstring错误提示

3.3 部分错误编码

其余编码详见接口返回。

编码描述
401未登录或者登录已失效
403login签名错误
500系统错误
1199999未知错误
1101000蓝牙未开启或者初始化异常
1101001蓝牙不可用或者意外关闭
1101002未找到指定设备
1101003蓝牙连接失败
1101004蓝牙获取所有服务失败
1101005蓝牙订阅特征值失败
1101006蓝牙或者定位未打开
1101602身份证信息读取失败
1101603卡片授权数据特征相同，忽略同步
1101604密码授权数据特征相同，忽略同步
1101605网络离线，忽略卡片数据同步
1101606网络离线，忽略密码数据同步
1101607刷卡模块已禁用，忽略卡片数据同步
1101608键盘模块已禁用，忽略密码数据同步
3300002AppKey错误
4400001用户ID错误
4400002程序包上传失败
4400003短信已失效,请重新获取
4400004该锁不存在
4400005校验位错误
4400006该锁已被其他用户绑定
4400007系统暂无用户身份信息
4400008权限不足
4400009偏移向量不能为空
4400010数据格式有误
4400012您的e锁设备已欠费,无法进行此操作
4400013分享用户未注册
4400014普通用户(非管理者权限)只能授权本人身份证
4400015授权身份证人证不符
4400016该用户不存在APP分享
4400017当前用户未实名验证
4400018系统异常
4400020强安全认证的锁，被授权对象必须先进行实名认证
4400021不能给自己授权
4400022owenerType参数设置错误，只能为：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())
  //  其他操作
}
@everything-registry/sub-chunk-3207
1.2.18

2 years ago

1.2.10

2 years ago

1.2.6

2 years ago

1.2.5

2 years ago