Tuya.com
简体中文
English
注册
登录开发者平台
简体中文
English
注册
登录开发者平台
云服务 API 参考（归档）
search
根据文档目录筛选
arrDownIoT Core服务
arrDown行业通用 API
arrDown全屋智能 API
arrDown垂直品类硬件 API
arrDown智能门锁开放能力
arrDown万能红外开放能力
arrDown实时音视频
arrDown视频云存储
arrDown短语音合成服务
arrDown物联网卡
arrDown智能发卡器开放能力
arrDown网关开放能力
arrDown扫地机器人开放能力
arrDown行业三方设备能力
arrDown公区通用能力
arrDown门禁开放能力
门禁开放能力说明
arrDown门禁用户管理
arrDown门禁人脸管理
arrDown门禁二维码管理
arrDown门禁卡管理
arrDown门禁通行密码管理
arrDown门禁远程开门
arrDown呼叫住户
arrDown门禁用户批量操作
arrDown门禁设备管理
arrDown梯控开放能力
arrDown车行开放能力
arrDown摄像头开放能力
arrDown消防开放能力
arrDown周界开放能力
arrDown智能断路器开放能力
arrDown智能水表开放能力
arrDown室内外融合定位器开放能力
arrDown通用基础 API
arrDown行业服务 API
云服务 API 参考（归档）垂直品类硬件 API行业三方设备能力门禁开放能力门禁开放能力说明

门禁开放能力说明

更新时间：2023-06-15 05:23:11

本文介绍门禁开放能力接入的相关说明。

接入流程说明

门禁设备分为可视对讲门禁和普通门禁。

若开发者接入的门禁为可视对讲门禁，需注意以下流程：

  • 开发者需创建 App 并与云项目关联。

    1. 登录 涂鸦 IoT 开发平台。
    2. 单击左侧导航栏中的 App，在 App > App SDK > SDK 开发 页面，单击 创建 App，并添加 App 信息。
      其中渠道标识符字段即为应用唯一标识 schema。
    3. 单击左侧导航栏中的 云开发，在 云开发 > 设备 > 关联自有 App 页面，关联对应 App。

  • 下发给门禁的用户 ID 须为涂鸦用户 ID，且涂鸦用户 ID 须授权给设备。

    1. 调用 同步用户接口，获取涂鸦用户 ID。
      创建涂鸦用户的 schema 参数为上述 App 的应用唯一标识 schema。

    2. 调用 新增用户设备权限 接口，涂鸦用户 ID 授权给对应设备。

    3. 调用 新增人员 接口，把涂鸦用户 ID 作为门禁用户 ID 下发给门禁。

门禁功能点说明

详细情况请参考 公区设备功能点。

功能点 code 说明
tyabinmc7h 人脸识别
tyabirdc5c 二维码
tyabiym3h3 刷卡
tyabi8n4fs 远程开门
tyabiwvwhq 可视化对讲
tyabikrhuc 蓝牙通行
tyabi9pqys 密码通行
tyabianxfw 指纹通行
tyabitkn9q 测温
tyabifgx7y 常开
tyabiu3s3d 常闭
tyabijhcym 日程功能

API 说明

门禁用户管理

API 名称 接口地址
删除人员 DELETE:/v1.0/access-control/{device_id}/persons/{person_id}
新增人员 POST:/v1.0/access-control/{device_id}/persons/{person_id}
更新人员 PUT:/v1.0/access-control/{device_id}/persons/{person_id}

门禁人脸管理

API 名称 接口地址
新增人脸 POST:/v1.0/access-control/{device_id}/persons/{person_id}/faces/{face_id}
删除人脸 DELETE:/v1.0/access-control/{device_id}/persons/{person_id}/faces/{face_id}
更新人脸 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/faces/{face_id}

门禁二维码管理

API 名称 接口地址
删除二维码 DELETE:/v1.0/access-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
新增二维码 POST:/v1.0/access-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
更新二维码 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}

门禁卡管理

API 名称 接口地址
冻结门禁卡 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/card/{card_no}/freeze
删除门禁卡 DELETE:/v1.0/access-control/{device_id}/persons/{person_id}/card/{card_no}
解冻门禁卡 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/card/{card_no}/unfreeze
新增门禁卡 POST:/v1.0/access-control/{device_id}/persons/{person_id}/card/{card_no}
更新门禁卡 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/card/{card_no}

门禁通行密码管理

API 名称 接口地址
删除门禁通行密码 DELETE:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}
更新门禁通行密码 PUT:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}
新增门禁通行密码 POST:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}

门禁远程开门

API 名称 接口地址
开门指令发送 POST:/v1.0/access-control/{device_id}/persons/{person_id}/actions/open

呼叫住户

API 名称 接口地址
呼叫门禁人员 POST:/v1.0/access-control/{device_id}/persons/actions/call

门禁用户批量操作

API 名称 接口地址
批量新增人员 POST:/v1.0/access-control/{device_id}/persons
批量新增二维码 POST:/v1.0/access-control/{device_id}/persons/qrcodes
批量删除人员 DELETE:/v1.0/access-control/{device_id}/persons
批量删除人脸 DELETE:/v1.0/access-control/{device_id}/persons/faces
批量新增人脸 POST:/v1.0/access-control/{device_id}/persons/faces
批量删除二维码 DELETE:/v1.0/access-control/{device_id}/persons/qrcodes

门禁设备管理

API 名称 接口地址
清理设备数据 POST:/v1.0/access-control/{device_id}/actions/cleardata
云端同步设备端时间 POST:/v1.0/access-control/{device_id}/actions/synctime

门禁事件格式

云开发项目开启消息订阅后，可以收到门禁设备端上报的事件消息。

消息队列接入流程请参考 消息队列。

通行记录上报

功能描述

用户触发门禁通行，门禁会上报用户的通行事件给开发者。事件 Code 为 event_pass，部分老设备的事件 Code 为 pass_event。

value 参数说明

参数名 类型 说明 必填
uid String 通行人员 ID。如果是陌生人，默认传 -1。 是
way Integer 通行方式。
  • 1：卡
  • 2：密码
  • 3：二维码
  • 4：人脸
  • 5：指纹
  • 6：红外感应
  • 8：蓝牙
  • 9：远程
  • 10：其它
 是
t Long 通行时间，13 位时间戳。 是
success Integer 是否成功。
  • 1：成功
  • 0：失败
是
message String 通行事件描述。如果通行失败，则返回失败原因。 否
passURL String 通行照片 URL。人员通行时，设备抓拍的人员照片。通行照片的 URL 是临时 URL，开发者需要根据 URL 下载照片并存储。 否
passPwd String 通行密码（密码通行模式下会上报通行密码）。 否
cardNo String 卡号。 否
temp String 体温。 否
passType Integer 通行类型。
  • 1：进
  • 2：出
 否
location String 位置信息。 否

数据示例

{
    "dataId": "AAXRV4BrtW9BRB9A2JY****",
    "devId": "6cac703763f7653deb****",
    "productKey": "iyktmr3hd2qp****",
    "status": [
        {
            "126": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}",
            "code": "event_pass",
            "t": 1637548630455,
            "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}"
        }
    ]
}

呼叫事件上报

功能描述

用户在可视门禁上输入房间号，呼叫业主或挂断通话都会触发该事件。开发者收到该事件后, 调用 呼叫门禁人员 接口，通知住户 App。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 Code，doorCall。 是
devId String 涂鸦设备 ID。 是
productKey String 产品 ID。 是
ts Long 时间 13 位时间戳。 是
bizData Object 业务数据。 是

bizData 参数说明

参数名 类型 说明 必填
deviceId String 涂鸦设备 ID。 是
type Integer 操作类型，见详细说明。 是
sn String SN 号。同一个呼叫流程里，SN 号都相同。 是
targetAddress String 被呼叫房间号。房间号格式如：01-01-01-01-01-01，表示 01 小区 01 苑 01 幢 01 单元 01 层 01 号房间。没有则传 00，比如没有苑，苑的位置传 00。
房间号的位数和设备的位置相关，如设备装在单元门上，则设备只需要传几层几号房间。		 是
happenTime Long 13 位时间戳。 否

操作类型详细说明

操作类型 场景 操作
1 设备呼叫业主 设备发送 type=1 事件。
2 设备呼叫业主，设备主动挂断 设备发送 type=3 事件，如果 App 已接听，通话开始时间/结束时间传值。
3 设备呼叫业主，呼叫时间超过设备限定，设备挂断。设备限定呼叫超时时间默认 30s。 设备发送 type=4 事件。
4 设备呼叫业主，业主接听后挂断 设备发送 type=5 事件，通话开始时间/结束时间需要传值。
5 设备呼叫业主，业主接听后，通话时间超过设备限定，设备挂断。设备限定通话超时时间默认 90s。 设备发送 type=7 事件，通话开始时间/结束时间需要传值。

数据示例

{
  "bizCode": "doorCall",
  "bizData": {
    "happenTime": 1612514362591,
    "targetAddress": "00-00-00-00-01-01",
    "sn": "121258194744908****",
    "type": 4
  },
  "devId": "6ce23ee0de009667c0****",
  "productKey": "hipg3mmwafxc****",
  "ts": 1637292665405
}

门禁告警上报

功能描述

门禁主动上报告警事件给开发者。事件 Code 为 alarm_info_report。

value参数说明

参数名 类型 说明 必填
alarmId String 告警序列号。 是
alarmType Integer 告警类型。
  • 1：防拆报警
  • 2：陌生人报警
  • 3：尾随
  • 4：逗留
  • 5：反潜
  • 10：其它
 是
alarmCont String 告警内容。 是
picURL String 抓拍图片 URL。 否
happenTime Long 告警发送时间。 是
confirmEnable Boolean 是否已处理。
  • true：已处理
  • false：未处理
 否
extendData String 扩展信息，JSON 类型。 否

extendData JSON 字段说明

参数名 类型 说明 是否必传
taggerType Integer 尾随者类型。告警类型为尾随类型时，即 alarmType 数值为 3 时，须传。
  • 1：家人
  • 2：陌生人
 否

数据示例

{
  "dataId": "AAXRV4BrtW9BRB9A2JYW****",
  "devId": "6cac703763f7653deb****",
  "productKey": "iyktmr3hd2qp****",
  "status": [
    {
      "126": "{\"alarmName\": \"设备异常\",\"happenTime\": 1609435288373,\"alarmType\": 1,\"alarmCont\": \"异常\",\"confirmEnable\": false,\"alarmId\": \"123123123123\",\"extendData\": \"\"}",
      "code": "alarm_info_report",
      "t": 1637548630455,
      "value": "{\"alarmName\": \"设备异常\",\"happenTime\": 1609435288373,\"alarmType\": 1,\"alarmCont\": \"异常\",\"confirmEnable\": false,\"alarmId\": \"123123123123\",\"extendData\": \"\"}"
    }
  ]
}

其它

门禁二维码

目前，二维码分为静态二维码和动态二维码。

  • 静态二维码：二维码固定不变，二维码与住户绑定，由开发者下发给设备。
  • 动态二维码：二维码定期刷新，设备端根据用户信息中的秘钥与时间因子动态生成。

门禁二维码流程

  1. 下发二维码。
    • 静态二维码：开发者调用接口下发静态二维码给设备。
    • 动态二维码：开发者调用接口下发住户信息给设备，设备端根据住户信息的动态秘钥生成动态二维码。
  2. 设备端保存静态二维码，或根据住户的动态秘钥生成动态二维码。
  3. 在 App 端生成相应二维码。
  4. 门禁设备扫描二维码，匹配成功后，识别成功并上报通行事件。

门禁二维码格式

二维码内容格式:

{
  "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="  //value：Base64 编码后字符串
}

门禁二维码生成（App 端）

静态二维码

静态二维码生成步骤:

  1. 拼接二维码字符串 “UID|二维码内容”。
  2. 对 "UID|二维码内容"进行 Base64 编码。
  3. 生成 JSON 格式的二维码内容。

示例:

    用户 ID: ay16110581781387****
    用户二维码内容: 46bff10b9bf843fab194cf246bf****
    对 "ay16110581781387****|46bff10b9bf843fab194cf246bf****" 进行 base64 编码,
    生成的字符串如下:      
      YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg=
    二维码的内容如下:
    {
      "qrcode": "YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg="
    }
动态二维码

动态二维码生成步骤:

  1. 通过 generateTOTP 方法生成二维码信息。
  2. 对 “UID|二维码信息” 进行 base64 编码。
  3. 生成 JSON 格式的二维码内容。

generateTOTP 方法参考代码:

/**
* 生成动态码
*
* @param uid           涂鸦用户 ID
* @param secretKey     秘钥, 32 位字符串, 建议由 UUID 生成
* @param refreshTime   二维码刷新时间
* @return
*/
public static TOTPTokenCodeDTO generateTOTP(String uid, String secretKey, Long refreshTime) {
      if (StringUtils.isBlank(uid) || StringUtils.isBlank(secretKey) || refreshTime == null) {
      log.error("请求参数有误, uid:{}, secretKey:{}, refreshTime:{}", uid, secretKey, refreshTime);
      throw new RuntimeException("请求参数有误");
      }

      // 获取当前时间的时间戳
      long now = new Date().getTime();
      // 将动态因子转为 16 进制
      String time = Long.toHexString(timeFactor(now, refreshTime)).toUpperCase();
      String totp = doGenerateTOTP(uid + secretKey, time);
      //本周期动态码已生成时长
      long usedTime = validTime(now, refreshTime);
      return new TOTPTokenCodeDTO(totp, usedTime);
      }

/**
* @param key  用户 ID+种子密钥
* @param time 时间因子
* @return
*/
private static String doGenerateTOTP(String key, String time) {
      // 1. 如果 time 小于 16 个字符，则用零补齐，例如：30B649C -> 00000000030B649C
      StringBuilder timeBuilder = new StringBuilder(time);
      while (timeBuilder.length() < 16) {
      timeBuilder.insert(0, "0");
      }
      time = timeBuilder.toString();

      // 2. 16 进制转 2 进制
      byte[] msg = hexStr2Bytes(time);
      // 3. 将 key 转为字节
      byte[] k = key.getBytes();
      // 4. 哈希加密
      byte[] hash = hmac_sha("HmacSHA256", k, msg);
      // 5. 返回指定位数的动态口令
      String encodeHexStr = Hex.encodeHexString(hash);
      StringBuilder result = new StringBuilder(encodeHexStr);
      //6. 如果返回值小于指定的位数，则用 0 补齐
      while (result.length() < 8) {
      result.insert(0, "0");
      }
      return result.substring(0, 8);
      }

/**
* 获取动态因子
*
* @param targetTime 指定时间
* @param refreshTime       时间步长，单位：毫秒，作为动态口令变化的时间周期
* @return long
*/
private static long timeFactor(Long targetTime, long refreshTime) {
      return targetTime / refreshTime;
      }

/**
* 获取本周期动态码已生成时长
*
* @param targetTime
* @param refreshTime
* @return
*/
private static long validTime(long targetTime, long refreshTime) {
      return targetTime % refreshTime;
      }

/**
* 哈希加密
*
* @param crypto   加密算法
* @param keyBytes 密钥数组
* @param text     加密内容
* @return byte[]
*/
private static byte[] hmac_sha(String crypto, byte[] keyBytes, byte[] text) {
      try {
      Mac hmac;
      hmac = Mac.getInstance(crypto);
      SecretKeySpec macKey = new SecretKeySpec(keyBytes, "AES");
      hmac.init(macKey);
      return hmac.doFinal(text);
      } catch (GeneralSecurityException gse) {
      throw new RuntimeException(gse);
      }
      }

private static byte[] hexStr2Bytes(String hex) {
      byte[] sourceArray = new BigInteger("10" + hex, 16).toByteArray();
      byte[] targetArray = new byte[sourceArray.length - 1];
      // 将原数组 copy 到目标数组
      // src：表示源数组，srcPos：源数组要复制的起始位置，dest：表示目标数组，destPos：目标数组要复制的起始位置，length：表示要复制的长度
      System.arraycopy(sourceArray, 1, targetArray, 0, targetArray.length);
      return targetArray;
      }

示例:

    用户 ID: ay16110581781387****
    密钥: 46bff10b9bf843fab194cf246bfe****
    二维码刷新时间: 5 * 60 * 1000
    generateTOTP 方法生成二维码信息: e4af****
    对 `ay16110581781387****|e4af****` 进行 base64 编码,
    生成的字符串:
    7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA=
    二维码的内容:
    {
    "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="
    }

门禁事件 1.0 格式

设备事件消息兼容 1.0 版本格式。如需开通 1.0 版本格式，请联系涂鸦工作人员。接入流程参考 公区设备事件1.0格式接入。

通行记录上报

功能描述

用户触发门禁通行，门禁会上报用户的通行事件给开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认edge_device。 是
eventType String 事件类型，默认edge_report_data。 是
mode String 事件模式，默认door_pass。 是
deviceId String 涂鸦设备 ID。 是
way Integer 通行方式。
  • 1：卡
  • 2：密码
  • 3：二维码
  • 4：人脸
  • 5：指纹
  • 9：远程
  • 10：其它
 是
personId String 通行人员 ID。如果是陌生人，默认传 -1。 是
passURL String 通行照片 URL。人员通行时，设备抓拍的人员照片。通行照片的 URL 是临时 URL，开发者需要根据 URL下载照片并存储。 否
cardNo String 卡号。 否
temp String 体温。 否
success Integer 是否成功。
  • 1：成功
  • 0：失败
是
message String 通行事件描述。如果通行失败，则返回失败原因。 否
happenTime Long 设备上线/离线时间，13 位时间戳。 是

数据示例

{
	"data": "{\"mode\":\"door_pass\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"message\\\":\\\"门禁通行\\\",\\\"passURL\\\":\\\"http://www.xxx.com/image.jpg\\\",\\\"personId\\\":\\\"ay16110581781387n472\\\",\\\"way\\\":4}\",\\\"success\\\":1}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}

呼叫事件上报

功能描述

用户在可视门禁上输入房间号，呼叫业主或挂断通话都会触发该事件。开发者收到该事件后, 需要调用 呼叫住户 接口，把事件通知给住户 App。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认edge_device。 是
eventType String 事件类型，默认edge_report_data。 是
mode String 事件模式，默认door_call。 是
deviceId String 涂鸦设备 ID。 是
type Integer 操作类型，见详细说明。 是
sn String SN 号.同一个呼叫流程，SN 号都相同。 是
targetAddress String 被呼叫房间号。房间号格式如：01-01-01-01-01-01，表示 01 小区 01 苑 01 幢 01 单元 01 层 01 号房间。没有则传 00。比如没有苑，苑的位置传 00。
房间号的位数和设备的位置相关，如设备装在单元门上， 则设备只需要传几层几号房间。		 是
beginTime Long 通话开始时间，13 位时间戳。 否
endTime Long 通话结束时间，13 位时间戳。 否
happenTime Long 事件发生时间，13 位时间戳。 是

操作类型详细说明

操作类型 场景 操作
1 设备呼叫业主 设备发送 type=1 事件。
2 设备呼叫业主，设备主动挂断 设备发送 type=3 事件。如果 App 已接听，通话开始时间/结束时间有值。
3 设备呼叫业主，呼叫时间超过设备限定，设备挂断。设备限定呼叫超时时间默认 30s。 设备发送 type=4 事件。
4 设备呼叫业主，业主接听后挂断 设备发送 type=5 事件，通话开始时间/结束时间有值。
5 设备呼叫业主，业主接听后，通话时间超过设备限定，设备挂断。设备限定通话超时时间默认 90s。 设备发送 type=7 事件，通话开始时间/结束时间有值。

数据示例

{
	"data": "{\"mode\":\"door_call\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"beginTime\\\":1612514362591,\\\"endTime\\\":1612514362591,\\\"targetAddress\\\":\\\"00-00-00-00-01-01\\\",\\\"sn\\\":\\\"1212581947449081856\\\",\\\"callType\\\":4}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}

门禁告警上报

功能描述

门禁主动上报告警事件给开发者。

参数说明

参数名 类型 说明 必填
bizCode String 事件业务 code，默认 edge_device。 是
eventType String 事件类型，默认 edge_report_data。 是
mode String 事件模式，默认 door_alarm。 是
deviceId String 涂鸦设备 ID。 是
alarmId String 告警序列号。 是
alarmType Integer 告警类型。
  • 1：防拆报警
  • 2：陌生人报警
  • 3：尾随
  • 4：逗留
  • 5：反潜
  • 10：其它
 是
alarmCont String 告警内容。 是
picURL String 抓拍图片 URL。 否
happenTime Long 告警发送时间。 是
confirmEnable Boolean 是否已处理。
  • true：已处理
  • false：未处理
 否
extendData String 扩展信息，JSON 类型。 否

extendData JSON 字段说明

参数名 类型 说明 是否必传
taggerType Integer 尾随者类型。告警类型为尾随类型时，即 alarmType 数值为 3 时，须传。
  • 1：家人
  • 2：陌生人
 否

数据示例

{
  "data": "{\"mode\":\"door_pass\",\"data\":\"{\\\"deviceId\\\":\\\"123123123\\\",\\\"alarmName\\\": \\\"设备异常\\\",\\\"happenTime\\\": 1609435288373,\\\"alarmType\\\": 1,\\\"alarmCont\\\": \\\"异常\\\",\\\"confirmEnable\\\": false,\\\"alarmId\\\": \\\"123123123123\\\",\\\"extendData\\\": \\\"\\\"}\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}
上一篇门禁开放能力
下一篇门禁用户管理
语言
简体中文
简体中文
English
400-881-8611
7×24小时服务热线
市场合作
marketing@tuya.com
业务合作
service@tuya.com
媒体联络
pr@tuya.com
关注“涂鸦智能”
涂鸦服务尽在掌握
关注“全球智能商业”
第一时间获取物联网资讯
联系我们加入我们TuyaExpoApp 商城TuyaGoTuyaGo服务商查询
法律声明隐私协议加州隐私权利声明服务条款廉正合规安全应急响应中心
©2014-2024 杭州涂鸦信息技术有限公司 版权
浙ICP备14011795号
浙B2-20210233号
浙公网安备33010602004238号
简体中文
简体中文
English