edit

云端API总览

前言

我们再来看下氦氪云的整体流程图。

  • D <-> C是设备和云端之间的双向链路,目前支持TCP、WebSocket长连接方式。U <-> C是用户(实际上是APP)和云端之间的双向链路,目前支持TCP、WebSocket长连接方式。U <-> D是设备和APP之间的双向链路,它是虚拟的(局域网控制时除外),实际云端C起到了中转的作用。因为是长连接,U <-> D可以被当做一个双向即时消息通道。在这个通道上,我们实现了一些API,叫做基础通信API
  • 云端对设备提供TCP、WebSocket短连接服务、HTTP服务,主要实现了设备端查询产品信息以实现负载均衡等功能,叫做产品信息查询API
  • 云端实现了一套账户体系,包括手机或邮箱注册、校验码验证、第三方社交账号登录等,账户体系暴露的API叫做认证授权API
  • 云端对APP提供HTTP/HTTPS服务,大量的云端服务被包装成API提供给APP调用,以实现复杂的功能,比如拉取设备列表、设备授权等,这部分API叫做用户API;比如获取厂家信息等,这部分API叫做企业API

下面我们分节对以上几类云端 API做详细说明。

curl说明

本文档从第三章开始的示例中使用的都是curl 命令,如果您没有安装curl,请从curl官方下载。

请注意,Windows下的语法与Linux和OS X下的略有不同。本文中的所有curl示例都是使用Linux和OS X下的语法。如果你使用的是Windows,那么所用的curl binary(比如,Generic、Cygwin 和 MinGW)可能会采用不同的语法。请参考curl技术文档了解语法的差异。

比如,假设使用的是Windows中的Generic curl binary,那么你需要修改如下内容:

  • 当编写跨行的命令时,你需要在行尾使用^而不是\
  • 当发送的请求带有Body时,你需要使用""括起Body而不是''
  • 如果请求的Body中包含", 你需要使用\来转义双引号。

例如:

curl -v -X PUT ^
-H "Authorization: Bearer {JWT_TOKEN}" ^
-H "Content-Type: text/plain" ^
"https://user-openapi.hekr.me/folder/{folderId}" ^
-d "newFolderName"

主要参数说明

参数名 说明 备注
msgId 消息ID 消息ID,0~65535,循环递增
action 指令 用来在消息通道里,标识每个消息的具体含义
devTid 设备ID 即使ID相同,云端也会区分为两个设备
appTid APP ID 即使ID相同,云端也会区分为两个APP
ctrlKey 控制设备时使用的key 云端颁发,32个字节
bindKey 绑定/解绑设备时使用的key 云端颁发,32个字节
prodKey 产品唯一标识(即产品密钥) 开发者在控制台上添加产品时自动生成,32个字节
ProdPubKey 设备产品公共密钥 通过接口“4.1.2 列举设备列表”获取
cid 产品类目唯一ID 氦氪云自己维护
mid 产品型号唯一ID 开发者在控制台上添加产品时自动生成
pid 厂家唯一ID 开发者认证申请通过之后自动生成
workMode 设备工作模式 设备工作方式,0.JSON透传、1.JSON主控
tokenType token类型 0\1:保留、2:动态token,现在云端只支持动态token
encryptType 加密类型 "None" :不加密、"SSL" :SSL加密,现在云端支持非加密和加密两种通道
connectType 连接类型 "tcp" :tcp长连接、"websocket" :websocket长连接
code 调用返回码 具体请看下面的返回码表
desc code对应描述 具体请看下面的返回码表

其他参数,在文档中单独说明。

1. 产品信息查询API

服务地址

域名:端口 功能 协议 数据安全级别 服务区域
info-dev.hekr.me:80 产品信息查询服务 HTTP 非SSL 全球
info-dev.hekr.me:91 产品信息查询服务 TCP 非SSL 全球
info-dev.hekr.me:92 产品信息查询服务 WebSocket 非SSL 全球
  • 如果使用HTTP,连接http://host:port
  • 如果使用TCP,连接tcp://host:port
  • 如果使用WebSocket,连接ws://host:port

调用说明

设备联网时,应该首先访问该服务。

  • 从应答里解析出serviceHost和servicePort,得到连接的目标地址。
  • 从应答里解析出connectType,决定建立tcp长连接还是websocket长连接。
  • 从应答里解析出encryptType,决定使用非加密还是加密通道。
  • 确定以上信息后,和云端建立真正的连接。

如果使用氦氪固件或氦氪嵌入式SDK,您并不需要关注这些细节,固件和SDK会封装好。

1.1 通过HTTP协议查询产品信息


curl -v -X POST \
    "http://info-dev.hekr.me/locate/getAddress" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "msgId": 90,
        "action": "getProdInfo",
        "params": {
          "devTid": "TEST_DEV001",
          "prodKey": "test_prod_key"
        }
    }'

返回


< 200
< {
  "msgId": 90,
  "action": "getProdInfoResp",
  "code": 200,
  "desc": "success",
  "params": {
    "mid": "test_mid",
    "workMode": 1,
    "tokenType": 2,
    "serviceHost": "host",
    "servicePort": 83,
    "encryptType": "None",
    "connectType": "tcp"
  }
}

1.2 通过WebSocket协议查询产品信息

请求地址


ws://info-dev.hekr.me:92/ws/locate/getAddress

请求数据

请求数据与1.1中描述的请求数据相同,但数据格式不是JSON对象,而是一个JSON格式的字符串,注意末尾有"\n"换行符。


{
  "msgId" : 90,
  "action" : "getProdInfo",
  "params" : {
    "devTid" : "TEST_DEV001",
    "prodKey" : "test_prod_key"
  }
}\n

返回数据

返回数据同1.1,数据格式也是一个JSON格式的字符串,注意字符串末尾有"\n"换行符。


{
  "msgId" : 90,
  "action" : "getProdInfoResp",
  "code" : 200,
  "desc" : "success",
  "params" : {
    "mid" : "test_mid",
    "workMode" : 1,
    "tokenType" : 2,
    "serviceHost" : "host",
    "servicePort" : 83,
    "encryptType" : "None",
    "connectType" : "tcp"
  }
}\n

WebSocket在线调试

主流编程语言(Java、Python、JavaScript、PHP等)都有提供专门的开发包或者开发库来实现WebSocket调用,开发者可以点击这里在线体验WebSocket调用。

调试步骤如下:

  1. 在Location中输入:ws://info-dev.hekr.me:92/ws/locate/getAddress
  2. 点击Connect。
  3. 如果服务正常,在Log框中将显示:CONNECTED
  4. 在Message中输入:{"msgId" : 90,"action" : "getProdInfo","params" : {"devTid" : "TEST_DEV001","prodKey" : "test_prod_key"}}
  5. 点击Send。
  6. 如果服务正常,可以在Log框中查看服务器的返回数据。

1.3 通过TCP协议查询产品信息

请求地址


tcp://info-dev.hekr.me:91

请求数据

同1.2。

返回数据

同1.2。

TCP调试

主流编程语言或者平台(Java、Python、NodeJS、PHP等)都有提供TCP开发包(即Socket开发包),开发者可以在命令行工具中通过“telnet”命令来调试TCP接口。

调试步骤如下:

  1. 在命令行工具输入:telnet info-dev.hekr.me 91
  2. 输入请求参数:{"msgId" : 90,"action" : "getProdInfo","params" : {"devTid" : "TEST_DEV001","prodKey" : "0126736378c6ba606ca72d9"}}
  3. 回车。
  4. 查看服务器返回结果。

错误码

错误码 提示信息 中文释义 可能造成的原因
9200000 Success 调用成功
9400000 Error 未知错误 该行以下所有9400开头的错误码需要单独处理
9400001 Bad param 非法参数
9400002 Action does not exist action不存在
9400003 Product does not exist 产品不存在
9400004 Time out 超时
9400005 Method not support 方法不支持
9500000 Server error 服务错误
9500001 Server response error 服务应答错误

2. 基础通信API

服务地址

域名:端口 功能 协议 数据安全级别 服务区域
asia-dev.hekr.me:83 设备<->云端通道 TCP长连接 非SSL 亚太
asia-dev.hekr.me:183 设备<->云端通道 TCP长连接 SSL 亚太
asia-dev.hekr.me:84 设备<->云端通道 WebSocket长连接 非SSL 亚太
asia-dev.hekr.me:184 设备<->云端通道 WebSocket长连接 SSL 亚太
asia-app.hekr.me:85 APP<->云端通道 TCP长连接 非SSL 亚太
asia-app.hekr.me:185 APP<->云端通道 TCP长连接 SSL 亚太
asia-app.hekr.me:86 APP<->云端通道 WebSocket长连接 非SSL 亚太
asia-app.hekr.me:186 APP<->云端通道 WebSocket长连接 SSL 亚太

此外,还有北美节点、欧洲节点,把asia替换成america、europe(america、europe正在建设中)即可

2.0 设备和用户绑定

指令格式


{
    "msgId" : 123,
    "action" : "devBind",
    "params" : {
        "devTid" : "ESP_34ABE",
        "prodKey" : "0cc175b9c0f1b6a831c399e269772661",
        "PINCode" : "1234",
        "SSID" : "HEKR",
        "token" : ""  //首次配网填空,其他情况填设备端保存的token
    }
}\n

应答格式


{
    "msgId" : 123,
    "action" : "devBindResp",
    "code" : 200,
    "desc" : "success",
    "params" : {
        "devTid" : "ESP_34ABE",
        "token" : "4a8a08f09d37b737956490",
        "ctrlKey" : "20005c97f94aff9d7ff8",
        "bindKey" : "92eb5ffee6ae2fec3ad7"
    }
}
}\n

调用说明

设备配网成功后需要和用户建立绑定关系以实现用户对设备的控制,token填写空字符串"",表示新设备。

返回参数说明:

  • token,新的设备token。设备下次再和云端建立通道时,务必使用这个新token,否则有可能导致设备被锁。
  • ctrlKey,控制码。APP远程控制设备时,必须使用这个key。
  • bindKey,绑定码。APP绑定、解绑设备时,必须使用这个key。

2.1 设备和云端建立通道

指令格式


{
    "msgId" : 123,
    "action" : "devLogin",
    "params" : {
        "devTid" : "ESP_34ABE",
        "prodKey" : "0cc175b9c0f1b6a831c399e269772661",
        "token" : "4a8a08f09d37b737956490"    // 设备第一次联网时填""
    }
}\n

应答格式


{
    "msgId" : 123,
    "action" : "devLoginResp",
    "code" : 200,
    "desc" : "success",
    "params" : {
        "devTid" : "ESP_34ABE",
        "token" : "4a8a08f09d37b737956490",   // 新的设备token
        "ctrlKey" : "20005c97f94aff9d7ff8",
        "bindKey" : "92eb5ffee6ae2fec3ad7",
        "forceBind" : true,                     
    }
}\n

调用说明

设备第一次和云端建立通道时,token填写空字符串"",表示新设备。在云端的应答中,有3个参数需要特别注意。

  • token,新的设备token。设备下次再和云端建立通道时,务必使用这个新token,否则有可能导致设备被锁。
  • ctrlKey,控制码。APP远程控制设备时,必须使用这个key。
  • bindKey,绑定码。APP绑定、解绑设备时,必须使用这个key。

以上3个参数都有特殊的设计目的,开发者无需知道其中细节,只要注意每次联网时使用新token即可。

2.2 APP和云端建立通道

指令格式


{
    "msgId" : 240,
    "action" : "appLogin",
    "params" : {
        "appTid" : "35897387434734",
        // 用户在APP上登录账号后,认证授权服务返回的JWT Token
        "token" : "eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsicHVzaC1zZXJ2aWNlIl0sInVzZXJfbmFtZSI6IjY2ODYxMTAyMDYxIiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl0sImV4cCI6MTQ1MDg2NzY0MywiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6ImY4MjA5NmE2LTlkMDUtNGIyNS1hMDU1LWMyMTczMmRkNTg0ZiIsImNsaWVudF9pZCI6ImUxZGUzZWI5LWIxZDEtNDlkMy04ZDNjLWNmYjU2YzU5YmU0YSJ9.bZiprbK9h1ohhEe_u0D-EmzWHxaCU3k6tTsJBmIDjXsI50h78Nudl_Fwoq6lqgPt5mPSKBgxmXIkLkSRz_5uaA"
    }
}\n

应答格式


{
    "msgId" : 240,
    "action" : "appLoginResp",
    "code" : 200,
    "desc" : "success"
}\n

调用说明

指令格式中的参数token,是APP调用认证授权API->登录接口返回的JWT Token,有效期为24小时。如果APP和云端建立通道前token已过期,云端会提示token无效;如果联网之后连接不断,即使token过期,APP还能继续控制设备。

2.3 设备上报详情

指令格式


{
    "msgId" : 291,
    "action" : "reportDevInfo",
    "params" : {                                    // 字段可扩展
        "devTid" : "ESP_4387EF",
        "mid" : "0cc175b9c0f1",
        "workMode" : 0,
        "MAC" : "08EFA809DE6D",                         // 设备MAC地址
        "tokenType" : 2,
        "binVer" : "3.0.61.2",                          // 固件版本
        "binType" : "A",                                // 固件类型
        "SDKVer" : "3.0.61.2",                          // 固件SDK版本
        "serviceHost" : "asia-dev.hekr.me",             // 服务器地址
        "servicePort" : 83,                             // 服务器端口
        "SSID" : "HEKR-TEST"                            // 路由器SSID
    }
}\n

应答格式


{
    "msgId" : 291,
    "action" : "reportDevInfoResp",
    "code" : 200,
    "desc" : "success"
}\n

调用说明

如果希望云端大数据分析的结果是正确无误的,这里面的每个参数都需要保证正确。

2.4 APP发送数据到设备

2.4.1 设备使用JSON主控协议时

指令格式


{
    "msgId" : 291,
    "action" : "appSend",
    "params" : {
        "devTid" : "ESP_245EC89",                       // 接收数据的设备ID
        "ctrlKey" : "123456789123456789",               // APP调用用户API"获取设备列表"时会返回该参数
        "appTid" : "54354353454",                       // 发送数据的APP ID
        "data" : {
            "cmdId" : 0,                                // 下发指令编号
            "key1" : "value1",                          // 设备参数键值对1
            "key2" : value2,                            // 设备参数键值对2
            ...                                         // 更多设备参数键值对
        }

    }
}\n

应答格式


{
    "msgId" : 291,
    "action" : "appSendResp",
    "code" : 200,
    "desc" : "success",
    "params" : {
        "devTid" : "ESP_245EC89",                       // 发送数据的设备ID
        "ctrlKey" : "123456789123456789",
        "appTid" : "345887867637",                      // 接收数据的APP ID
        "data" : {
            "cmdId" : 0
            "key1" : "value1",
            "key2" : value2,
            ...
        }
    }
}\n

调用说明

  • cmdId、key1、key2、...,这些值,可在氦氪云控制台->产品管理->参数信息->产品参数信息页面上查看它们的具体定义。
  • 指令和应答里的key1、key2、...,不一定是完全一致的,因为指令里的key1等值是期望值,应答里的值是返回一瞬间设备的实际值,各种因素都可能导致不一致。

2.4.2 设备使用JSON透传协议时

指令格式


{
    "msgId" : 291,
    "action" : "appSend",
    "params" : {
        "devTid" : "ESP_245EC89",
        "ctrlKey" : "123456789123456789",
        "appTid" : "358974675345",
        "data" : {
            "raw" : "48EF4DFA"                          // 注意这里和JSON主控协议的区别
        }
    }
}\n

应答格式


{
    "msgId" : 291,
    "action" : "appSendResp",
    "code" : 200,
    "desc" : "success",
    "params" : {
        "devTid" : "ESP_245EC89",
        "ctrlKey" : "123456789123456789",
        "appTid" : "345887867637",
        "data" : {
            "raw" : "48EF4DFA"
        }
    }
}\n

调用说明

  • raw的具体格式,可在氦氪云控制台->产品管理->参数信息->产品参数信息页面上查看。
  • 和JSON主控情况一样,指令和应答里的raw不一定一致,原因同上。

2.5 设备发送数据到APP

2.5.1 设备使用JSON主控协议时

指令格式


{
    "msgId" : 382,
    "action" : "devSend",
    "params" : {
        "devTid" : "ESP_245EC89",                       // 发送数据的设备ID
        "appTid" : [],                                  // 接收数据的多个APP ID
        "data" : {
            "cmdId" : 9,                                // 上报指令编号
            "key1" : "value1",                          // 设备参数键值对1
            "key2" : value2,                            // 设备参数键值对2
            ...                                         // 更多设备参数键值对
        }
    }
}\n

应答格式


{
    "msgId" : 382,
    "action" : "devSendResp",
    "code" : 200,
    "desc" : "success"
}\n

调用说明

  • 指令里面的appTid参数为[ ]时,表示设备最大组播;不为[ ]时,每个元素都是APP ID,系统只会发送到这些指定APP上。云端暂时只支持appTid为[ ]
  • cmdId、key1、key2、...,这些值,可在氦氪云控制台->产品管理->参数信息->产品参数信息页面上查看它们的具体定义。

2.5.2 设备使用JSON透传协议时

指令格式


{
    "msgId" : 382,
    "action" : "devSend",
    "params" : {
        "devTid" : "ESP_245EC89",
        "appTid" : [],
        "data" : {
            "raw" : "48EFDFAB"                          // 注意这里和JSON主控协议的区别
        }
    }
}\n

应答格式


{
    "msgId" : 382,
    "action" : "devSendResp",
    "code" : 200,
    "desc" : "success"
}\n

调用说明

  • appTid参数的取值情况同上。
  • raw的具体格式,可在氦氪云控制台->产品管理->参数信息->产品参数信息页面上查看。

2.6 设备、APP发送心跳

指令格式


{
   "msgId" : 98,
   "action" : "heartbeat"
}\n

应答格式


{
    "msgId" : 98,
    "action" : "heartbeatResp",
    "code" : 200,
    "desc" : "success"
}\n

调用说明

如果30秒内云端没有收到任何数据,则会主动断开与设备的连接,所以设备、APP必要时可以发送心跳指令来保活连接。

错误码表

错误码 提示信息 中文释义 可能造成的原因
1200000 Success 调用成功
1400000 Error 未知错误 该行以下所有1400开头的错误码需要单独处理
1400001 Json parse error json解析错误 json格式错误
1400002 JWT parse error jwt_token解析错误 jwt token错误
1400003 The field {0} contains a value that is too high 属性值过高 发送报文中某属性的值超过了其上限
1400004 The field {0} contains a value that is too low 属性值过低 发送报文中某属性的值低于了其下限
1400005 The value of the field {0} must be an enumerated value 属性值必须为范围内枚举值 发送报文中某属性值不符合其定义的取值范围
1400006 Field {0} not exist 属性不存在 发送报文中存在了未定义的属性
1400008 devTid not match 设备ID不匹配 报文填写的devTid与登录设备的devTid不一致
1400009 App repeat login APP重复登录 同一个appTid的app重复登录
1400010 User does not exist 用户不存在 用户不存在或者uid填错了
1400011 The device does not have this instruction 设备不具有该指令 设备不具备该指令
1400012 Device does not belong to user 设备不属于该用户 设备不再属于该用户
1400013 Device repeat login 设备重复登录 设备同时登录
1400014 Frame parse error 帧解析错误 报文格式或内容错误
1400015 Device last token can not use 设备上一次token已过期无法使用 使用的旧token已经超过上限
1400016 Action not support 该帧行为不被支持 报文中的action填错了
1400017 Device token can not verification 设备token校验错误 设备token错误
1400018 Device not online 设备不在线 设备离线
1400019 App is not logged in app未登录 app未登录或其他原因导致云端认为app已经离线
1400020 Device is not logged in 设备未登录 设备未登录或其他原因导致云端认为设备已经离线
1400023 appTid does not match app设备id不匹配 当前发送报文的appTid与绑定设备时的appTid不一致
1400024 You report info does not match your connect server 上报节点信息与实际不符 上报的内容与当时连接节点信息不一致
1400025 RAW not valid, Please check your protocol template 协议不合法,请参照协议模板 48协议串不合法
1400026 AuthKey can't auth authKey 认证失败 填写了错误的authkey
1400027 Product key not available 不是有效的pk 填写了错误的pk
1400028 PinCode or SSID not available pinCode或者ssid无效 填写了无效的pinCode或者ssid
1400029 Bind failed due to timeout error 绑定设备超时错误 绑定设备超时
1400030 Can not bind other manufacture's device 无法绑定其它厂商的设备 APP绑定了非该厂家的设备
1400031 Can not force bind device 无法强绑设备 设备设定为无法强绑,强绑失败
1500000 Internal error ({0}) 内部错误 服务内部错误
1500001 Link error 链路错误 链路错误

3. 认证授权API

服务地址

域名:端口 功能 协议 数据安全级别 服务区域
uaa-openapi.hekr.me:80 提供认证授权功能 HTTP 非SSL 全球

错误返回方式说明

调用接口成功返回20X,如有返回内容会在body中给出,没有返回内容body将为空,仅有HTTP头。

调用接口失败返回40X或500,错误信息会在body中给出。

如果返回的HTTP Code是401,请检查请求头是否正确。

3.1 发送短信验证码


curl -v -X GET \
    -H "Accept: application/json" \
    "https://uaa-openapi.hekr.me/sms/getVerifyCode?phoneNumber=138xxxxxxxx&pid=01698862201&type=register"

参数

参数名 是否可选 参数类型 取值范围 说明
phoneNumber 必选 String 用户手机号码
type 必选 String register, resetPassword, changePhone 验证码用途
pid 必选 String 厂家唯一ID
token 可选 String 图形验证码token

调用说明

  • 每个手机号每天接收验证码的次数有限制。
  • 接口中设置白名单过滤,如果pid在白名单中,访问改接口时,不需要带token信息,否则访问时必须带token参数
  • 参数中的token为3.19接口中返回的token

3.2 校验短信验证码


curl -v -X GET \
    -H "Accept: application/json" \
    "https://uaa-openapi.hekr.me/sms/checkVerifyCode?phoneNumber=138xxxxxxxx&code=000000"

参数

参数名 是否可选 参数类型 取值范围 说明
phoneNumber 必选 String 用户手机号码
code 必选 String 用户收到的短信验证码,长度为6位

返回


< 200
< {
    "phoneNumber" : "138xxxxxxxx",
    "verifyCode" : "101436",
    "token" : "dd27b62f-ce29-4411-9bc2-d1e36f",
    "expireTime" : 1452073528209
}

调用说明

返回中的token在注册时要使用,而且该token有过期时间expireTime。在该时间之前没有注册,token会过期,必须重新获取、校验短信验证码。

3.3 使用手机号注册账号


curl -v -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/register?type=phone" \
    -d '{
        "pid" :"01xxxxxxxxx",
        "phoneNumber" :"138xxxxxxxx",
        "password" :"xxxxxxxx",
        "token" : "dd27b62f-ce29-4411-9bc2-d1e338176f"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String phone 账号注册方式
pid 必选 String 厂家唯一ID
phoneNumber 必选 String 用户手机号码
password 必选 String 密码
token 必选 String 3.2返回里的token

返回


< 200
< {
    "uid" : "51727051945"                               // 用户ID
}

调用说明

  • 提交的JSON里需要填写pid参数,该参数需要在氦氪云控制台->个人中心->认证信息页面里查看。
  • 该接口注册的账号是主账号(OAuth账号是第三方账号)。

3.4 使用邮箱注册账号


curl -v -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/register?type=email" \
    -d '{
        "pid" :"01xxxxxxxxx",
        "email" :"xxxx@hekr.me",
        "password" :"xxxxxxxx"
    }'

系统收到请求后,若确认无异常,会给用户邮箱发送激活邮件,激活邮件支持中英文,随“Accept-Language”请求头内容自动切换。

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String email 账号注册方式
pid 必选 String 厂家唯一ID
email 必选 String 用户邮箱地址
password 必选 String 密码

返回


< 200
< {
    "uid" : "51727051945"                               // 用户ID
}

调用说明

  • 提交的JSON里pid参数,说明同上。
  • 该接口注册的账号是主账号(OAuth账号是第三方账号)。

3.5 使用账号登录


curl -v -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/login" \
    -d '{
        "pid" : "01xxxxxxxxx",
        "username" : "138xxxxxxxx",
        "password" : "xxxxxx",
        "clientType" : "ANDROID"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 厂家唯一ID
username 必选 String 账号名
password 必选 String 账号密码
clientType 必选 String ANDROID, IOS, WP, WEB 客户端类型

返回


< 200
< {
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiJ9.BrWcVY82dmgdY2yM5l-6yYMgHm-VEyE1T_hAhwvz7x2mGpMfWxKTVsvjPYqfAiO79yhakW_-HzvmmCtBCKeTnw",
    "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImF0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjNiOTVmMzkyLWVhMjQtNDIzZC1iMTlkLWZjMmQ2NDVmOGU4MiJ9.jI-6nNVpPTXIaguefTvW_boV5aq77Plobucukw72TNPd9PNHyQwuTl35Mvj9KS1irTOhbdUbj8yISobYQVBuiQ",
    "token_type": "bearer",
    "expires_in": 86399,
    "jti": "7ee5ade2-3d6b-4581-93b6-fea526337742"
}

调用说明

返回中的access_token是JWT Token,注意第四章用户API、第五章企业API中的每个API都会加上一个认证头,使用的就是这个access_token。

3.6 使用手机号重置密码


curl -v -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/resetPassword?type=phone" \
    -d '{
        "pid" : "01xxxxxxxxx",
        "phoneNumber" : "138xxxxxxxx",
        "verifyCode" : "xxxxxx",
        "password" : "xxxxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String phone 重置密码方式
pid 必选 String 厂家唯一ID
phoneNumber 必选 String 用户手机号码
verifyCode 必选 String 短信验证码
password 必选 String 用户密码

返回


< 200
< No Content

调用说明

无。

3.7 修改密码


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/changePassword" \
    -d '{
        "pid" : "01xxxxxxxxx",
        "newPassword" : "xxxxxx",
        "oldPassword" : "xxxxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 厂家唯一ID
newPassword 必选 String 新密码
oldPassword 必选 String 老密码

返回


< 200
< No Content

调用说明

注意头里面需要JWT TOKEN,所以调用时需要登录。

3.8 修改用户手机号

用户的老手机号不用了,想换一个手机号,而且希望老数据都能保存下来,可以使用该接口。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/changePhoneNumber" \
    -d '{
        "pid" : "01xxxxxxxxx",
        "token" : "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
        "verifyCode" : "xxxxxx",
        "phoneNumber" : "138xxxxxxxy"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 厂家唯一ID
token 必选 String 参考调用说明
verifyCode 必选 String 短信验证码
phoneNumber 必选 String 用户手机号码

返回


< 200
< No Content

调用说明

  • 注意头里面需要JWT Token,所以调用时需要登录。
  • 提交的JSON里token参数,需要调用发送短信验证码接口给老手机号发送验证码,并调用校验短信验证码接口成功时获取。
  • 提交的JSON里verifyCode参数,需要调用发送短信验证码接口给新手机号phoneNumber发送验证码获取。
  • 虽然修改了用户手机号,但用户所有老数据均能保存下来。

3.9 发送重置密码邮件


curl -v -X GET \
    "https://uaa-openapi.hekr.me/sendResetPasswordEmail?email=test@hekr.me&pid=01xxxxxxxxx"

激活邮件支持中英文,随“Accept-Language”请求头内容自动切换。

参数

参数名 是否可选 参数类型 取值范围 说明
email 必选 String 邮箱
pid 必选 String 厂家唯一ID

返回


< 200
< No Content

调用说明

无。

3.10 重新发送激活邮件


curl -v -X GET \
    "https://uaa-openapi.hekr.me/resendVerifiedEmail?email=test@hekr.me&pid=01xxxxxxxxx"

激活邮件支持中英文,随“Accept-Language”请求头内容自动切换。

参数

参数名 是否可选 参数类型 取值范围 说明
email 必选 String 邮箱
pid 必选 String 厂家唯一ID

返回


< 200
< No Content

调用说明

无。

3.11 发送修改邮箱邮件

用户的老邮箱不用了,想换一个邮箱,而且希望老数据都能保存下来,可以使用该接口。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://uaa-openapi.hekr.me/sendChangeEmailStep1Email?email=test@hekr.me&pid=01xxxxxxxxx"

参数

参数名 是否可选 参数类型 取值范围 说明
email 必选 String 老邮箱地址
pid 必选 String 厂家唯一ID

返回


< 200
< No Content

调用说明

  • 注意头里面需要JWT Token,所以调用时需要登录。
  • 虽然修改了用户邮箱地址,但用户所有老数据均能保存下来。

3.12 刷新Access Token


curl -v -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://uaa-openapi.hekr.me/token/refresh" \
    -d '{
        "refresh_token" : "eyJhbGciOiJS...",
        "expires_in": 86400
    }'

参数

参数名 是否可选 参数类型 默认值 说明
refresh_token 必选 String 刷新token
expires_in 可选 Integer 86400 token过期时间(秒),最大不能超过86400

返回


< 200
< {
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiJ9.BrWcVY82dmgdY2yM5l-6yYMgHm-VEyE1T_hAhwvz7x2mGpMfWxKTVsvjPYqfAiO79yhakW_-HzvmmCtBCKeTnw",
    "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImF0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjNiOTVmMzkyLWVhMjQtNDIzZC1iMTlkLWZjMmQ2NDVmOGU4MiJ9.jI-6nNVpPTXIaguefTvW_boV5aq77Plobucukw72TNPd9PNHyQwuTl35Mvj9KS1irTOhbdUbj8yISobYQVBuiQ",
    "token_type": "bearer",
    "expires_in": 86399,
    "jti": "7ee5ade2-3d6b-4581-93b6-fea526337742"
}

调用说明

  • 基于安全考虑,access_token的生命周期较短,因此调用云端 API时可能会返回401错误码,此时说明access_token过期,必须调用该接口让云端重新签发token。
  • 如果调用该接口时就返回401错误码,说明refresh_token也过期了,此时必须调用3.5 使用账号登录接口重新登录让云端重新签发两个token。
  • 每次调用该接口返回里的access_token和refresh_token都是被重新签发的,所以必须更新本地值。

3.13 移动端OAuth


curl -v -X GET \
    -H "Accept: application/json" \
    "https://uaa-openapi.hekr.me/MOAuth?type=QQ&pid=0000000000&clientType=IOS&certificate=&certificateSecret=&uid="

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String GOOGLE, WECHAT, QQ, SINA, FACEBOOK, TWITTER OAuth账号类型
pid 必选 String 厂家唯一ID
clientType 必选 String GENERAL, WEB, ANDROID, IOS, WP 客户端类型
certificate 必选 String 移动端OAuth之后返回的code,或者Twitter返回的access_token 刷新token
certificateSecret 可选 String 当type为TWITTER时,此值为TWITTR返回的access_token_secret值
uid 可选 String 当type是SINA时,此值为SINA返回的uid值 注意和本文档中的其他uid概念区分

返回

如果该OAuth账号还未和主账号(这里指的是通过3.3 使用手机号注册账号3.4 使用邮箱注册账号两个接口注册的账号)绑定,则返回如下格式:


< 200
< {
    "uid": null,
    "pid": "01xxxxxxxxx",
    "oAuthType": "ANDROID",
    "bindToken": "qazxswedcvfrtgbnhyujmkilop",
    "unionId": "xxxxxxx",                               // 用户在各个OAuth平台上的唯一ID
    "nick": "",                                         // 用户在各个OAuth平台上的昵称
    "avatar": "http://xxx.xxx.xxx/xxxx.png"             // 用户在各个OAuth平台上的头像图片链接
}

如果该OAuth账号已经和主账号(这里指的是通过3.3 使用手机号注册账号3.4 使用邮箱注册账号两个接口注册的账号)绑定,则返回如下格式:


< 200
< {
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiJ9.BrWcVY82dmgdY2yM5l-6yYMgHm-VEyE1T_hAhwvz7x2mGpMfWxKTVsvjPYqfAiO79yhakW_-HzvmmCtBCKeTnw",
    "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImF0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjNiOTVmMzkyLWVhMjQtNDIzZC1iMTlkLWZjMmQ2NDVmOGU4MiJ9.jI-6nNVpPTXIaguefTvW_boV5aq77Plobucukw72TNPd9PNHyQwuTl35Mvj9KS1irTOhbdUbj8yISobYQVBuiQ",
    "token_type": "bearer",
    "expires_in": 86399,
    "jti": "7ee5ade2-3d6b-4581-93b6-fea526337742"
}

调用说明

使用该接口时,需要事先在各个OAuth平台上申请OAuth账号,并在氦氪云控制台->第三方账号管理->OAuth账号管理页面里配置。

3.14 将OAuth账号和主账号绑定


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://uaa-openapi.hekr.me/account/bind?token=qazxswedcvfrtgbnhyujmkilop&pid=01xxxxxxxxx"

参数

参数名 是否可选 参数类型 取值范围 说明
token 必选 String 绑定token
pid 必选 String 厂家唯一ID

返回


< 200
< No Content

调用说明

token参数是调用3.13 移动端OAuth接口,当OAuth账号和主账号没绑定时返回里的bindToken。

3.15 解除OAuth账号和主账号的绑定关系


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://uaa-openapi.hekr.me/account/unbind?type=TWITTER&pid=01xxxxxxxxx"

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String GOOGLE, WECHAT, QQ, SINA, FACEBOOK, TWITTER OAuth账号类型

返回


< 200
< No Content

调用说明

无。

3.16 移动端使用微信第三方账号登录


curl -v -X GET \
   -H "Accept: application/json" \
   "https://uaa-openapi.hekr.me/weChatMOAuth?type=QQ&pid=0000000000&clientType=IOS&certificate="

参数

参数名 是否可选 参数类型 取值范围 说明
type 必选 String GOOGLE, WECHAT, QQ, SINA, FACEBOOK, TWITTER OAuth账号类型,目前仅支持WECHAT
pid 必选 String 厂家唯一ID
clientType 必选 String GENERAL, WEB, ANDROID, IOS, WP 客户端类型
certificate 必选 String 移动端OAuth之后返回的code,或者Twitter返回的access_token 刷新token

返回


< 200
    < {
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiJ9.BrWcVY82dmgdY2yM5l-6yYMgHm-VEyE1T_hAhwvz7x2mGpMfWxKTVsvjPYqfAiO79yhakW_-HzvmmCtBCKeTnw",
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImF0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjNiOTVmMzkyLWVhMjQtNDIzZC1iMTlkLWZjMmQ2NDVmOGU4MiJ9.jI-6nNVpPTXIaguefTvW_boV5aq77Plobucukw72TNPd9PNHyQwuTl35Mvj9KS1irTOhbdUbj8yISobYQVBuiQ",
        "token_type": "bearer",
        "expires_in": 86399,
        "jti": "7ee5ade2-3d6b-4581-93b6-fea526337742"
    }

调用说明

接口适用于 移动端使用微信第三方账号登录时使用,如果该微信账号已绑定hekr用户则返回access_token,如果改账号还未绑定hekr账号, 则创建匿名hekr账号和该微信账号进行绑定,并且完成登录返回access_token。

3.17 创建匿名Hekr主账户并与当前登录三方账户绑定


curl -v -X GET \
  -H "Accept: application/json" \
  "https://uaa-openapi.hekr.me/account/createUserAndBind?token=qazxswedcvfrtgbnhyujmkilop&pid=01xxxxxxxxx&type=QQ&clientType=IOS"

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 厂家唯一ID
clientType 必选 String [GENERAL, WEB, ANDROID, IOS, WP] 客户端类型
token 必选 String 绑定token

返回


< 200
    < {
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiJ9.BrWcVY82dmgdY2yM5l-6yYMgHm-VEyE1T_hAhwvz7x2mGpMfWxKTVsvjPYqfAiO79yhakW_-HzvmmCtBCKeTnw",
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ1aWQiOiIxNjE5Mzc1MTc0MiIsImF0aSI6IjdlZTVhZGUyLTNkNmItNDU4MS05M2I2LWZlYTUyNjMzNzc0MiIsImlzb2xhdGlvbiI6IjAwMDAwMDAwMDAwIiwiZXhwIjoxNDYxMjEzODUzLCJ0eXBlIjoiV0VCIiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9VU0VSIl0sImp0aSI6IjNiOTVmMzkyLWVhMjQtNDIzZC1iMTlkLWZjMmQ2NDVmOGU4MiJ9.jI-6nNVpPTXIaguefTvW_boV5aq77Plobucukw72TNPd9PNHyQwuTl35Mvj9KS1irTOhbdUbj8yISobYQVBuiQ",
        "token_type": "bearer",
        "expires_in": 86399,
        "jti": "7ee5ade2-3d6b-4581-93b6-fea526337742"
    }

调用说明

调用改接口时 程序将创建默认的hekr账号和用户登录时的第三方账号进行绑定并且完成登录 token参数是调用3.13 移动端OAuth接口,当OAuth账号和主账号没绑定时返回里的bindToken。

3.18 获取图形验证码


curl -v -X GET \  
     -H "Accept: MediaType.IMAGE_PNG_VALUE" \  
     "https://uaa-openapi.hekr.me/images/getImgCaptcha?rid=12345678901234567" \    

参数

参数名 是否可选 参数类型 取值范围 说明
rid 必选 String 长度大于16,不能含有空格 验证码key

返回


    返回值为图片形式的验证码  

调用说明

rid为获取验证码的标识,可前端自动生成一个唯一码。

3.19 校验图形验证码


curl -v -X POST \  
    -H "Accept: application/json" \  
    -H "Content-Type: application/json" \  
    "https://uaa-openapi.hekr.me/images/checkCaptcha" \  
    -d '{  
        "rid" :"01xXxxxxxxxx",  
        "code":"1qaz"  
    }'  

参数

参数名 是否可选 参数类型 取值范围 说明
rid 必选 String 长度大于16,不能含有空格 验证码key
code 必选 String 验证码的值

返回


< 200  
< {  
   "captchaToken":"51727051945"      // 图形验证码token  
  }

调用说明

返回值为图形验证码的token,在获取短信校验码的时候需要校验该token。

3.20 添加密保问题

用户登录成功后如果还未设置密保问题,提示用户设置密保问题


curl -v -X POST \  
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \  
    -H "Content-Type: application/json" \  
    "https://uaa-openapi.hekr.me/setSecurityQuestion" \  
    -d '{  
        "firstSecurityQues" :"duanyichao",  
        "secondSecurityQues" :"18980909",  
        "thirdSecurityQues" :"12345x"
    }'

参数

参数名 是否可选 参数类型 取值范围 说 明
firstSecurityQues 必选 String 密保问题1
secondSecurityQues 必选 String 密保问题2
thirdSecurityQues 必选 String 密保问题3

返回


< 200
< No Content

调用说明

  • 注意头里面需要JWT Token,所以调用时需要登录。

3.21 验证密保问题

校验用户输入的密保问题是否正确,返回SmsToken


curl -v -X POST \  
    -H "Accept: application/json" \  
    -H "Content-Type: application/json" \  
    "https://uaa-openapi.hekr.me/sms/checkSecurityQuestion" \  
    -d '{  
        "firstSecurityQues" :"duanyichao",  
        "secondSecurityQues" :"18980909",  
        "thirdSecurityQues" :"12345x"  
        "phoneNumber" : "13510786994"
        "pid" : "00000000000"  
    }'

参数

参数名 是否可选 参数类型 取值范围 说 明
firstSecurityQues 必选 String 密保问题1
secondSecurityQues 必选 String 密保问题2
thirdSecurityQues 必选 String 密保问题3
phoneNumber 可选 String 用户账号手机
pid 必选 String 用户pid

返回


< 200
< {
    "phoneNumber" : "138xxxxxxxx",
    "verifyCode" : "",
    "token" : "dd27b62f-ce29-4411-9bc2-d1e3386e176f",
    "expireTime" : 1452073528209
}

调用说明

  • 为了兼容 修改手机号接口,故返回值为SmsToken,但是返回值中verifyCode为空值

3.22 通过密保问题重置密码


curl -v -X POST \  
    -H "Accept: application/json" \  
    -H "Content-Type: application/json" \  
    "https://uaa-openapi.hekr.me/resetPassword?type=security" \  
    -d '{  
        "token" :"dd27b62f-ce29-4411-9bc2-d1e3386e176f",
        "pid" : "00000000000",
        "password":"123456"
    }'

参数

参数名 是否可选 参数类型 取值范围 说 明
token 必选 String 验证密保时返回的token
password 必选 String 用户新密码
pid 必选 String 用户pid

返回


< 200
< No Content

调用说明

  • token值为验证密保问题接口返回的token

3.23 获取用户是否设置了密保问题


curl -v -X GET \
    -H "Accept: application/json" \
    "http://uaa.openapi.hekr.me/isSecurityAccount?phoneNumber=138xxxxxxxx&pid=01698862201"

参数

参数名 是否可选 参数类型 取值范围 说 明
pid 必选 String 用户pid
phoneNumber 必选 String 用户手机号

返回


< 200
< {
 "result": true   
}

3.24 获取萤石云accessToken


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    "http://uaa.openapi.hekr.me/getYsToken?phoneNumber=13621331213"

参数

参数名 是否可选 参数类型 取值范围 说明
phoneNumber 可选 String 萤石云账户手机号

返回


< 200
< {
    "accessToken": "at.14e5e229f13b45cda399b95832842b02-40f3f6d06efb-fba3a116",
    "userId": "a4fdea416b"
}

调用说明

  • 如果用户第一次开通服务调用接口,则手机号必填。如已调用过该接口,则手机号可以不填

错误码表

错误码 提示信息 中文释义 可能造成的原因
400016 Rate limit exceeded 调用接口频率过快受限 调用接口频次过频繁
400017 Times limit exceeded 调用次数受限 调用接口次数超过限制
3200000 Success 调用成功 调用成功
3400000 Error 未知错误 该行下面的以3400开头的错误码需要单独处理
3400001 Phone number invalid 手机号无效 手机号码无效
3400002 Verify code error 验证code错误 验证code错误
3400003 Verify code expire 验证code过期 验证code过期
3400004 Verify code send too fast 发送code过快 发送code过快
3400005 Verify code send too many 发送code次数过多 发送code次数过多
3400006 Invalid request type 无效的请求类型 验证请求type填错了
3400007 Invalid old password 无效的旧密码 旧密码错误
3400008 User has been registered 用户已注册 用户已经注册
3400009 Your account has not been verified 账户尚未认证 用户尚未验证
3400010 Could not authenticate user. Verify the user name and password, and try again 用户名或密码错误 用户名或密码错误
3400011 User does not exist 用户不存在 用户不存在
3400012 Invalid email token 无效的邮件token 无效的邮件token
3400013 Your account has already been verified 账户已认证 账户已认证
3400014 Your account has already been linked to a {0} account 账户已经关联了某个三方账号 一个账户只能绑定一种三方账户,例如一个账户只能绑定一个微博
3400015 Invalid token 无效的token 使用了不合法或者过期的token
3400016 Account can not upgrade 账户无法升级为主账户 该三方账户无法升级为主账户
3400017 Invalid captcha token 无效的验证码token 提交了错误的验证码token
3400018 {0} 用户密保问题校验失败 用户还未设置密保问题或用户密保校验失败
3400019 Invalid token {0} 无效的token 在一些需要token的校验的方法中 用户的提供的token无效
3400020 Invalid captcha params 无效的验证码参数 用户获取图片校验码参数错误
3400021 captch code can not match 校验码不能匹配 用户的输入的图形校验码不能匹配
3400022 request failure {0} 接口调用失败 云端调用萤石云接口失败或者萤石云返回的错误信息异常
3400023 not open ys service 未开通萤石云服务 该用户还没有开通萤石云服务(获取accessToken前需先开通萤石云服务)
3400024 Phone number invalid 手机号无效 手机号码无效
3400025 oauth not cofig 厂家未配置对应的三方登录配置信息 果app端开启了三方登录,但是console上未进行配置相应信息
3500000 Internal error ({0}) 内部错误 服务内部错误

4. 用户API

服务地址

域名:端口 功能 协议 数据安全级别 服务区域
user-openapi.hekr.me:80 云端用户API HTTP 非SSL 全球

错误返回方式说明

调用接口成功返回20X,如有返回内容会在body中给出,没有返回内容body将为空,仅有HTTP头。

调用接口失败返回40X或500,错误信息会在body中给出。

如果返回的HTTP Code是401,请检查请求头是否正确。

4.1 设备管理

4.1.1 绑定设备


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device" \
    -d '{
        "devTid" : "ESP_XXXX",
        "deviceName" : "我的设备1号",
        "bindKey" : "xxxxxx",
        "desc" : "我的第一台hekr智能设备"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
bindKey 必选 String 绑定码
deviceName 可选 String 长度[1,128] 设备名称
desc 可选 String 长度[1,128] 设备描述

返回


< 201
< {
    "deviceName" : "我的设备1号",
    "tokenType" : 2,
    "binType" : null,
    "devTid" : "ESP_XXXX",
    "serviceHost" : null,
    "ctrlKey" : "6ef3c2cb87d341f9a83ce12",
    "logo" : "http://app.hekr.me/res/img/icon/icon_33@3x.png",
    "currentLoginTime" : 1459426566661,
    "ownerUid" : "20039941211",
    "ssid" : null,
    "granted" : false,
    "eventRuleMap" : None,
    "workModeType" : "JSON_CTRL",
    "timerMap" : null,
    "wanIp" : "127.0.0.1",
    "lastLoginTime" : 1454294875463,
    "connectIp" : "192.168.1.2",
    "productPublicKey" : "xxxxxx",
    "androidH5Page" : "",
    "online" : true,
    "setSchedulerTask" : false,
    "lastUpdateTime" : null,
    "servicePort" : 0,
    "firstLoginTime" : 1454294875463,
    "folderId" : "0",
    "sdkVer" : null,
    "desc" : "我的第一台hekr智能设备",
    "binVersion" : null,
    "cid" : "test-cid",
    "devShareNum" : 0,
    "iosH5Page" : "",
    "ctrlKey" : "xxxxxxxxx",
    "bindKey" : "xxxxxxxxx",
    "lastHeartbeat" : 1454294875463
}

4.1.2 列举设备列表

不指定分页信息默认最多只返回20条记录。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device?devTid=tid1234,tid22,tid55&folderId=fid1234&groupId=gid1234&page=0&size=10"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 可选 String (废弃,请使用ctrlKey)设备devTid,多个使用逗号分隔
ctrlKey 可选 String 设备唯一ID,多个使用逗号分隔
folderId 可选 String 目录ID,按其值筛选
groupId 可选 String 群ID,按其值筛选
granted 可选 Boolean 是否授权,按其值筛选
setSchedulerTask 可选 Boolean 是否设置了预约,按其值筛选
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回

当调用者为该设备属主时,bindKey与ctrlKey皆返回,否则只返回ctrlKey。


< 200
< [
    {
        "deviceName" : "hekr_device",                   // 设备绑定指定名字
        "tokenType" : 2,                                // token类型 2:动态token
        "mid": "01650ca78f33",                          // 产品ID
        "binType" : null,                               // 固件类型
        "devTid" : "tid2",                              // 设备ID
        "serviceHost" : null,                           // 连接服务器host
        // 设备logo地址
        "logo" : "http://7xl8jv.com2.z0.glb.qiniucdn.com/1455783857385iconfont-hekriconshebeitaideng18.png",
        "androidH5Page" : "",                           // 安卓H5页面地址
        "iosH5Page" : "",                               // ios H5页面地址
        "devShareNum" : 0,                              // 设备当前授权人数
        "currentLoginTime" : 1458732550117,             // 最新登录时间时间戳
        "ownerUid" : "20039941211",                     // 设备属主UID
        "ssid" : null,                                  // 连接WIFI ssid
        "granted" : false,                              // 是否授权给了其他人
        "productPublicKey" : "xxxxxx",                  // 设备产品公共密钥
        "workModeType" : "JSON_CTRL",                   // 设备工作模式 JSON_CTRL(JSON主控)/JSON_TRANSPARENT(JSON透传)
        "timerMap" : null,                              // 定时预约任务
        "gis": {                                        // 地理位置信息
              "ip": {
                "country": "中国",
                "province": "北京市",
                "city": "北京市",
                "citycode": null,
                "district": null,
                "adcode": null,
                "township": null,
                "towncode": null,
                "street": null,
                "ip": "61.148.244.191"
              },
              "geo": null,
              "bs": null,
              "bsOther": null
        },
        "wanIp" : "127.0.0.1",                          // 公网IP
        "lanIp": "192.168.1.245",                       // 局域网IP
        "lanIpUpdateDate": 1454294875463,               // 局域网IP上报时间
        "lastLoginTime" : 1454294875463,                // 上一次登录时间
        "connectIp" : "192.168.1.2",                    // 连接服务器IP
        "online" : true,                                // 是否在线
        "setSchedulerTask" : false,                     // 是否设置了预约任务
        "lastUpdateTime" : null,                        // 上次更新固件时间
        "servicePort" : 0,                              // 服务端口
        "firstLoginTime" : 1454294875463,               // 首次登录时间时间戳
        "folderId" : "0",                               // 设备所在文件夹ID
        "sdkVer" : null,                                // sdk版本
        "desc" : "",                                    // 设备描述
        "binVersion" : null,                            // 固件版本
        "cid" : "test-cid",                             // 品类ID
        "ctrlKey" : "8971a6b62c0649f6bdec99c",          // 设备控制码
        "bindKey" : "20005c97f94aff9d7ff870a941e",      // 设备绑定码
        "lastHeartbeat" : 1454294875463                 // 上次心跳时间时间戳
        "groupInfo" : [
            {
                "groupId" : "gid1234",                  // 设备所在群组信息
                "groupName" : "联动小组001",
                "deviceList": [
                  {
                    "devTid": "xketuo2z5c",
                    "ctrlKey": "704973e8d3a3424ebcc"
                  }
                ],
                "createTime": 1462343277675,
                "updateTime": null,
                "groupMid": "01d836a3cb28"
            },
            ...
        ]
        "androidH5Page": "https://xxxx/index.html",      // 安卓的H5控制页面
        "iosH5Page": "https://xxxx/index.html",          // IOS的H5控制页面
        "weChatH5Page": "https://xxxx/index.html",       // 微信的H5控制页面
        "iosPageZipURL" : "https://xxxx/xxxx.zip",       // IOS的H5控制页的zip包
        "androidPageZipURL" : "https://xxxx/xxxx.zip",   // 安卓的H5控制页的zip包
        "weChatPageZipURL": "https://xxxx/xxxx.zip",     // 微信的H5控制页的zip包
        "categoryName": {
          "zh_CN": "xxxx",                               //品类中文名称
          "en_US": "xxxx"                                //品类英文名称
        },
        "productName": {
          "zh_CN": "xxxx",                               //产品中文名称
          "en_US": "xxxx"                                //产品英文名称
        },
        "productBand" : "xxx"                            // 设备品牌
        "model" : "xxxx"                                 // 产商设置的设备型号
        "cidName" : "xxx"                                // 具体的品类名称
        "bindPid": "01015362077",                        // 当前绑定人pid
        "subscribe": true,                               // 是否为产品订阅企业用户绑定
        "subDevices": [                                  // 设备下子设备列表(网关设备独有)
            {
                "devTid": "0003b1b000000000", // 子设备ID
                "mid": "01b49090fe42",  // 子产品ID
                "connectType": "linptech",  // 连接方式
                "online": true,   //是否在线
                "binVer": "2.1.0", //
                "devName": "",
                "devModel": "",
                "manufacturerName": "Linptech",
                "description": "scene button-3",
                "cidName": "家居家装/情景开关",
                "categoryName": {
                  "zh_CN": "家居家装/情景开关",
                  "en_US": "Misc/Scene Switch"
                },
                "productName": {
                  "en_US": "Scene Button",
                  "zh_CN": "三键情景按钮"
                },
                "logo": "https://allinone-ufile.hekr.me/product/60e182aa-474e-49ae-a33a-3fd231dd9e6d.png",
                "androidH5Page": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/index.html",
                "iosH5Page": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/index.html",
                "iosPageZipURL": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/cloud-house-scene-button.zip",
                "androidPageZipURL": "https://allinone-ufile.hekr.me/h5page/e9ae2147-ca32-41f6-8d05-283220e370c5/cloud-house-scene-button.zip",
                "productPublicKey": "k0wfHypbzGlO984xLmtZMCNI+tAqIZKOmM2vxb+xLOVoZqfuJ4ZjTi9ZBAcuRiV1Qp",
                "folderId": "0",
                "folderName": "root",
                "parentDevTid": "7f992582caec4b8587fb3ba4d23b2d46",
                "parentCtrlKey": "042a9c2a96c647949d49c8b0e9f0b7fd",
                "devType": "SUB"
            },
            ......
        ]
    },
    ...
  ]

4.1.2.1 列举指定目录下设备列表


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{folderId}?page=0&size=10"

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 必选 String 目录ID
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


>200
>[
  {
    "devTid": "d0364654e8b",
    "devType": "GATEWAY",
    "mid": "xxx",
    "cid": "694aec7",
    "ctrlKey": "xxx",
    "bindKey": "xxx",
    "workModeType": "JSON_CTRL",
    "ssid": "NULL",
    "mac": "d0364654d788e8b",
    "gis": {
      "country": null
    },
    "wanIp": "xxx",
    "country": null,
    "province": null,
    "city": null,
    "binType": "A",
    "finger": "c9e4f2f8-33bb-4fc6-baa8-c31ab2",
    "lastHeartbeat": 1488884595573,
    "ownerUid": "xxx",
    "status": "ONLINE",
    "granted": true,
    "setSchedulerTask": true,
    "forceBind": false,
    "devShareNum": 3,
    "maxDevShareNum": 0,
    "bindPid": null,
    "subscribe": false,
    "timerMap": {
      "1": {
        "uid": "xxx",
        "taskId": 1,
        "taskName": "新加预约",
        "taskKey": null,
        "enable": true,
        "code": {
          "cmdId": 2,
          "sw": 0
        },
        "desc": "备注",
        "timeZoneOffset": 480,
        "count": 1,
        "timerTaskStatus": "SCHEDULING",
        "createTime": 1488872928681,
        "updateTime": 1488876565571,
        "subDevTid": "00124b000",
        "schedulerType": "LOOP",
        "cronExpr": "0 52 16 ? * TUE,WED,SUN *",
        "triggerDateTime": null,
        "triggerTime": "16:52:00",
        "repeatList": [
          "TUE",
        ]
      }
    },
    "eventRuleMap": null,
    "deviceBindingStatus": {
      "uid": "xxx",
      "bindTime": 1488793564998,
      "expire": 33024793564998,
      "desc": ""
    },
    "deviceAuthorizationStatuses": [
      {
        "grantee": "xxx",
        "grantTime": 1488871803948,
        "updateTime": null,
        "expire": 3636355450948,
        "instructionExpire": null,
        "mode": "ALL",
        "enableIFTTT": true,
        "enableScheduler": true,
        "desc": "",
        "subDevTids": [
          "00124b000"
        ]
      }
    ],
    "deviceName": "智能网关",
    "desc": "",
    "folderId": "0",
    "productPublicKey": "xxx",
    "logo": "",
    "androidH5Page": "",
    "iosH5Page": "",
    "productBand": "新歌",
    "model": "HEKR-01",
    "cidName": "家居家装/智能网关",
    "categoryName": {
      "zh_CN": "家居家装/智能网关",
      "en_US": "Misc/Smart Gateway"
    },
    "productName": {
      "en_US": "Smart Gateway",
      "zh_CN": "智能网关"
    },
    "folderName": "root",
    "online": true,
    "groupInfo": [],
    "bindResultCode": null,
    "bindResultMsg": null,
    "subDevices": [
      {
        "devTid": "00124b000",
        "mid": "xxx",
        "connectType": "zigbee_zha",
        "online": true,
        "devName": "",
        "devModel": "42",
        "manufacturerName": "Hongsi",
        "description": "WP sensor",
        "cidName": "家居家装/传感器",
        "categoryName": {
          "zh_CN": "家居家装/传感器",
          "en_US": "Misc/Sensor"
        },
        "productName": {
          "en_US": "Flooding Detection",
          "zh_CN": "水浸传感器"
        },
        "logo": "",
        "androidH5Page": "",
        "iosH5Page": "",
        "folderId": "0",
        "folderName": "root",
        "parentDevTid": "d0364654d3d",
        "parentCtrlKey": "82bfb8e1",
        "devType": "SUB"
      }
    ]
  }
]

4.1.2.2 列举当前用户下指定设备下所有子设备


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/subDevList?devTid=tid1234&ctrlKey=fidxxxxxxxxx&subDevTid=gid1234&page=0&size=10"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
subDevTid 可选 String 子设备ID
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


>200
>[
  {
    "devTid": "gid1234",
    "mid": "xxx",
    "connectType": "zigbee_zha",
    "online": true,
    "binVer": "3.0.10",
    "devName": "",
    "devModel": "42",
    "manufacturerName": "Heiman",
    "description": "WP sensor",
    "cidName": "家居家装/传感器",
    "categoryName": {
      "zh_CN": "家居家装/传感器",
      "en_US": "Misc/Sensor"
    },
    "productName": {
      "en_US": "Flooding Detection",
      "zh_CN": "水浸传感器"
    },
    "logo": "",
    "androidH5Page": "",
    "iosH5Page": "",
    "iosPageZipURL": "",
    "androidPageZipURL": "",
    "productPublicKey": "",
    "folderId": "0",
    "folderName": "root",
    "parentDevTid": "d0364654d3d8bd",
    "parentCtrlKey": "82bfb8e19f1be",
    "devType": "SUB"
  }
  .....
 ]

4.1.3 删除设备

注意,该接口会彻底解绑设备,切改接口不适用于子设备


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}?bindKey={bindKey}&randomKey={randomKey}"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
bindKey 必选 String 绑定码
randomToken 可选 String 删除设备令牌

返回

  • 第一步(设备在场景和联动中有使用)
< 202
< {
    "randomToken":"1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      },
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }
  • 第二步(用户确认删除)
> 204
> No Content

4.1.3.1 删除子设备

删除子设备前,确认子设备在场景和联动中的使用情况。 删除子设备走TCP协议

curl -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/delSubDevice"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 网关设备tid
ctrlKey 必选 String 网关设备ctrlKey
subDevTid 必选 String 要删除的子设备的tid

返回

  • 如果没有返回值则返回null(这块不太合适随后再改改 没有返回值返回 204)
< 200
< {
    "randomKey":"1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      },
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }

4.1.4 更改设备名称/描述


curl -v -X PATCH \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}" \
    -d '{
        "deviceName" : "新的设备1",
        "desc" : "新的设备描述",
        "ctrlKey" : "xxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
deviceName 可选 String 长度[1, 128] 设备名称
desc 可选 String 长度[1, 128] 设备描述

返回


< 204
< No Content

4.1.4.1 更改子设备名称和描述


curl -v -X PATCH \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/device/{devTid}/{subDevTid}" \
    -d '{
        "deviceName" : "新的子设备名称",
        "desc" : "新的子设备描述",
        "ctrlKey" : "xxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
subDevTid 必选 String 子设备ID
deviceName 可选 String 设备名称
desc 可选 String 设备描述

返回


< 204
< No Content

4.1.5 获取当前局域网内所有设备绑定状态


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/deviceBindStatus"
    -d '[{
          "bindKey" : "xxxxx",
          "devTid" : "ESP_test"
      },
      ...
    ]'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
bindKey 必选 String 绑定码

返回

只返回正确的devTid/bindKey对应的设备绑定状态,所以返回里的元素数量会少于提交里的元素数量。


< 200
< [
    {
        "devTid": "test-2016-4-18-1",                   // 设备ID
        "bindToUser": true,                             // 是否已被用户绑定
        "forceBind": false,                             // 是否可以被强制绑定
        "deviceName": "",                               // 设备名字
        // logo url
        "logo": "http://app.hekr.me/res/img/icon/icon_33@3x.png",
        "cid": "fc1345a42510",                          // 设备品类
        "cidName": "厨房电器/电饭煲",                     // 设备品类名称
        "productBand": "HEKR"                           // 设备品牌
    },
    ...
]

4.1.6 批量查询设备状态

被查询设备可以不属于同一个型号。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/deviceStatusQuery" \
    -d '[{
          "devTid" : "ESP_X01",                         // 设备ID
          // 控制码
          "ctrlKey" : "8971a6b62c0649f6bdc99c"
      },
      {
          "devTid" : "ESP_X02",
          "ctrlKey" : "4571bcb62c0909f6d43c909"
      },
      ...
    ]'

参数

期望查询的设备列表,最少1个,最多512个设备。

返回


> 200
> [
    {
        "devTid": "ESP_X01",
        // 该设备型号的设备参数
        "status": {
            "power": {
                "currentValue": 0,
                "lastValue": 1,
                "reportTimestamp": 1458724895439
        }                                     
    },
    {
        "devTid" : "ESP_X02",
        "status": {
            "light": {
                "currentValue": null,
                "lastValue": 24,
                "reportTimestamp": 1458724895439
            }
        }
    },
    ...
]

4.1.7 批量控制设备

被控制设备必须属于同一个型号。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/deviceControl" \
    -d '{
          "deviceList" : [
              {
                  "devTid" : "ESP_X01",                 // 设备ID
                  // 控制码
                  "ctrlKey" : "8971a6b62c0649f699c"
              },
              {
                  "devTid" : "ESP_X02",
                  "ctrlKey" : "4571bcb62c1949f643c909"
              },
              ...
          ],
          "data" : {
              "raw" : "48EA80DE"                        // JSON透传
          }
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
deviceList 必选 List 列表长度[1, 512] 期望控制的设备列表,最少1个,最多512个设备
data 必选 Map 指令内容,注意使用JSON透传和JSON主控时,data的格式不一样,参照2.5.1和2.5.2里data的格式

返回


> 200
> no content

注意该接口没有执行结果的具体返回,请使用4.1.6 批量查询设备状态接口查询最新的设备状态来确定控制是否成功。

4.1.8 返回非强绑设备属主联系信息

该接口用于用户由于尝试绑定 有归属且非强绑类型的 设备失败之后查询当前设备的属主信息的接口,注意该接口返回的属主信息经过了简单的加密处理


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/queryOwner" \
    -d '{
        "devTid": "xxxxx",
        "bindKey" : "xxxxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
bindKey 必选 String 绑定码

返回


> 200
> {
  "message": "133****9180"
}

4.1.9 返回设备事件记录


curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/queryHistory?devTid=xxx&ctrlKey=xxx&actions=xxx&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
actions 必选 String 多个用逗号“,”分开 执行指令
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


> 200
> {
  "content": [
    {
      "objectId": "58b0faf5e4b07bd40b653fb1",
      "finger": "2d25d5dad728",
      "sessionId": "4fc5adfe-8ced-4978-8964-56c9278",
      "action": "appSend",
      "devTid": "xxxxxxxxx",
      "ctrlKey": "xxxxxxxxxxx",
      "msgId": 10,
      "timestamp": 1487993589681,
      "pid": "00000000000",
      "mid": "xxxxxxxx",
      "cid": null,
      "rawRequest": "{xxxxx}",
      "rawResult": null,
      "request": {
        "msgId": 10,
        "action": "appSend",
        "params": {
          "raw": "xxxxxxxxxxxx"
          }
        }
      },
      "result": {
        "msgId": 10,
        "action": "appSendResp",
        "code": 200,
        "desc": null,
        "params": {
          "devTid": null,
          "ctrlKey": null,
          "appTid": null,
          "subDevTid": null,
          "data": null
        }
      }
    }
   ],
  "last": false,
  "totalPages": 2,
  "totalElements": 40,
  "sort": null,
  "first": true,
  "numberOfElements": 20,
  "size": 20,
  "number": 0
}

4.1.10 获取PINCode

该接口用于配网时获取PINCode


curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/getPINCode?ssid=1111"

参数

参数名 是否可选 参数类型 取值范围 说明
ssid 必选 String 当前连接路由器的ssid

返回


> 200
> {
  "PINCode" : "sS16sg"
}

4.1.11 获取当前局域网设备配网详情

该接口用于配网时查看当前局域网内设备配网进度


curl -v -X GET \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  "https://user-openapi.hekr.me/getNewDeviceList?pinCode=xx&ssid=xxx"

参数

参数名 是否可选 参数类型 取值范围 说明
ssid 必选 String 当前连接路由器的ssid
pinCode 必选 String 当前配网使用的pinCode

返回


> 200
> [
    {   
        // 部分 kv 释义请参考 4.1.2
        "deviceName": null,
        "cidName": "\u751f\u6d3b\u7535\u5668/\u706f",
        "binType": null,
        "bindResultCode": 0,                            // 绑定(配网)是否成功 0:成功 1:失败
        "devTid": "zyut4fxrbn",
        "serviceHost": null,
        "ctrlKey": "2ef0a36d9583413daf6",
        "logo": "http://7xsk3u.com1.z0.glb.clouddn.com/1464157649632lamp2.png",
        "iosPageZipURL": "",
        "currentLoginTime": 1470904732349,
        "productBand": "a",
        "groupInfo": [],
        "ssid": null,
        "granted": false,
        "eventRuleMap": null,
        "androidPageZipURL": "",
        "forceBind": true,
        "workModeType": "JSON_TRANSPARENT",
        "bindResultMsg": "18518018418",                 // 绑定结果信息  
        "finger": "d4e67da1-a06d-4708-90d7-0edef855b611",
        "timerMap": null,
        "wanIp": "182.50.118.126",
        "lastLoginTime": 1470904732349,
        "bindKey": "ced854a79c4a4ed519ba",
        "status": "ONLINE",
        "categoryName": {
            "en_US": "EA/Lamp",
            "zh_CN": "\u751f\u6d3b\u7535\u5668/\u706f"
        },
        "maxDevShareNum": 0,
        "ownerUid": "13805966378",
        "deviceAuthorizationStatuses": null,
        "androidH5Page": "",
        "online": true,
        "setSchedulerTask": false,
        "servicePort": 0,
        "deviceBindingStatus": {
            "bindTime": 1470904732372,
            "expire": -1,
            "uid": "13805966378",
            "desc": ""
        },
        "mac": null,
        "firstLoginTime": 1470904732349,
        "folderId": null,
        "sdkVer": null,
        "productName": {
            "en_US": "",
            "zh_CN": ""
        },
        "desc": null,
        "productPublicKey": "k0wfHypbzGlO9FdoxF",
        "cid": "b7f9a8ecabef",
        "devShareNum": 0,
        "iosH5Page": "",
        "folderName": "",
        "model": "pass_through",
        "binVersion": null,
        "lastHeartbeat": 1470904732349
    }
]

4.1.12 列举设备上报日志


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/getDeviceLog?devTid=tid1234&ctrlKey=xxx&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
startTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间

返回


> 200
> [
      {
         "logContent":"xxxxxxx",
         "time":"xxxxxxx"
      },
      ....
 ]

4.1.13 列举APP上报日志


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/getAppLog?appTid=xxxxxx&action=tid1234&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
appTid 必选 String appID
action 必选 String 指令
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


> 200
> [
   {
       "msgId":"234",
       "action":"appsend",
       "time":"xxxxxx",
       "devTid":"EX-xxxxxx",
       "log":"xxxxxxx"
   },
   ......
]

4.1.14 获取设备上下线记录


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/queryDevLoginHistory?devTid=xxxxxx&ctrlKey=tid1234&type=2016-01-01T09:45:00.000+0800&startTime=2017-01-01T09:45:00.000+0800&endTime=xxx&page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
type 必选 String 类型
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


> 200
> {
    "sort" : null,
    "numberOfElements" : 1,
    "last" : true,
    "number" : 0,
    "content" : [
        {
            "time" : 1457946475120,
            "type" : "xxxxxxx"
        },
        ...
    ],
    "totalPages" : 1,
    "first" : true,
    "totalElements" : n,
    "size" : 20
}

4.1.15 返回设备上报帧,下发帧记录


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/devSendAndRecv?devTid=xxxxxx&ctrlKey=tid1234&type=xxx&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码
type 必选 String 类型
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


{
  "totalPages": 207,
  "totalElements": 207,
  "deviceHistoryList": [
    {
      "time": 1487994014288,
      "type": "devSend",
      "data": {
        "raw": "xxxxxxxxxx"
      }
    },
    ....
  ]
}

4.1.16 查询设备快照

该接口返回当前用户下所有设备的快照信息


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/devSnapshot?page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20
devTid 可选 String 设备ID(如果有多个使用英文半角逗号分开)

调用说明

  • 多个devTid使用英文半角逗号分割,
  • 支持模糊查询
  • 当subDevTid参数不为空时代表该快照为子设备快照

返回

返回该设备快照信息,不指定分页参数默认返回20条


< 200
< [
    {
        "devStatus": "online", // 设备状态,
        "devTid": "c520ea53d373",
        "ctrlKey": "78cefdc033dd35a",
        "subDevTid":null
        "snapshot": {   
                "power" : {             // 设备上报参数
                    "currentValue" : 0, // 当前值
                    "lastValue" : 0,    // 上次值
                    "reportTimestamp" : NumberLong("1479709915369") // 上报时间
                },
        ...
        },
        "lastOprationTime": 0 // 最后操作时间
    },
    {
        "devStatus": "offline",
        "devTid": "c520ea64d373",
        "ctrlKey": "78cefdc01dd35a",
        "subDevTid":"0003b1b000000000"
        "snapshot": {
                "channel_1" : {
                        "currentValue" : 1,
                        "lastValue" : 2,
                        "reportTimestamp" : NumberLong("1479802058250")
                },
                ...

        },
        "lastOprationTime": 1472020160281
    },
    ...
]

4.1.17 返回第三方设备列表

该接口返回当前用户下第三方设备列表


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/thirdPartDevice"

返回

返回当前用户下第三方设备列表,不指定分页参数默认返回20条


< 200
< [
    {
      "deviceName": "小白",
      "logo": "",
      "devType": "THIRD",
      "online": true,
      "robotSN": "1121601000101"
    },
    ...
]

4.2 目录管理

4.2.1 添加目录

一个用户最多只能建立128个目录。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/folder" \
    -d '{
        "folderName" : "xxxxx"    
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
folderName 必选 String 长度[1, 128] 目录名字

返回


< 201
< {
    "folderId" : "xxxx",
    "folderName" : "{folderName}",
    "devTidList" : []
}

4.2.2 列举目录


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/folder?folderId=xxx,xxx1&page=1&size=1"

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 可选 String 目录ID,多个逗号分隔
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


< 200
< [
    {
        "folderId" : "xxxx",
        "folderName" : "xxx",
        "devTidList" : ["xxx", "xxx"]
    },
    ...
  ]

4.2.3 修改目录名称


curl -v -X PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/folder/{folderId}" \
    -d '{
        "newFolderName" : "xxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 必选 String 目录ID
newFolderName 必选 String 长度[1, 128] 新目录名字

返回


< 204
< No Content

4.2.4 删除目录

即使目录下有设备也可以删除,后续动作是把这些设备挪到根目录下。


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/folder/{folderId}"

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 可选 String 目录ID,如果不指定folderId参数,会删除全部自定义目录

返回


< 204
< No Content

4.2.5 将设备挪到指定目录

除了根目录,一个目录下最多可以放置512个设备。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/folder/{folderId}" \
    -d '{
        "devTid" : "xxxxxx",
        "ctrlkey" : "xxxx"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 必选 String 目录ID
ctrlKey 必选 String 设备控制码
devTid 必选 String 设备ID

返回


< 201
< No Content

4.2.6 将设备从目录挪到根目录下


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/folder/{folderId}/{devTid}?ctrlKey=xxxx"

参数

参数名 是否可选 参数类型 取值范围 说明
folderId 必选 String 目录ID
devTid 必选 String 设备ID
ctrlKey 必选 String 设备控制码

返回


< 204
< No Content

4.3 授权管理

每个设备授权给多少人有最大限制,由设备具体型号决定,这个值可以在氦氪云控制台->产品管理->参数信息->其他参数信息页面中设置。

4.3.1 正向创建授权

所谓正向,是指授权用户直接拿到被授权用户的用户ID,只需要一次调用就能创建授权关系。

4.3.1.1 整体授权设备

将设备的所有功能(除了绑定/解绑)授权给某用户。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization" \
    -d '{
        "grantor" : "uid1",
        "grantee" : "uid2",
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxxxxx"
        "expire" : 300,
        "mode" : "ALL",
        "desc" : "xxxx"
        "enableScheduler" : true,
        "enableIFTTT" : true
    }'
4.3.1.2 部分授权设备

将设备的部分功能(绑定/解绑默认不能授权)授权给某用户。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization" \
    -d '{
        "grantor" : "uid1",
        "grantee" : "uid2",
        "ctrlKey" : "xxx",
        "devTid" : "ESP_xxx",
        "expire" : 300,
        "instructionExpire" : {
            "brush" : 200,
            "power-off" : 100,
            ...
        },
        "mode" : "PARTIAL",
        "desc" : "xxxxx",
        "enableScheduler" : true,
        "enableIFTTT" : true
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
grantor 必选 String 授权用户ID
grantee 必选 String 被授权用户ID
ctrlKey 必选 String 控制码
devTid 必选 String 设备ID
expire 必选 Long [300, ?]秒 设备授权失效时间
mode 必选 String ALL, PARTIAL 设备授权权限模式
instructionExpire 可选 Map 具体细化的指令失效时间,当mode为PARTIAL时必选
desc 可选 String 长度[0, 128] 授权说明
enableScheduler 可选 Boolean 是否授予预约任务的权限,默认为true
enableIFTTT 可选 Boolean 是否授予增/删/改IFTTT规则的权限,默认为true

返回


< 201
< 同4.3.5返回

4.3.2 反向授权创建

所谓反向,是指被授权用户拿到被授权设备ID,请求授权用户创建授权关系。流程有下面4步:

  1. 授权用户创建授权二维码
  2. 被授权用户扫描该二维码
  3. 授权用户收到被授权者的请求
  4. 授权用户同意
  5. 授权用户拒绝

4和5是的关系,以上4个步骤,依次对应下面的4命令及返回:

1. 创建授权二维码URL

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization/reverse/authUrl" \
    -d '{
        "grantor" : "uid1",
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxxxxx"
        "expire" : 300,
        "mode" : "ALL",
        "desc" : "xxxx"
        "enableScheduler" : true,
        "enableIFTTT" : true
    }'

< 201
< {
    "reverseAuthorizationTemplateId": "8777bf2cf9d642deb8c2c20f2dc9feda" //该id有效时间为一个小时
  }
2. 被授权用户扫描二维码

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/authorization/reverse/register?reverseTemplateId={reverseAuthorizationTemplateId}"

注意,这里reverseAuthorizationTemplateId与上一条请求返回的一致。


< 201
< No Content

调用该接口,授权用户会收到一条请求。

3. 授权用户收到被授权者的请求

通过该接口可以实现: 1. 直接通过reverseRegisterId参数精确查询到指定的反向授权请求。 2. 不指定devTid参数查询该用户所有设备收到的反向授权请求。 3. 指定devTid参数返回该设备的反向授权请求。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization/reverse/register?devTid=xxx&page=xxx&size=xxx&reverseRegisterId=xxx"

返回


< 200
< [
    {
        "registerId" : "xxxx",
        "grantor" : "xxx",
        "grantee" : "xxx",
        "devTid" : "ESP_tidxxx",
        "expire" : 300,
        "mode" : "ALL",
        "desc" : "xxxx"
        "enableScheduler" : true,
        "enableIFTTT" : true
    },
    ...
  ]

注意,返回是个数组,因为有可能同时有多个被授权者发起请求,或者一个被授权者多次发起请求。

4. 授权用户同意

授权用户同意其中一个请求。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization/reverse?devTid=xxx&ctrlKey=xxxx&reverseRegisterId=xxx" \

返回


< 201
< 同4.3.5返回
5. 授权用户拒绝

授权用户拒绝其中一个请求。


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization/reverse/register/{reverseTemplateId}?devTid=xxx&uid=xxx&ctrlKey=xxx&"

返回


< 201
< 同4.3.5返回

4.3.3 编辑授权

提交时必须包含全部的授权信息,即只支持全量提交。


curl -v -x PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization" \
    -d '{
        ...
        // 同4.3.1完整授权对象
    }'

返回


< 204
< No Content

4.3.4 取消授权

调用该函数会删除某个设备上授权者对被授权者的完整的授权关系,如果仅需要删除具体某个指令的授权关系,请使用4.3.3。
第一步:校验改设备是否在用户设置的场景或连动中使用,如果有使用返回相关的scene、ifttt和randomToken
第二步:用户确认后再次调用取消授权接口(带入randomToken标识第二步操作)执行授权移除操作

curl -v -x DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization?grantor=xxx&ctrlKey=xxx&grantee=123,456,789&devTid=ESP_xxx&randomToken=1qazxsw23edcvfr4"

参数

参数名 是否可选 参数类型 取值范围 说明
grantor 必选 String 授权用户uid
grantee 可选 String 被授权用户uid,多个使用逗号分隔;当不提交该参数时,表示授权者删除该设备上对所有被授权者的授权关系
ctrlKey 必选 String 控制码
devTid 必选 String 设备ID
randomToken 可选 String 确认取消授权的Token

返回

  • 第一步(设备在场景和联动中有使用)
< 202
< {
    "randomToken":"1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      },
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }
  • 第二步(用户确认删除)
> 204
> No Content

4.3.5 列举授权信息

该接口授权者和被授权者皆可调用,其中被授权者调用时,grantee 参数不得为空,且其值为当前调用用户的uid。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization?grantor=xxx&ctrlKey=xxx&devTid=ESP_xxx&grantee=yyy,xxx,123"

参数

参数名 是否可选 参数类型 取值范围 说明
grantor 必选 String 授权用户uid
grantee 可选 String 被授权用户uid,多个使用逗号分隔;当不提交该参数时,表示列举该设备上所有的授权关系;被授权者调用时不得为空,且其值为当前调用用户的uid
ctrlKey 必选 String 控制码
devTid 必选 String 设备ID

返回


< 200
< [
    {
        "grantorName" : "小李",
        "grantee" : "",
        "granteeName" : "小明",
        "grantTime" : 1460219502699,
        "updateTime" : 1460219502699,
        "expire" : 3600,
        "instructionExpire" : null,
        "enableIFTTT" : true,
        "enableSchedule" : true,
        "desc" : "test"
    },
    ...
]

4.3.6 列举授权历史记录

该接口授权者可调用,拉取曾经设备授权的历史记录。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/authorization/history?devTid=xxxx&ctrlKey=xxx&passAuth=true&page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 可选 String 设备ID
ctrlKey 可选 String 控制码
passAuth 可选 Boolean 是否同意授权,是拉取只有同意授权的记录,否拉去全部记录
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


< 200
< {
  "content": [
    {
      "registerId": "xxx",
      "grantor": "uid1",
      "grantee": "uid2",
      "devTid": "xxx",
      "ctrlKey": "xxx",
      "expire": 300,
      "longCreateTime": 1488372857467,
      "desc": "授权",
      "instructionExpire": null,
      "mode": "ALL",
      "enableIFTTT": true,
      "enableScheduler": true,
      "deviceName": "hha",
      "granteeName": "",
      "granteeAvater": null,
      "cidName": "生活电器/灭蚊器",
      "categoryName": {
        "zh_CN": "生活电器/灭蚊器",
        "en_US": "Life electric application/Mosquito Killer"
      },
      "productName": {
        "en_US": "测试",
        "zh_CN": "test"
      },
      "result": false
    },
  ],
  "totalPages": 1,
  "totalElements": 1,
  "last": true,
  "size": 20,
  "number": 0,
  "sort": null,
  "first": true,
  "numberOfElements": 1
}

4.4 IFTTT规则、预约任务管理

IFTTT规则

英文全称是IF-THIS-THEN-THAT,基于纯软件服务的IFTTT,可以参考百度百科对IFTTT的解释。氦氪云提供的IFTTT服务则结合了软服务和硬件服务。其使用方式很简单,提交一条IFTTT规则即可,氦氪云IFTTT规则有自己的语法,请参考《氦氪云IFTTT规则语法》。

预约任务

预约任务类似手机上的待办事项、闹钟。氦氪提供了基于软服务和硬件服务的预约服务,要实现预约功能,提交一个预约任务即可,但一个设备最多只能添加10个预约任务。

4.4.1 添加IFTTT规则

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule" \
    -d '{
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxx",
        "subDevTid": "01234567788"
        "ruleName" : "新建联动",
        "condition" : {
            "triggerType" : REPORT,
            "conDesc" : "触发描述"
            "triggerParams" : [
              {
                "left" : "_cmdId",
                "operator" : "==",
                "right": 10
              },
              {
                "left" : "_cloudTime",
                "operator" : "==",
                "right" : "0 15 10 * * ? 2016"
              },
              ......      
            ]
        },
        "iftttTasks" : [
            {
                "type": "APPSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "desc" : "开灯"
                    "data": {
                        "raw": "48070200010153"
                    }
                }
            },
            {
                "type": "APPSUBSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "desc" : "开灯"
                    "data":{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                }

            },
            {
                "type": "APPGROUPSEND",
                "params": {
                    "groupId":"123123",
                    "desc" : "开客厅灯"
                    "data":{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                }
            },
            {
                "type": "SCENETRIGGERSEND",
                "params": {
                    "sceneId":"123123",
                    "desc" : "执行场景"
                    "data":{
                        "cmdId" : 1,
                        "key1" : "value"
                    }
                }
            },
            {
                "type": "ENABLEIFTTT",
                "desc" : "开启联动"
                "params": {
                    "iftttId":"123123123",
                    "enable":"enable\disable"
                }
            },
            {
                "type": "DALAYTIME",
                "desc" : "延时执行"
                "params": {
                    "time":"10"
                }
            }
        ],
        "desc" : "xxxxxx"
        "pushMsg": {
            "pushEnable": true,
            "isAlarm": true,
            "pushTemplateId": "00000000012"
        },
        "smsPushMsg": {
            "pushEnable": "true",
            "pushTemplateId": "00000000002"
        },
        "iftttType":"CUSTOM",
        "cronExpr" : "0 15 10 * * ? 2016",
        "timeZoneOffset" : 480,
        "setRing":{
            "cmdId" : 1,
            "key1" : "value"
        },
        "undo_ring" = {
            "undoParams": [
                {
                    "left": "_cmdId",
                    "operator": "==",
                    "right": 10,
                }
            ],
            "subIftttTask": {
                "type": "appSend",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "data": {
                        "raw": "48070200010153"
                    }
                }
            }
        }
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
subdevTid 可选 String 子设备ID
ruleName 必选 String 长度[1, 128] 规则名称
condition 必选 TriggerCondition 联动触发条件
iftttTasks 必选 List 联动执行action列表
desc 可选 String 长度[1, 128] 联动描述
pushMsg 可选 PushMessage 推送信息
smsPushMsg 可选 PushMessage 短信推送信息
iftttType 必选 enum SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM 联动类型
cronExpr 可选 cron_expr 启动时间cron表达式
timeZoneOffset 必选 String [-720, 720] 时区偏移,请注意javascript中获取的东八区时区偏移为-480,该处需要填写480
setRing 可选 Map 设置铃声的指令
undoRing 可选 UndoRingIFTTT 撤销铃声的联动
  • TriggerCondition参数说明
参数名 参数类型 取值范围 说明
triggerType enum SCHEDULER, REPORT 触发类型(定时触发,上行指令触发)
triggerParams List 触发表达式参数列表
conDesc String 长度[1, 128] 触发条件描述
  • TriggerParam 参数说明
参数名 参数类型 取值范围 说明
left String 条件表达式左边参数
right String 条件表达式右边参数
operator String ">", "<", "==", "in", "not in" 条件表达式运算符
  • UndoRingIFTTT参数说明
参数名 参数类型 取值范围 说明
left String 条件表达式左边参数
right String 条件表达式右边参数
operator String ">", "<", "==" 条件表达式运算符
subTask Map 联动执行action指令
  • PushMessage 参数说明
参数名 参数类型 取值范围 说明
pushEnable boolean 是否推送
isAlarm boolean 是否是告警推送(短信推送无该参数)
pushTemplateId String 推送模板ID
pushParams List 推送模板参数(名称、执行结果、执行时间已默认添加)

参数提交说明

  • 触发条件参数为定时触发,则参数right必须为cron表达式 且云端会对cron表达式触发频率进行校验,触发过于频繁的表达式会被禁止创建(每5分钟触发一次为阈值)

  • IFTTTTask参数说明:
    1> type : 为字符串String 取值 [appSend,appSubSend,appGroupSend,sceneTriggerSend,enableIFTTT,delayTime]
    2> params: 根据type的不同所传参数也不一样, 对应关系如,上边创建参数所示

  • PushMessage参数说明: 1> pushParams推送基本参数已添加,故录入时暂时不用添加改参数. 2> 短信推送目前只支持安防报警类型的联动,其他类型的联动暂不需要添加改参数

返回

< 201
< {  
    "cronExpr": "0 15 10 * * ? 2016",
    "iftttType": "SECURITY_ALARM",
    "uid": "10894587829",
    "ruleId": "effdd6a0-5b67-486b-8e14-fe6606d10c7d",
    "pushMsg": {
        "alarm": false,
        "pushEnable": true,
        "pushParams": [],
        "pushTemplateId": "00000000012"
    },
    "smsPushMsg": {
        "alarm": false,
        "pushEnable": true,
        "pushParams": [],
        "pushTemplateId": "00000000002"
    },
    "ctrlKey": "e86ea2dead014923b1c04a463372637a",
    "pid": "00000000000",
    "updateTime": null,
    "ruleName": "SECURITY_ALARM_test6",
    "isEnabled": true,
    "iftttTasks": [
        {
            "params": {
                "devTid": "2016-08-17T20-21-42",
                "data": {
                    "cmdId": 1,
                    "power": 1
                },
                "ctrlKey": "54308a73b0b34911a14206b8baaba57f"
            },
            "type": "APPSEND"
        }
    ],
    "devTid": "test-11-36-14",
    "undoRing": {
        "subIftttTask": {
            "params": {
                "devTid": "123123",
                "data": {
                    "cmdId": 1,
                    "key1": "value"
                },
                "ctrlKey": "123123"
            },
            "desc" : "开灯"
            "type": "APPSEND"
        },
        "undoParams": [
            {
                "operator": "==",
                "right": "10",
                "left": "_cmdId"
            }
        ]
    },
    "timeZoneOffset": 480,
    "subDevTid": null,
    "setRing": {
        "cmdId": 1,
        "key1": "value"
    },
    "createTime": 1482313906019,
    "condition": {
        "triggerParams": [
            {
                "operator": "==",
                "right": "10",
                "left": "_cmdId"
            },
            {
                "operator": "==",
                "right": "0 15 10 * * ? 2016",
                "left": "_cloudTime"
            }
        ],
        "triggerType": "REPORT",
        "conDesc" : "触发描述"
    },
    "desc": "第一次测试"
}

调用说明

  • 需console提供接口,通过设备相关信息确认当前联动下是否包含闹铃设备或报警设备,否则无法确认。
  • 当前联动如果包含多个触发条件,只支持 以 并且的关系操作
  • 联动名称不可重复,且数量不超过20个
  • 请注意接口中的参数形式及名称

4.4.2 列举IFTTT规则

支持通过联动名称模糊查询

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?devTid=1234&ruleName=xxxx&ruleId=1234&ruleType=CUSTOM"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 可选 String 设备ID,多个使用逗号分隔
ruleName 可选 String 联动名称,支持模糊查询
ruleId 可选 String 联动ID,多个使用逗号分隔
ruleType 可选 String SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM 联动类型

返回

< 200
< [
    同4.4.1
    ...
]

4.4.3 编辑IFTTT规则

更新为全参提交,参数与4.4.1方法相同

curl -v -X PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?ruleId=123"
       -d '{
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxx",
        "subDevTid": "01234567788"
        "ruleName" : "新建联动",
        "condition" : {
            "triggerType" : REPORT,
            "triggerParams" : [
              {
                "left" : "_cmdId",
                "operator" : "==",
                "right": 10
              },
              {
                "left" : "_cloudTime",
                "operator" : "==",
                "right" : "0 15 10 * * ? 2016"
              },
              ......      
            ]
        },
        "iftttTasks" : [
            {
                "type": "APPSEND",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "data": {
                        "raw": "48070200010153"
                    }
                }
            },
            ......
        ],
        "desc" : "xxxxxx"
        "pushMsg": {
            "pushEnable": true,
            "isAlarm": true,
            "pushTemplateId": "00000000012"
        },
        "isEnabled" : true,
        "iftttType":"CUSTOM",
        "cronExpr" : "0 15 10 * * ? 2016",
        "timeZoneOffset" : 480,
        "setRing":{
            "cmdId" : 1,
            "key1" : "value"
        },
        "undo_ring" = {
            "undoParams": [
                {
                    "left": "_cmdId",
                    "operator": "==",
                    "right": 10,
                }
            ],
            "subIftttTask": {
                "type": "appSend",
                "params": {
                    "devTid": "2016-08-17T20-21-42",
                    "ctrlKey": "54308a73b0b34911a14206b8baaba57f",
                    "data": {
                        "raw": "48070200010153"
                    }
                }
            }
        }
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
subdevTid 可选 String 子设备ID
ruleName 必选 String 长度[1, 128] 规则名称
condition 必选 TriggerCondition 联动触发条件
iftttTasks 必选 List 联动执行action列表
desc 可选 String 长度[1, 128] 联动描述
pushMsg 可选 PushMessage 推送信息
smsPushMsg 可选 PushMessage 短信推送信息
iftttType 必选 enum SECURITY_ALARM,DEPLOY,MORNING_ALARM,DOOR_BELL,CUSTOM 联动类型
cronExpr 可选 cron_expr 启动时间cron表达式
timeZoneOffset 必选 String [-720, 720] 时区偏移,请注意javascript中获取的东八区时区偏移为-480,该处需要填写480
setRing 可选 Map 设置铃声的指令
undoRing 可选 UndoRingIFTTT 撤销铃声的联动
enabled 可选 Boolean 联动开关

返回

< 204
< No Content

调用说明

修改联动是enabled参数 如果没有输入,则不会修改联动当前的isEnabled

4.4.4 删除IFTTT规则

curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttRule?ruleId=xxx,xxx,xxx"

参数

参数名 是否可选 参数类型 取值范围 说明
ruleId 必选 String 联动ID,多个使用逗号分隔
randomToken 可选 String

返回

  • 没有返回值时
< 204
< No Content
  • 有返回值时
< 202
< {
    "randomToken":"1qazxsw23edcvfr4"
    "scene":[
      {
        "sceneId":"222222222",
        "sceneName":"睡觉"
      },
      {
        "sceneId":"333333"
        "sceneName":"会家"
      }
      ...
    ]
    "ifttt":[
      {
        "ruleId":"1111111",
        "ruleName":"看电视"
      },
      {
        "ruleId":"666666",
        "ruleName":"开门"
      },
      .....
    ]
  }

4.4.5 添加预约任务

预约任务提供两种简易方式,4.4.5.1 添加一次性预约任务4.4.5.2 添加循环预约任务,当此两个接口无法满足条件时请调用本接口进行创建。 下面是创建定时预约任务的通用调用方式。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask" \
    -d '{
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxxxx",
        "code" : {
            "cmdId" : 1
        },
        "taskName" : "xxxxx",
        "schedulerType" : "GENERIC",
        "taskKey" : "xxxx",
        "timeZoneOffset" : 480,
        "desc" : "xxxx",
        "isForce" : false,
        "enable" : false,
        "feedback" : true,
        "cronExpr" : "0 */2 * * * ? *"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
code 必选 Map 预约任务代码
taskName 必选 String 长度[1, 128] 预约任务名称
schedulerType 必选 String ONCE, LOOP, GENERIC 任务类型,根据类型不同提交的参数也有所不同。此处使用"GENERIC"。
taskKey 必选 String 由客户端生成唯一标识该任务的字符串,一经生成不可修改
timeZoneOffset 必选 String [-720, 720] 时区偏移,请注意javascript中获取的东八区时区偏移为-480,该处需要填写480
desc 必选 String 长度[1, 128] 任务描述
isForce 必选 boolean true/false(默认false) 创建时任务重复是否强制覆盖
enable 必选 boolean true/false(默认false) 创建的任务是否生效()
feedback 必选 boolean true/false(默认false) 任务执行完毕后是否回馈
cronExpr 必选 CronExpr 任务触发的时间cron表达式,当创建GENERIC型预约时必须提供。cron表达式说明见下方。

cronExpr说明

cronExpr表达式可以用来定义一个计划时间来约定执行工作。使用空格进行各个时间段的分隔,cronExpr表达式由7部分组成,格式如下:

Seconds Minutes Hours DayofMonth Month DayofWeek Year

字段名称 可选值 额外可选特殊字符 说明
Seconds 0-59 , - * /
Minutes 0-59 , - * / 分钟
Hours 0-23 , - * / 小时
DayofMonth 1-31 , - * ? / L W C
Month 0-11 或者 JAN-DEC , - * / 月。1-12月简写列表为
"JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC"
DayofWeek SUN-SAT , - * ? / L C # 星期。周一至周日简写列表为
"MON, TUE, WED, THU, FRI, SAT, SUN"
Year 1970-2099 , - * / 年份
  1. "*" 表示匹配该域的任意值,假如在minutes域使用"*", 即表示每分钟都会触发事件。
  2. "?" 只能用在DayofMonth和DayofWeek两个域。它也匹配域的任意值,但实际不会。因为DayofMonth和DayofWeek会相互影响。例如想在每月的20日触发调度,不管20日到底是星期几,则只能使用如下写法: "13 13 15 20 * ? *", DayofWeek位只能用"?",而不能使用"*"。
  3. "-" 表示范围,例如在Minutes域使用"5-20",表示从当前小时内的第5分到20分钟每分钟触发一次
  4. "/" 表示起始时间开始触发,然后每隔固定时间触发一次,例如在Minutes域使用5/20,则意味着第5分钟触发一次,而第25,第45等分别触发一次。
  5. "," 表示列出枚举值值。例如:在Minutes域使用"5,20",则意味着在第5和第20分钟触发一次。
    可通过http://www.cronmaker.com/ 进行格式生成及校验。

返回


< 200
< 同4.4.6
4.4.5.1 添加一次性预约任务

所谓一次性,是指任务在未来一个时间点执行,且执行一次。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask" \
    -d '{
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxxxx",
        "code" : {
            "cmdId" : 1
        },
        "taskName" : "xxx",
        "schedulerType" : "ONCE",
        "timeZoneOffset" : 480,                         // 东八区时区偏移
        "taskKey" : "xxxx",
        "desc" : "xxxx",
        "isForce" : false,
        "triggerDateTime" : "2016-01-07T12:00:00"       // localDate,默认东八区时间
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
code 必选 Map 预约任务代码
taskName 必选 String 长度[1, 128] 预约任务名称
schedulerType 必选 String ONCE, LOOP, GENERIC 任务类型,根据类型不同提交的参数也有所不同。此处使用"ONCE"。
timeZoneOffset 必选 String [-720, 720] 时区偏移,请注意javascript中获取的东八区时区偏移为-480,该处需要填写480。
taskKey 必选 String 由客户端生成唯一标识该任务的字符串,一经生成不可修改
desc 必选 String 长度[1, 128] 任务描述
isForce 必选 Boolean 创建时任务重复是否强制覆盖
enable 必选 boolean true/false(默认false) 创建的任务是否生效()
triggerDateTime 必选 String 一次性预约触发时间

返回


< 200
< 同4.4.6
4.4.5.2 添加循环预约任务

所谓循环,是指一周中某几天的某个时间点执行,如不删除则一直执行。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask" \
    -d '{
        "devTid" : "ESP_xxx",
        "ctrlKey" : "xxxxx",
        "code" : {
            "cmdId" : 1
        },
        "taskName" : "xxx",
        "schedulerType" : "LOOP",
        "timeZoneOffset" : 480,                         // 东八区时区偏移
        "taskKey" : "xxxx",
        "desc" : "xxxx",
        "isForce" : false,
        "triggerTime" : "12:00:00",
        "repeatList" : ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"]
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
code 必选 Map 预约任务代码
taskName 必选 String 长度[1, 128] 预约任务名称
schedulerType 必选 String ONCE, LOOP, GENERIC 任务类型,根据类型不同提交的参数也有所不同
timeZoneOffset 必选 String [-720, 720] 时区偏移,请注意javascript中获取的东八区时区偏移为-480,该处需要填写480
taskKey 必选 String 由客户端生成唯一标识该任务的字符串,一经生成不可修改
desc 必选 String 长度[1, 128] 任务描述
isForce 必选 Boolean 创建时任务重复是否强制覆盖
enable 必选 boolean true/false(默认false) 创建的任务是否生效()
triggerTime 必选 String 循环预约触发时间,当创建LOOP型预约时必须提供。
格式为"hh:mm:ss",例如"16:30:00"表示下午4点半。
repeatList 必选 List ["MON", "TUE", ...] 循环预约触发天,当创建LOOP型预约时必须提供。
周一至周日对应值为"MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"

返回


< 200
< 同4.4.6

4.4.6 列举预约任务


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask?devTid=1234&ctrlKey=xxx&taskId=1234"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID,按其value筛选
ctrlKey 必选 String 控制码
taskId 可选 String 任务ID,按其value筛选

返回


< 200
< [
    {
        "taskId" : 1,
        "uid" : "uid123",
        "taskName" : "定时001",
        "taskKey" : "xxxx",
        "enable" : true,
        "schedulerType" : "LOOP",
        "code" : {
            "cmdId" : 1
        },
        "desc" : "我的的定时关机任务",
        "timeZoneOffset" : 480,
        "cronExpr" : "0 5 * * * ? * ",
        "count" : 1,                                     // 执行次数
        "timerTaskStatus" : "FREEZE",                    // 任务调度状态 FREEZE(冻结)/SCHEDULING(调度)
        "feedback" : true,                      
        "expired" : false,       
        "nextTriggerTime" : "2016/01/08T12:00:00",      // localDate,默认东八区时间
        "serverTime": {
            "dayOfWeek": "SUNDAY",
            "nano": 886000000,
            "hour": 1,
            "monthValue": 4,
            "chronology": {
                "id": "ISO",
                "calendarType": "iso8601"
            },
            "second": 33,
            "dayOfYear": 101,
            "year": 2016,
            "month": "APRIL",
            "minute": 25,
            "dayOfMonth": 10
        },
        "serverTimeZoneOffset" : 480,
        "createTime" : "2016/01/07T12:00:00",           // localDate, 默认东八区时间
        "modifyTime" : "2016/01/07T12:00:00"            // localDate,默认东八区时间
    },
    ...
]

4.4.7 编辑预约任务


curl -v -X PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask?taskId=123&devTid=ESP_001&ctrlKey=xxx"
    -d '{
        "taskName" : "xxx",
        "desc" : "xxx",
        "code" : {
            "cmdId" : 1,
        },
        "enable" : true,
        "feedback" : true,
        "cronExpr" : "0 1/2 * * * ? *"
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
taskId 必选 String 任务ID
taskName 可选 String 长度[1, 128] 预约任务名称
desc 可选 String 长度[1, 128] 任务描述
code 可选 Map 预约任务代码
enable 可选 true 启用/禁用
feedback 可选 Boolean 任务执行完毕后是否回馈
triggerDateTime 可选 String 一次性定时预约触发时间,当修改ONCE型预约时提供
triggerTime 可选 String 循环预约触发时间,当修改LOOP型预约时提供
repeatList 可选 List ["MON", "TUE", ...] 循环预约触发天,当修改LOOP型预约时提供
cronExpr 可选 CronExpr 任务触发的时间的cron表达式,当修改GENERIC型预约时提供

返回


< 200
< 同4.4.6

4.4.8 删除预约任务


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/schedulerTask?devTid=xxx&ctrlKey=xxx&taskId=xxx,xxx"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
taskId 可选 String 任务ID,多个逗号分隔;若不指定该参数,则会删除全部预约任务

返回


< 200
< 同4.4.6

4.4.9 查询联动执行历史记录

curl -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/rule/iftttExecuteHistory?page=0&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
ruleId 可选 String 联动ID
ruleName 可选 String 联动name
result 可选 Boolean true/false 执行结果
startTime 必选 dateTime yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 起始时间
endTime 可选 dateTime yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 结束时间
page 可选 Int [0, ?] 分页参数
size 可选 Int [1, 20] 分页参数

返回

< 201
< {
  "ruleId": "f81eef1d-5a88-4e5c-bd9c-623f39434c0a",
  "uid": "31009181856",
  "ruleName": "test",
  "iftttExecuteDetails": [
    {
      "iftttExecuteAck": "SUCCESS",
      "desc": "开关3:关闭",
      "iftttTaskId": "c069e96dccd84ef7aa6578e663e2fa2a"
    },
    {
      "iftttExecuteAck": "SUCCESS",
      "desc": " 开关1:打开",
      "iftttTaskId": "ed1981c3b12944ba9ebacdf8cff4df4f"
    },
    {
      "iftttExecuteAck": "FAILURE",
      "desc": "红色:0 绿色:0 蓝色:0 白光:0 RGB亮度系数:0",
      "iftttTaskId": "d90eebe551574f1fbccb6bb786ca21bc"
    }
  ],
  "result": true,
  "executeTime": 1493050660080,
  "desc": ""
 }

注意

  • 开始时间为必选参数

4.5 存储、统计、告警

存储

云端提供了K/V、文件存储的接口,且这些数据都是厂家、用户隔离,APP开发者可以很方便地调用。

统计

统计有两个来源、5个维度。

来源包括:

  • 设备自动上报的产品参数值,通常就是某时刻的设备状态,可在氦氪云控制台->产品管理->参数信息->产品参数信息页面里查看目前已有的产品参数。
  • APP调用存储接口上报的用户参数值,可在氦氪云控制台->产品管理->参数信息->用户参数信息页面里查看目前已有的用户参数。

维度包括:最大值max、最小值min、平均值avg、总和sum、记录数count。

不管是设备还是APP,只要配置好需要统计的参数,按照规定格式上报,云端就能对某个时间段内的数据进行。

告警

可以配置一些告警逻辑规则,在规则满足时,云端通过短信、邮件或APP通知这三种方式发出告警,配置接口将在下个版本的云端 API里提供,暂时只能通过和氦氪云团队直接提需求单解决,但是云端提供了一些接口可以访问已经产生的告警记录。

4.5.1 获取用户档案

用户档案,有两个组成部分:

  • 固定部分,包括:名字、性别、头像、生日。
  • 自定义部分,K/V格式,可以定义以设置。

curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/user/profile"

返回


< 200
< {
    "firstName" : "Li",
    "lastName" : "Hekr",
    "gender" : "MAN",                                   // 取值范围: ["MAN", "WOMAN", "UNKNOWN"]
    "birthDay" : 952646400000,                          // 时间戳
    "avatarUrl" : {                                     // 头像链接
        "small" : "http://ufilexxx/xxxxx",
        "big" : "http://ufilexxx/yyyyy"
    },
    "updateDate" : 1460216077963                        // 时间戳
    "customKey1" : "customValue1"                       // 自定义K/V
}

4.5.2 更新用户档案

可以只填部分参数,即支持部分档案更新。


curl -v -X PUT \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/user/profile" \
    -d '{
        "firstName" : "Mao",
        "lastName"  : "Xiao",
        "gender" : "MAN",
        "birthday" : "1990-01-01",
        "description" : "就是我",
        "avatarUrl" : {
            "small" :"http://xxxx.com"
        },
        "extraProperties" : {
            "customKey1" : "customValue1"               // 自定义K/V
        }
    }'

返回


< 204
< No Content

4.5.3 设置用户APP偏好设置

所谓APP偏好,即类似APP皮肤等,跟APP本身相关的特性。 该类偏好设置跟具体品类和设备没有任何关系,只是用来反映用户的使用习惯(注意和用户档案的区别)。比如:

  • APP皮肤或者主题
  • 反向授权是否需要本人同意
  • APP缓存自动清除的大小阈值

类似反向授权是否需要本人同意这种可预见的通用配置可直接作为系统内置偏好,该类设置的参数名全系统唯一,且只允许厂家修改默认值,不允许厂家删除。 后端(云端 API)只处理内置偏好,比如反向授权是否需要本人同意。其他偏好,比如APP皮肤或主题这种后端只负责存储、拉取,逻辑由APP来实现。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/appPreferences" \
    -d '{
        "key1" : "value1",
        ...
    }'

返回


< 201
< 创建的偏好设置

4.5.4 获取用户APP偏好设置


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/appPreferences"

返回


< 200
< {
      "reservedKey": {
        "_ReverseAuthAgree" : false
      },
      "customKey": {
        "key1": "red",
        "key2": 5,
        "key4": true,
        "key3": 17.7
      }
}

4.5.5 用户产品偏好设置

所谓产品偏好,即类似净化器默认工作模式等,跟某个产品相关的特性。 该类偏好设置跟具体品类相关。比如:

  • 该品类预约任务最大数
  • 该品类最大授权数
  • 该品类的PM2.5值的默认报警阈值
  • 该品类的AQI值在IFTTT规则中的默认触发区间

另外,需要注意的是: 用户不能通过调用云端 API来提交修改内置的品类偏好


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/productPreferences" \
    -d '{
        "key1" : "value1",
        ...
    }'

返回


< 201
< 创建的偏好设置

4.5.6 获取用户产品偏好设置


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/productPreferences"

返回


< 200
< {
    "key1" : "value1",
    ...
}

4.5.7 设置具体设备偏好设置

特定设备的偏好设置 我们可以认为:

  • 品类偏好设置是具体设备偏好设置的默认设置
  • 具体设备偏好设置是品类偏好设置的特例设置

curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/productDevicePreferences?devTid=xx&ctrlKey=xx&subDevTid=xx"
    -d '{
        "key1" : "value1",
        ...
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
subDevTid 可选 String 子设备ID

返回


< 201
< 创建的偏好设置

4.5.8 获取具体设备偏好设置

获取特定设备的偏好设置,如果用户没有特殊设定则默认返回 品类偏好设置的默认值


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/productDevicePreferences?devTid=xx&ctrlKey=xx&subDevTid=xx"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
ctrlKey 必选 String 控制码
subDevTid 可选 String 子设备ID

返回


< 200
< {
    "key1" : "value1",
    ...
}

4.5.9 获取设备告警记录

Deprecated

该接口将会被废弃,请使用用户通知

GET /user/warnings?warningId=&startTime=&endTime=&devTid=&page=1&size= HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
X-Hekr-ProdPubKey: {PPK}

注意,该接口调用成功后会自动设置被拉取告警记录为已读状态。

参数

参数名 是否可选 参数类型 取值范围 说明
warningId 可选 String 告警ID,多个使用逗号分隔
devTid 必选 String 设备ID
subDevTid 可选 String 子设备ID
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "content": [
    {
      "id": "591acd5be4b024b9f457d100",
      "isRead": false,
      "reportTime": 1494928731841,
      "subject": "subject",
      "content": "foo",
      "sender": {
        "type": "Device",
        "ppk": {
          "pid": "01240737641",
          "mid": "IyFauxgNdjFs"
        },
        "devTid": "01_0d1c17d1007d16cdb7c4160d41e04",
        "subDevTid": null
      },
      "data": {
        "cmdId": 1,
        "light": 2
      }
    }   
  ],
  "last": false,
  "totalPages": 2,
  "totalElements": 20,
  "sort": [
    {
      "direction": "DESC",
      "property": "reportTime",
      "ignoreCase": false,
      "nullHandling": "NATIVE",
      "ascending": false
    }
  ],
  "first": true,
  "numberOfElements": 10,
  "size": 10,
  "number": 0
}

4.5.9.1 获取用户下所有设备告警记录

Deprecated

该接口将会被废弃,请使用用户通知

GET /user/allWarnings?startTime=&endTime=&page=1&size= HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
X-Hekr-ProdPubKey: {PPK}

参数

参数名 是否可选 参数类型 取值范围 说明
startTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回

如果有子设备存在,deviceName、logo 都是子设备的

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "content": [
    {
      "id": "591af65bce1ac730f9e72cbc",
      "isRead": false,
      "reportTime": 1494939227134,
      "subject": "warning titile ",
      "content": "warning content",
      "sender": {
        "type": "Device",
        "ppk": {
          "pid": "01227017699",
          "mid": "127a52186e4"
        },
        "devTid": "1_3522d7070fa2a19c8fa0f5f1e9b6f",
        "subDevTid": null
      },
      "data": {
        "cmdId": 1,
        "light": 2
      }
    }
  ],
  "last": true,
  "totalPages": 1,
  "totalElements": 1,
  "numberOfElements": 1,
  "first": true,
  "sort": [
    {
      "direction": "DESC",
      "property": "reportTime",
      "ignoreCase": false,
      "nullHandling": "NATIVE",
      "ascending": false
    }
  ],
  "size": 10,
  "number": 0
}

4.5.10 删除设备告警记录

Deprecated

该接口将会被废弃,请使用用户通知

DELETE /user/warnings?devTid=xxx&waringId=123,456,789 HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
X-Hekr-ProdPubKey: {PPK}

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
warningId 可选 String 告警ID,多个使用逗号分隔;若为空,则删除该用户收到的关于此设备的所有告警记录

返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

4.5.11 产品参数简单聚合统计

氦氪云控制台->产品管理->参数信息->产品参数信息页面里能看到当前已添加的产品参数。

通常,设备都会定时上报(参考第二章基础通信API)这些产品参数,云端会自动存储它们。如果想对它们进行简单的聚合计算,就可以调用这个接口。渲染返回的数据,可绘制成折线,如下图。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics?devTid=1234&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&dataTag=pm25,aqi"

另外该接口提供了下面3种简易方式,当以下3个接口无法满足条件时请调用上面的方法进行创建。

4.5.11.1 近一天时间内产品参数简单聚合统计

该接口返回以当前时间节点开始近一天内的产品参数简单聚合统计数据,注意该接口并不需要指定startTime参数


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics/daily?devTid=1234&dataTag=pm25,aqi"
4.5.11.2 近一周时间内产品参数简单聚合统计

该接口返回以当前时间节点开始近一周内的产品参数简单聚合统计数据,注意该接口并不需要指定startTime参数


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics/weekly?devTid=1234&dataTag=pm25,aqi"
4.5.11.3 近一月时间内产品参数简单聚合统计

该接口返回以当前时间节点开始近一月内(注意这里默认是30天)的产品参数简单聚合统计数据,注意该接口并不需要指定startTime参数


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics/monthly?devTid=1234&dataTag=pm25,aqi"
4.5.11.4 近一个小时时间内产品参数简单聚合统计

该接口返回以当前时间节点开始近一小时内的产品参数简单聚合统计数据,注意该接口并不需要指定startTime参数


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics/hourly?devTid=1234&dataTag=pm25,aqi"
4.5.11.5 近一年时间内产品参数简单聚合统计

该接口返回以当前时间节点开始近一年内的产品参数简单聚合统计数据,注意该接口并不需要指定startTime参数


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/deviceStatistics/yearly?devTid=1234&dataTag=pm25,aqi"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID
dataTag 必选 String 产品参数名,多个参数名使用逗号分隔
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间

返回


< 200
< [
    {
        "cnt": 20.0,                                    // count
        "avg": 567.35,                                  // average
        "cid": "5102af881daf",
        "max": 989.0,   
        "sum": 11347.0,
        "min": 57.0,
        "pid": "01662606768",
        "mid": "0178fba35c8a",
        "devTid": "local-2016-06-02T13-45-47",
        "tag": "aqi",                                   //产品参数名
        "startTime": 1464848700000,
        "endTime": 1464849000000
    },
    {
        "cnt": 30.0,
        "avg": 73.03333333333336,
        "cid": "5102af881daf",
        "max": 196.0,
        "sum": 1442.0,
        "min": 10.0,
        "pid": "01662606768",
        "mid": "0178fba35c8a",
        "devTid": "local-2016-06-02T13-45-47",
        "tag": "pm25",                                   //产品参数名
        "startTime": 1464849000000,
        "endTime": 1464849300000
    }
]

4.5.12 上报用户参数记录 - 参数和设备无关

参数和设备无关,因此该接口适合做非设备性的用户数据存储,比如用户的积分是1400。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/customUserData?pid=xxxx" \
    -d '{
        "score" : 1400,
        ...
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 厂商唯一ID

返回


< 201
< 上传的数据原样返回

4.5.13 上报用户参数记录 - 参数和设备有关

氦氪云控制台->产品管理->参数信息->用户参数信息页面里,可以添加需要上报的用户参数。

参数和设备有关,因此该接口适合做设备性的用户数据存储,比如用户在某投食机里添加了100克猫粮。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/customUserDeviceData?devTid=xxxx" \
    -d '{
        "catFood" : 100,
        ...
    }'

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 必选 String 设备ID

返回


< 201
< 上传的数据原样返回

4.5.14 查询用户参数记录

不管参数和设备是否相关,该接口均可用来查询该参数的记录。若不指定分页参数,则默认返回最近20条记录。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/customData?devTid=123&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&page=1&size=1"

参数

参数名 是否可选 参数类型 取值范围 说明
devTid 可选 String 设备ID,指定该参数,则必须携带ProdPubKey Header头,查询设备相关性用户参数记录
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


< 200
< [
    {
        "uid": "138xxxxxxxx",
        "devTid": "123",
        "time": 1460031251985,
        "pid": "01xxxxxxxxx",
        "mid": null,
        "month": 3,
        "hours": 12,
        "second": 11,
        "year": 2016,
        "data": {
            "drink": 111,
            "hobbit": "hike",
            "skin": "yellow",
            "pm25": 100
        },
        "day": 7,
        "minute": 14
    },
    {
        "uid": "138xxxxxxxx",
        "devTid": "123",
        "time": 1460385079529,
        "pid": "01xxxxxxxxx",
        "mid": null,
        "month": 3,
        "hours": 14,
        "second": 19,
        "year": 2016,
        "data": {
            "light": 99,
            "hobbit": "hike",
            "skin": "yellow",
            "pm25": 100
        },
        "day": 11,
        "minute": 31
    }
]

4.5.15 用户参数简单聚合统计


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ProdPubKey}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/user/userStatistics?startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800&dataTag=drink,light"

参数

参数名 是否可选 参数类型 取值范围 说明
dataTag 必选 String 用户参数名,多个参数名使用逗号间隔
devTid 可选 String 设备ID,指定该参数,则必须携带ProdPubKey Header头,统计设备相关性用户参数记录
startTime 必选 Long yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 Long yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间

返回


< 200
< [
    {
        "cnt": 20.0,                                    // count
        "avg": 567.35,                                  // average
        "cid": "5102af881daf",
        "max": 989.0,
        "sum": 11347.0,
        "min": 57.0,
        "pid": "01662606768",
        "mid": "0178fba35c8a",
        "devTid": "local-2016-06-02T13-45-47",
        "tag": "pm",                                     
        "startTime": 1464848700000,
        "endTime": 1464849000000
    },
    {
        "cnt": 30.0,
        "avg": 471.03333333333336,
        "cid": "5102af881daf",
        "max": 996.0,
        "sum": 14131.0,
        "min": 1.0,
        "pid": "01662606768",
        "mid": "0178fba35c8a",
        "devTid": "local-2016-06-02T13-45-47",
        "tag": "pm",
        "startTime": 1464849000000,
        "endTime": 1464849300000
    }
]

4.5.16 上传文件

已废弃

请使用文件上传接口

注意,上传文件不得大于2M。


curl -F "file=@/Path/file;type=xxx" \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/user/file"

返回


< 201
< {
    "fileOriginName" :"cdraw.png",
    "fileName" :"xxxx.png",
    "fileSourceUrl" :"http://hekr-images.xxxxx.png",
    "fileCDNUrl" :"http://hekr-images.xxxxxx.png",
    "uploadTime" :1458031660384,
    "md5" :"3ba434398bbde210435afba88f64e908"
}

4.5.17 列举已上传文件

不指定分页参数,默认列举最早的20个文件信息。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/user/file?fileName=xxx&page=1&size=20"

参数

参数名 是否可选 参数类型 取值范围 说明
fileName 可选 String 文件名
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


< 200
< {
    "sort" : null,
    "numberOfElements" : 1,
    "last" : true,
    "number" : 0,
    "content" : [
        {
            "fileOriginName" : "cdraw.png",
            "fileName" : "xxxxxx.png",
            "fileSourceUrl" : "http://hekr-images.xxxxxxxx.png",
            "fileCDNUrl" : "http://hekr-images.xxxxx.png",
            "uploadTime" : 1458031660384,
            "md5" : "3ba434398bbde210435afba88f64e908"
        }
    ],
    "totalPages" : 1,
    "first" : true,
    "totalElements" : 1,
    "size" : 20
}

4.5.18 删除已上传文件

已废弃

该接口不再删除文件,不会有任何效果,客户端无需手动调用删除文件,服务端会自动删除未引用的文件。


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/user/file?fileName=xxxx"

返回


< 204
< No Content

4.5.19 绑定推送标签接口

该接口用于给app用户绑定推送标签使用

POST /user/pushTagBind HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "appId" : "<appId>",
  "clientId": "123",
  "locale" : "zh-CN",
  "pushPlatform": "GETUI"
}

参数

参数名 是否可选 参数类型 取值范围 说明
clientId 必选 String 推送sdk分配给app的客户端id
pushPlatform 必选 String [GETUI, XIAOMI, HUAWEI, FCM ] 推送平台:GETUI 个推,XIAOMI 小米,HUAWEI 华为, FCM google推送
locale 必选 String [zh-CN, en-US, ...] 用户所用语言 Language Tag(IETF BCP 47 standard)

返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

4.5.20 解绑推送

该接口用于给app用户解绑推送

POST /user/unbindPushAlias HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "appTid" : "<appTid>",
  "clientId": "123",
  "pushPlatform": "GETUI"
}

参数

参数名 是否可选 参数类型 取值范围 说明
appTid 必选 String APP ID
clientId 必选 String 推送sdk分配给app的客户端id
pushPlatform 必选 String [GETUI, XIAOMI, HUAWEI ] 推送平台:GETUI 个推,XIAOMI 小米,HUAWEI 华为

返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

4.5.21 获取推送历史记录

该接口用于给app用户获取推送历史记录使用

GET /user/pushHistory?page=&size= HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "appTid" : "<appTid>",
  "clientId": "123",
  "pushPlatform": "GETUI"
}

返回

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "content": [
    {
      "subject": "您收到了新的资讯,请查阅",
      "content": "资讯标题",
      "createDate": 1488854041278
    },
    {
      "subject": "您收到了新的资讯,请查阅",
      "content": "资讯标题",
      "createDate": 1488854039037
    }
  ],
  "last": true,
  "totalElements": 2,
  "totalPages": 1,
  "numberOfElements": 2,
  "first": true,
  "sort": null,
  "size": 10,
  "number": 0
}

4.6 三方API

三方API,是氦氪云和第三方合作服务提供商联合推出的服务API。目前有两大类:

  1. 气象API。
  2. 红外API。

4.6.1 天气实况

获取指定城市的实况天气。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/weather/now?location=beijing&language=zh-Hans&unit=c"

参数

参数名 是否可选 参数类型 取值范围 说明
location 必选 String 支持:城市中文名(杭州)、拼音(hangzhou)、英文名(hangzhou)、经纬度(维度:经度 30.26:120.19)、IP(106.75.130.74)
language 可选 String 支持:简体中文zh-Hans(默认)、繁体中文zh-Hant、英文en
unit 可选 String 单位类型,支持:c(温度c、风速km/h、能见度km、气压mb)(默认)、f(温度f、风速mph、能见度mile、气压inch)

返回


< 200
{
    "results" : [{
    "location" : {
        "id" : "C23N20TF",
        "name" : "西雅图",
        "country" : "US",
        "timezone" : "America/Los_Angeles",
        "timezone_offset" : "-07:00"
    },
    "now" : {
        "text" : "多云",                                  // 天气现象文字
        "code" : "4",                                    // 天气现象代码
        "temperature" : "14",                            // 温度,单位为c摄氏度或f华氏度
        "feels_like" : "14",                             // 体感温度,单位为c摄氏度或f华氏度
        "pressure" : "1018",                             // 气压,单位为mb百帕或in英寸
        "humidity" : "76",                               // 相对湿度,0~100,单位为百分比
        "visibility" : "16.09",                          // 能见度,单位为km公里或mi英里
        "wind_direction" : "西北",  
        "wind_direction_degree" : "340",
        "wind_speed" : "8.05",
        "wind_scale" : "2",
        "clouds" : "90",
        "dew_point" : "-12"                              // 露点温度,请参考:http://baike.baidu.com/view/118348.htm
    },
    "last_update" : "2015-09-25T22:45:00-07:00"          // 数据更新时间(该城市的本地时间)
    }]
}

4.6.2 逐日预报

获取指定城市未来最多7天的每日白天和夜间预报。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/weather/daily?location=beijing&language=zh-Hans&unit=c&start=0&days=5"

参数

参数名 是否可选 参数类型 取值范围 说明
location 必选 String 支持:城市中文名(杭州)、拼音(hangzhou)、英文名(hangzhou)、经纬度(维度:经度 30.26:120.19)、IP(106.75.130.74)
language 可选 String 支持:简体中文zh-Hans(默认)、繁体中文zh-Hant、英文en
unit 可选 String 单位类型,支持:c(温度c、风速km/h、能见度km、气压mb)(默认)、f(温度f、风速mph、能见度mile、气压inch)
start 可选 Int 整数[0, 7]、日期YYYY/mm/dd 整数,例如:start=0代表今天(默认)、start=1代表明天;日期,例如:start=2015/10/1
days 可选 Int 从start算起days的天数

返回


< 200
< {
    "results" : [{
        "location" : {
            "id" : "WX4FBXXFKE4F",
            "name" : "北京",
            "country" : "CN",
            "path" : "北京,北京,中国",
            "timezone" : "Asia/Shanghai",
            "timezone_offset" : "+08:00"
        },
        "daily" : [{                                     // 返回指定days天数的结果
            "date" : "2015-09-20",                       // 日期
            "text_day" : "多云",                          // 白天天气现象文字
            "code_day" : "4",                            // 白天天气现象代码
            "text_night" : "晴",                         // 晚间天气现象文字
            "code_night" : "0",                          // 晚间天气现象代码
            "high" : "26",                               // 当天最高温度
            "low" : "17",                                // 当天最低温度
            "precip" : "0",                              // 降水概率,范围0~100,单位百分比
            "wind_direction" : "",                       // 风向文字
            "wind_direction_degree" : "255",             // 风向角度,范围0~360
            "wind_speed" : "9.66",                       // 风速,单位km/h(当unit=c时)、mph(当unit=f时)
            "wind_scale" : ""                            // 风力等级
        },
        {
            "date" : "2015-09-21",
            "text_day" : "晴",
            "code_day" : "0",
            "text_night" : "晴",
            "code_night" : "0",
            "high" : "27",
            "low" : "17",
            "precip" : "0",
            "wind_direction" : "",
            "wind_direction_degree" : "157",
            "wind_speed" : "17.7",
            "wind_scale" : "3"
        },
        {
            ...                                          // 更多返回结果
        }
        ],
        "last_update" : "2015-09-20T18:00:00+08:00"      // 数据更新时间(该城市的本地时间)
    }]
}

4.6.3 空气质量实况

获取指定城市的AQI、PM2.5、PM10、一氧化碳、二氧化氮、臭氧等空气质量信息。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Hekr-ProdPubKey: {ppk}" \
    "https://user-openapi.hekr.me/air/now?location=beijing&language=zh-Hans&scope=city"

参数

参数名 是否可选 参数类型 取值范围 说明
location 必选 String 城市拼音/英文名 例如:location=beijing
language 可选 String 支持:简体中文zh-Hans(默认)、繁体中文zh-Hant、英文en
scope 可选 String city, all scope为city时,只返回城市平均值;为all时,返回城市平均值和各监测站监测值

返回


< 200
< {
    "results": [{
            "location": {
                "id": "WX4FBXXFKE4F",
                "name": "北京",
                "country": "CN",
                "path": "北京,北京,中国",
                "timezone": "Asia/Shanghai",
                "timezone_offset": "+08:00"
            },
            "air": {
                "city": {                           //城市综合空气质量数据
                    "aqi": "40",                        //空气质量指数(AQI)是描述空气质量状况的定量指数
                    "pm25": "28",                       //PM2.5颗粒物(粒径小于等于2.5μm)1小时平均值。单位:μg/m³
                    "pm10": "33",                       //PM10颗粒物(粒径小于等于10μm)1小时平均值。单位:μg/m³
                    "so2": "2",                         //二氧化硫1小时平均值。单位:μg/m³
                    "no2": "32",                        //二氧化氮1小时平均值。单位:μg/m³
                    "co": "0.642",                      //一氧化碳1小时平均值。单位:mg/m³
                    "o3": "78",                         //臭氧1小时平均值。单位:μg/m³
                    "quality": "优",                    //空气质量类别,有“优、良、轻度污染、中度污染、重度污染、严重污染”6类
                    //数据发布时间
                    "last_update": "2015-09-23T13:00:00+08:00"
                },
                "stations": [{                      //该城市所有监测站数组"aqi": "50",
                        "pm25": "35",
                        "pm10": "0",
                        "so2": "2",
                        "no2": "39",
                        "co": "0.8",
                        "o3": "83",
                        "station": "万寿西宫",           //监测站名称
                        "latitude": "39.865927",        //监测站纬度
                        "longitude": "116.359805",      //监测站经度
                        "last_update": "2015-09-23T13:00:00+08:00"
                    },
                    {
                        ...                         //更多监测站
                    }
                ]
            },
            "last_update": "2015-09-23T22:45:48+08:00"
        }
    ]
}

4.6.4 空气质量城市排名


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/air/ranking?language=zh-Hans"

参数

参数名 是否可选 参数类型 取值范围 说明
language 可选 String 支持:简体中文zh-Hans(默认)、繁体中文zh-Hant、英文en

返回


< 200
< {
    "results": [{                                   // 城市排名数组,从好到差排序
            "location": {                           // 排名第一城市
                "id": "TV9JG0M1S9QU",                   // 城市ID
                "name": "阿里",                         // 城市名称
                "country": "CN",                       // 国家代码
                "path": "阿里,阿里,西藏,中国",            // 隶属层级,从小到大
                "timezone": "Asia/Shanghai",           // IANA标准时区名称(该名称不受夏令时影响)
                "timezone_offset": "+08:00"            // 相对于UTC时区的偏移量(采用夏令时的城市会因夏令时而变化)
            },
            "aqi": "18"                                // 空气质量指数
        },
        {
            "location": {                           // 排名第二城市
                "id": "WKN2DZXM71F0",
                "name": "玉林",
                "country": "CN",
                "path": "玉林,玉林,广西,中国",
                "timezone": "Asia/Shanghai",
                "timezone_offset": "+08:00"
            },
            "aqi": "18"
        },
        {
            ....                                    // 后续排名城市
        }
    ]
}

天气实况和空气质量实况


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey:{}"
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    "https://user-openapi.hekr.me/external/now?location=beijing&sign=5faa9f91a0961a2e1e0ad0c113e89863×tamp=1464849000"

参数

参数名 是否可选 参数类型 取值范围 说明
location 必选 String 天气与空气共用参数: 支持:城市中文名(杭州)、拼音(hangzhou)、英文名(hangzhou)
language 可选 String 天气与空气共用参数: 支持:简体中文zh-Hans(默认)、繁体中文zh-Hant、英文en
unit 可选 String 天气实况参数: 单位类型,支持:c(温度c、风速km/h、能见度km、气压mb)(默认)、f(温度f、风速mph、能见度mile、气压inch)
scope 可选 String city, all(默认为city) 空气质量参数: scope为city时,只返回城市平均值;为all时,返回城市平均值和各监测站监测值
flag 可选 String weather,air, all(默认为all) weather获取天气、air获取空气质量、all获取所有

返回


< 200
{
  "weather": [
    {
      "location": {
        "id": "WX4FBXXFKE4F",
        "name": "北京",
        "country": "CN",
        "path": "北京,北京,中国",
        "timezone": "Asia/Shanghai",
        "timezone_offset": "+08:00"
      },
      "now": {
        "text": "多云",
        "code": "4",
        "temperature": "4",
        "feels_like": "3",
        "pressure": "1025",
        "humidity": "55",
        "visibility": "2.1",
        "wind_direction": "东",
        "wind_direction_degree": "80",
        "wind_speed": "4.32",
        "wind_scale": "1",
        "clouds": "",
        "dew_point": ""
      },
      "last_update": "2017-02-14T16:35:00+08:00"
    }
  ],
  "air": [
    {
      "location": {
        "id": "WX4FBXXFKE4F",
        "name": "北京",
        "country": "CN",
        "path": "北京,北京,中国",
        "timezone": "Asia/Shanghai",
        "timezone_offset": "+08:00"
      },
      "air": {
        "city": {
          "aqi": "258",
          "pm25": "208",
          "pm10": "237",
          "so2": "43",
          "no2": "100",
          "co": "2.725",
          "o3": "25",
          "last_update": "2017-02-14T16:00:00+08:00",
          "quality": "重度污染"
        },
        "stations": null
      },
      "last_update": "2017-02-14T16:00:00+08:00"
    }
  ]
}

4.6.5 红外匹配


curl -v -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/irdainfo" \
    -d '{
        "action" :"IRA0",                               // 请求服务类IRA0
        "type" :"LE",                                   // type有:LE,BE,HEXLE,HEXBE,DEC,DECHL,DECLH,LHDEC,HLDEC,即硬件上报红外数据的格式
        // 红外编码,格式根据type的定义  
        "code" :"e400AB0EDB050A02CF04F201FE04DB012D02DD012C02DE011202F501E704F3011702F2011802F401E704F401EB04F0012E02F201D004F2011502F4011502F501E604F4010205DB011402DD010005F601FC04DC011302F5011702F2012D05B9010A02F3011702DE01FE04F4012E02DC012D02DC012D02DB011602F3011702F2012F02D90101020C021302F4011702D9013202F3012C02F401FE01F1012F02DA013102D8013302DA011402F5011802F2010B05D00112020E02FE01F2010005DB011502F4011902F2012F02DA011602F3011602F301E504F5011602F3012F02F3011602D9011902F401EA04F201E604F401FF04DE011302F3011302F6011502F3011702F3011802F4011702F2010105D8011602F401FF04F2011802DB012F02D9012F02D9011902F5012F02DA012F02BF012E02F5012F02F2011502DD012E02DB011402F4011902F2013002D8013002DB011602F3011402F3011A02EF013102C1014602DB011702F5010005DA013102D7013002D8013102DA011702F3012D02DB011602F30101020C021702F8013102D2010005DB012E02D9012F02D9013002C1014702D6013802D901E704F5010105D8010105D9013102D9010005DA013B020D02B304E8013102F501FFFF"
    }'

举例说明:

假设收到的红外数据的高低电平数是7个,长度分别是(单位us,微秒):


    256,512,768,1024,1280,1536,1792

对应的16进制数分别是:


    0x100,0x200,0x300,0x400,0x500,0x600,0x700

则各种格式对应的编码是:


    "LE" :"07000001000200030004000500060007",
    "BE" :"00070100020003000400050006000700",
    "HEXBE" :"0100020003000400050006000700",
    "HEXLE" :"0001000200030004000500060007",
    "DEC" :"256, 512, 768,1024,1280,1536,1792",
    "DECHL" :"256.0H, 512.0L, 768.0H,1024.0L,1280.0H,1536.0L, 1792.0H",
    "DECLH" :"256.0L, 512.0H, 768.0L,1024.0H,1280.0L,1536.0H,1792.0L",
    "HLDEC" :"H256.0, L512.0, H768.0,L1024.0,H1280.0,L1536.0, H1792.0",
    "LHDEC" :"L256.0, H512.0, L768.0,H1024.0,L1280.0,H1536.0,L1792.0",

其中容易造成混淆的是LE、BE、HEXBE、HEXLE四种。

LE格式: "07000001000200030004000500060007"

0700–> BCD码相当于16进制0x0007,表示后面的电平个数,其中前后字节要倒换

0001–> BCD码相当于16进制0x0100,其中前后字节要倒换

0002–> BCD码相当于16进制0x0200,其中前后字节要倒换

BE格式: "00070100020003000400050006000700"

0007–> BCD码相当于16进制0x0007, 表示后面的电平个数

0100–> BCD码相当于16进制0x0100

0200–> BCD码相当于16进制0x0200

HEXLE和LE的区别是不含头四位的电平个数值

HEXBE和BE的区别是不含头四位的电平个数值

返回


< 200
< {
    "action": "IRA1",                                   // 返回服务类,请求成功返回IRA1,否则返回IRA0
    "irdaInfo": [                                       // 红外信息集,匹配请求可以返回多个红外类型信息
        {
            "typeId": "T01001",                         // 红外码类型
            "brand": "飞利浦",                           // 品牌
            "devType": "TV",                            // 设备类型
            "status": "T_P-",                           // 设备状态
            "bcchno": "38",                             // 载波频率
            "fixedCode": ""                             // 固定码
        },
        {
            "typeId": "",
            "brand": "",
            "devType": "",
            "status": "",
            "bcchno": "",
            "fixedCode": ""
        }
    ]
}

status 具体说明:

  • 如果不是空调遥控器,则为对应遥控器的单一按键指令。如果是空调遥控器,则状态值为6位16进制数字。

如(100811 解析--状态:开;模式:自动;温度:24度;风速:低风;风向:手动):

  • 开关(第1位), 模式(第2位) 温度(第3,4位),风量(第5位), 风向(第6位)。各位的值范围和含义:

    开关: 0-1; 0->关, 1->开,其他保留

    模式: 0-4; 0->自动,1->制冷, 2->制热,3->抽湿, 4->送风,F保持原来状态,其他保留

    温度: 00-10; 00->16度, 0F->31, 10->32度,FF保持原来状态, 其他保留

    风量: 0-3; 0->自动,1->低, 2->中, 3->高,F保持原来状态,其他保留

    风向: 0-4 0->自动,位置:1-4摆风,F保持原来状态,其他保留

fixedCode 具体说明:

  • 固定码:一个红外编码类型对应有一个红外固定码。主要是红外编码中固定不变的内容,其包括有载波频率,引导码,0/1码格式,停止码。固定码需要和指令编码一起使用,最终换算出原始红外编码。

4.6.6 红外指令集合请求


curl -v -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    "https://user-openapi.hekr.me/irdainfo" \
    -d '{
        "action" :"IRB0",                               // 请求服务类IRA0
        "typeId" : "100001"                             // 红外类型
    }'

返回


< 200
< {
    "action" :"IRB1",                                   // 返回服务类,请求成功返回IRB1,否则返回IRB0
    "high" :"141035",                                   // 指令组合最大值(只有空调类遥控有返回)  
    "low" :"000000",                                    // 指令组合最小值(只有空调类遥控有返回
    "temperature" :[16,30],                             // 空调温度范围如上范围[16,30],即是16到30度(只有空调类遥控有返回
    // 编码集合
    "set" :[
        {
            "inst" :"T_ONOFF",                          // 指令
            // 红外编码
            "code" :"013f006e0a7903bc01bc01bc01bc01bc017903bc01790335057803bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc01bc0178037803bc01bc01bc01bc01bc01bc017803780378037803bc01bc017803bc01bc017803bc01bc01bc01bc01bc01bc01bc01bc017803bc01bc017803bc01bc01bc01",
            "instCode" :""                              // 指令编码
        },
        {
            "inst" :"T_*",
            "code" :"",
            "instCode" :""
        }
    ]
}  

code红外编码解析:

  • 开始是2个数写成16进制数为0x01,表示发送次数,例如:01表示发送1次。

  • 后面4个数表示电平数量:e600 == 0x00e6。

  • 后续的每4个数为一组,16进制little ending,表示电平长度,第一个电平是高电平。

instCode 指令编码解析:

  • 指令编码,每条指令对应一条指令编码,其和固定码一起换算出红外编码。

inst指令具体说明:

  • 空调指令如上述status解析。注意此时指令的每个状态都需确定。

  • 常见电视指令:

指令 解析 指令 解析
T_ONOFF 开/关 T_D0 数字0
T_AVTV AV/TV T_D1 数字1
T_P+ 频道+ T_D2 数字2
T_P- 频道- T_D3 数字3
T_V+ 声音+ T_D4 数字4
T_V- 声音- T_D5 数字5
T_OK 确认 T_D6 数字6
T_UP T_D7 数字7
T_DOWN T_D8 数字8
T_LEFT T_D9 数字9
T_RIGHT T_MUTE 静音
T_MENU 菜单
T_RETURN 返回
注意: 有些遥控器指令是反转的,指令集里的表示会有T0_ONOFF,T0_AVTV ... 和 T1_ONOFF,T1_AVTV ... 。这表示按下按键这次发T0,再按下按键须发T1,再按下发T0 ... ,如此来回循环

4.7 群组API

4.7.1 创建群组

创建新的群组,一个用户最多只能建立10个群组。


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group" \
    -d '
      {
          "groupName": "走廊灯组",
          "deviceList" : [
            // 至少有一个设备
            {
              "devTid":"ESP_X01",
              "ctrlKey": "xxxx"
            },
            {
              "devTid":"ESP_X02",
              "ctrlKey": "yyyy"
              }
          ]
          "desc" : "xxxx"
      }
    '

参数

参数名 是否可选 参数类型 取值范围 说明
groupName 必选 String 长度[1,128] 群组名称
deviceList 必选 List 列表长度[1,512] 创建群组里含有的设备名称列表,至少需要一个设备
devTid 必选 String 设备唯一ID
ctrlKey 必选 String 设备控制码
desc 必选 String 长度[1, 128] 群组描述

返回


> 201
> {
      "groupName": "走廊灯",
      "groupId" : "xxxxx",
      "deviceList" : [
        {
          "devTid":"ESP_X01",
          "ctrlKey": "xxxx"
        },
        {
          "devTid":"ESP_X02",
          "ctrlKey": "yyyy"
          }
      ],
      "desc" : "xxxx",
      "createTime": 1462347208990,
      "updateTime": null,
      "groupMid": "01d838"
  }

4.7.2 列举群组


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group?groupId=xxx"

参数

参数名 是否可选 参数类型 取值范围 说明
groupId 可选 String 长度[1,128] 群组ID

返回


> 200
> [
    {
      "groupName": "走廊灯小组",
      "groupId" : "xxxxx",
      "deviceList" : [
        {
          "devTid":"ESP_X01",
          "ctrlKey": "xxxx"
        },
        {
          "devTid":"ESP_X02",
          "ctrlKey": "yyyy"
          }
      ],
      "desc" : "xxxx",
      "createTime" : 14xxxx,
      "updateTime" : 14xxxx,
      "groupMid": "01db28"
    }, ...
  ]

4.7.3 群组改名


curl -v -X PUT \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group/{groupId}" \
    -d '{
      "newGroupName" : "新的组名"
      }'

参数

参数名 是否可选 参数类型 取值范围 说明
groupId 必选 String 群组ID
newGroupName 必选 String 长度[1,128] 群组新的名称

返回


< 204
< No Content

4.7.4 删除群组


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json " \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group?groupId=xxx"

参数

参数名 是否可选 参数类型 取值范围 说明
groupId 必选 String 群组ID

返回


< 204
< No Content

4.7.5 增加设备到群组


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group/{groupId}" \
    -d '[
          // 添加多个
          {
            "ctrlKey": "704973e8d3a34dcc",
            "devTid": "jwpbghi"
          },
          ...
      ]'

参数

参数名 是否可选 参数类型 取值范围 说明
groupId 必选 String 群组ID
devTid 必选 String 设备唯一ID
ctrlKey 必选 String 设备控制码

返回


< 201
< no content

4.7.6 将设备从群组中删除


curl -v -X DELETE \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json " \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/group/{groupId}"
    -d '[
       // 支持删除多个
      {
        "ctrlKey" : "xxxx",
        "devTid" : "xxx"
      },
      ...
    ]'

参数

参数名 是否可选 参数类型 取值范围 说明
groupId 必选 String 群组ID
devTid 必选 String 设备唯一ID
ctrlKey 必选 String 设备控制码

返回


< 204
< No Content

4.8 场景API

4.8.1 列举默认场景推荐



curl -v -X GET \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
       "https://user-openapi.hekr.me/sceneTemplate?templateId=2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9"

参数

参数名 是否可选 参数类型 取值范围 说明
templateId 可选 String 模板ID

返回


< 200
  < [
      {
        "templateId":"2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9"
        "pid" : xxx,
        "name" : "场景",
        "sceneTaskList": [
                {
                   "taskId": "7440ba09-2969-4ed0",
                   "desc": "开客厅所有灯",
                   "cmdArgs": {
                       "devTid": "third test-14-47-15",
                       "ctrlKey": "xxx"
                        },
                   "groupId": "123456789"
                 }
              ],
        "desc": null,
        "createTime": 1482135729797,
        "updateTime": null
      },
      ......
  ]

4.8.2 自定义场景创建/根据模板创建场景

每个app创建的场景模板不能超过20个


curl -v -X POST \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        "https://user-openapi.hekr.me/scene"
        -d '{
            "sceneName" : "回家场景",
            "sceneTaskList" : [
                 // 组控操作
                 {
                    "desc":"开客厅所有灯",
                    "cmdArgs" : {
                        "cmdId" : 1,
                        "key1" : "value"
                    },
                    "groupId":"123456789"
                 },
                 // 设备操作
                 {
                    "desc":"开电视",
                    "cmdArgs" : {
                        "raw": "48070200010153"
                    },
                    "devTid":"third test-14-47-15",
                    "ctrlKey":"xxz"
                 },
                 // 子设备操作
                 {
                    "desc":"打开窗帘",
                    "cmdArgs" : {
                        "cmdId" : 1,
                        "key1" : "value"
                    },
                    "subDevTid":"sub-2016-08-17T20-21-42",
                    "devTid":"third test-14-47-15",
                    "ctrlKey":"xxx"
                 },
                 // 延迟时间
                 {
                    "desc":"延时3s",
                    "time": 3

                 },
                 // 联动使能
                 {
                    "desc":"联动",
                    "iftttId" : "123123123123",
                    "enable": "ENABLE" .  //ENABLE / DISABLE( 开/关)
                 },
                 // 推送
                 {
                    "desc" : "场景推送"
                    "templateId":"xxx",
                    "params": ["1","2"]     // 场景推送模板中的参数
                    "cmdArgs":{             // 推送是hideParam 参数
                        "key1":"value1",
                        "key2":"value2"
                    }
                 }
            ]
        }'

参数

参数名 是否可选 参数类型 取值范围 说明
sceneName 必选 String 场景名称,不能创建已有名称
sceneTaskList 必选 List 场景中需要执行的任务列表,SceneTask所传参数,根据不同的执行动作参数不同,请参照curl命令中的参数示例添加

返回


< 201
   < {
    "sceneId" : "98e8b004-f288-4e81-ae31-fefec8457732",
    "sceneName" : "scene_fivth",
    "uid" : "10894587829",
    "sceneTaskList" : [
        {
            "devTid" : "2016-08-17T20-21-42",
            "ctrlKey" : "xxx",
            "taskId" :  "bc5a900a-195b-430c-94",
            "desc" : "开门",
            "cmdArgs" : {
                "cmdId" : 1,
                "power" : 1
            }
        },
        {
            "iftttId" : "effdd6a0-5b67-486b-8e14-fe6606d10c7d",
            "enable" : "ENABLE",
            "taskId" : "51658b37-c35a-437c-b5ae-24ddc011ed11",
            "desc" : "开启联动"
        },
        {
            "time" : 3,
            "taskId" : "148de23b-f528-4352-b814-9510c446a86b",
            "desc" : "延迟时间"
        },
        {
            "templateId" : "00000000012",
            "params" : [
                "1"
            ],
            "taskId" : "3b73ead6-55d9-418a-a831-e03e70536eeb",
            "desc" : "场景推送"
        }
    ],
    "createTime" : ISODate("2016-12-22T08:22:57.230Z")
  }

4.8.3 列举场景详情


curl -v -X GET \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
        "https://user-openapi.hekr.me/scene?scenceId=2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9&sceneName=场景"

参数

参数名 是否可选 参数类型 取值范围 说明
sceneId 可选 String 场景ID
sceneName 可选 String 场景名称

返回



< 200
  < [
      {
        "sceneId":"2b4df4b2-fd7b-4a7a-a519-6ecf7ced9ab9"
        "uid" : xxx,
        "name" : "场景",
        "sceneTaskList": [
                {
                   "taskId": "7440ba09-2969-4303-86f6ed0",
                   "desc": "开客厅所有灯",
                   "cmdArgs": {
                       "devTid": "third test-14-47-15",
                       "ctrlKey": "xxxx"
                        },
                   "groupId": "123456789"
                 }
              ],
        "desc": null,
        "createTime": 1482135729797,
        "updateTime": null
      },
      ......
  ]


4.8.4 删除场景


curl -v -X DELETE \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        "https://user-openapi.hekr.me/scene/{sceneId}"

参数

参数名 是否可选 参数类型 取值范围 说明
sceneId 必选 String 场景ID

返回


< 204
< No Content

4.8.5 场景更新


curl -v -X PATCH \
        -H "Authorization: Bearer {JWT_TOKEN}" \
        -H "Accept: application/json" \
        "https://user-openapi.hekr.me/scene/{sceneId}"
        -d '{
            "sceneName" : "回家场景",
            "sceneTaskList" : [
                 同4.8.2所列参数
            ]
        }'

参数

参数名 是否可选 参数类型 取值范围 说明
sceneId 必选 String 场景ID
sceneName 可选 String 场景名称,不能修改成除本身外己有的名称
sceneTaskList 必选 List 场景中需要执行的任务列表,SceneTask所传参数,根据不同的执行动作参数不同,请参照4.8.2curl命令中的参数示例添加

返回


< 204
< No Content

4.8.6 查询场景执行结果历史记录


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://user-openapi.hekr.me/sceneExcuteHistory?sceneId=xxx&sceneName=回家&result=true&startTime=2016-01-01T09:45:00.000+0800&endTime=2017-01-01T09:45:00.000+0800"

参数

参数名 是否可选 参数类型 取值范围 说明
sceneId 可选 String 场景ID
sceneName 可选 String 场景name
result 可选 Boolean true/false 执行结果
startTime 必选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询起始时间
endTime 可选 String yyyy-MM-ddTHH:mm:ss.SSSZ 例如 2001-07-04T12:08:56.235-0700 查询结束时间
page 可选 Int [0, ?] 分页参数,默认为0
size 可选 Int [1, 20] 分页参数,默认为20

返回


< 200
< {
    "content": [
        {
        "objectId": {
            "time": 1490003369000,
            "timestamp": 1490003369,
            "date": 1490003369000,
            "timeSecond": 1490003369,
            "machine": -458185787,
            "inc": -1003867645,
            "new": false
        },
        "sceneId": "cc27ec7b-21a7-404c-b930-5da131",
        "uid": "xxxx",
        "origin": "DIRECT",
        "sceneTaskExecuteDetails": [
            {
            "sceneExecuteAck": "PENDING",
            "sceneId": "cc27ec7b-21a7-404c-b930-5da131",
            "sceneTaskId": "b7731ef7-7eef-4a71-b67f-49242225e219"
            },
            {
            "sceneExecuteAck": "PENDING",
            "sceneId": "cc27ec7b-21a7-404c-b930-5da19c66e331",
            "sceneTaskId": "2bd42bd9-6bac-4017-8bd2-3b49041ef17e"
            },
            ......
        ],
        "sceneName": "外出场景",
        "result": true,
        "executeTime": 1490003369443,
        "desc": "[scene execute Succeed]"
        }
    ],
    "last": false,
    "totalElements": 769,
    "totalPages": 769,
    "numberOfElements": 1,
    "sort": [
        {
        "direction": "DESC",
        "property": "executeTime",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": false
        }
    ],
    "first": true,
    "size": 20,
    "number": 0
  }

错误码表

错误码 提示信息 中文释义 可能造成的原因
5200000, 620000 Success 成功
5400000 Error 未知错误 该行下面的以5400、6400开头的错误码需要单独处理
5400002 App repeat login error app重复登录 同一个appTid的app重复登录
5400003 appTid can not be empty appTid不能为空 appTid不能为空
5400004 Authorization already exists 授权关系已存在 授权关系已存在
5400005 Authorization does not exist 授权关系不存在 授权关系不存在
5400006 Bind failed due to network error 因网络原因绑定失败 因网络原因绑定失败
5400007 Bind failed due to timeout error 因超时原因绑定失败 因超时原因绑定失败
5400008 Can not bind other manufacture's device 无法绑定其他厂商设备 非公版用户无法绑定非该pid设备
5400009 Modified user profile failed 修改用户档案失败 修改用户档案失败
5400010 Check verify code error 校验code失败 校验code失败
5400011 You have reached your device's authorization limits 设备授权次数达到上限 设备授权次数达到上限,无法再次授权
5400012 Bind failed due to internal error 因内部错误绑定失败 因内部错误绑定失败,一般是因为bindKey不对或者是devTid不对
5400013 Bind failed due to repeat bind 因重复绑定绑定失败 因重复绑定绑定失败
5400014 Device does not belong to user 设备不属于用户 设备不再属于该用户
5400015 No such instruction error 没有这样的指令 没有这样的指令
5400016 Device can not repeat login 设备无法重复登录 设备无法同时登录
5400017 devTid can not be empty devTid不能为空 devTid不能为空
5400018 Create timer task failed due to counts reach limit 创建定时预约次数达到上限 创建定时预约次数达到上限
5400019 Instruction expired 授权的指令已过期 授权的指令已过期
5400020 Instruction not support 不支持该指令 不支持该指令,可能是指令填错了
5400021 Invalid email token 不合法的邮件token 不合法的邮件token
5400022 Invalid old password 不合法的旧密码 不合法的旧密码
5400023 Invalid verify code 不合法的校验code 不合法的校验code
5400024 Device does not found due to internal error, please reconnect 由于内部错误设备无法找到,请重连
5400025 No such manufacture id 不存在该pid 不存在该pid
5400026 No permission to access the instruction 没有对该指令的权限 没有对该指令的权限
5400027 Template with given id does not exist 指定模板不存在 指定模板不存在
5400028 Device does not found due to incorrect status 由于内部不正确的状态导致设备无法被找到
5400035 TaskId does not exist 指定任务不存在 指定任务不存在
5400036 Can not create duplicate template 无法创建重复模板 无法创建重复模板
5400037 devTid not match 设备id 不匹配 报文填写的devTid与登录设备的devTid不一致
5400039 User does not exist 用户不存在 用户不存在
5400043 Device can not force bind 设备无法强制绑定 设备无法强制绑定
5500000 Internal error 内部错误 内部服务错误
6400001 Reverse auth template with given id does not exist 指定id的反向注册申请不存在 请求已经被同意或拒绝
6400002 Invalid reverse authorization request 不合法的反向授权请求 设备此时已经不属于该授权者;调用者不是授权者;反向授权请求id错误
6400003 Only owner can authorize 只有属主可以授权设备给其他人 非属主尝试授权设备给其他人
6400004 Device with given devTid does not exist 指定devTid的设备不存在 操作不存在的设备
6400005 Reached the maximum number of device the folder can hold 达到文件夹所能容纳设备数量的上限 达到文件夹所能容纳设备数量的上限
6400006 Can not create duplicate template folder 无法创建同名文件夹 创建同名文件夹
6400007 Folder with given id does not exist 指定id的文件夹不存在 操作不存在的文件夹
6400008 Reached the maximum number of folder the user can create 达到创建文件夹数量上限 达到创建文件夹数量上限
6400009 Can not remove root folder 无法删除根目录 删除根目录
6400010 Can not rename root folder 无法给根目录改名 给根目录改名
6400011 Rule with given id does not exist 指定的规则不存在 操作不存在的规则
6400012 Scheduler task with given id does not exist 指定的定时预约任务不存在 操作不存在的定时预约任务
6400013 Can not create duplicate rule 无法创建相同的规则 创建相同的规则
6400014 Can not create duplicate scheduler task 无法创建相同的定时预约 创建相同的定时预约
6400015 Invalid prodPubKey 不合法的prodPubKey 不合法的prodPubKey
6400016 Has no privilege do that 没有权限这样做 操作没有权限
6400017 Invalid Param {0} 参数错误 请求参数错误
6400018 Cloud storage file with given name does not exist 指定的网盘文件不存在 操作不存在的网盘文件
6400020 Can not find this infrared code 找不到这个红外码 操作不存在的红外码
6400021 Infrared code request without response 红外服务请求出错
6400022 Can not find instruction set 无法找到指令集 操作不存在的指令集
6400023 Request params not supported 参数不支持 请求参数错误
6400024 Translating Json to String failure 解析json失败
6400025 Scheduler not supported 不支持定时预约 该设备不支持定时预约功能
6500001 Delete cloud storage file failed 删除网盘文件失败 网盘操作失败
6500002 Upload cloud storage file failed 上传网盘文件失败 网盘操作失败
6500003 Server use httpClient invoke failed http网络调用失败 http调用失败

5. 企业API

服务地址

域名:端口 功能 协议 数据安全级别 服务区域
console-openapi.hekr.me:80 云端用户API HTTP 非SSL 全球

错误返回方式说明

调用接口成功返回20X,如有返回内容会在body中给出,没有返回内容body将为空,仅有HTTP头。

调用接口失败返回40X或500,错误信息会在body中给出。

如果返回的HTTP Code是401,请检查请求头是否正确。

如果接口需要使用参数ppk,并且ppk不合法,将返回错误码:6400015。

如果请求参数不合法或者错误,将返回错误码:8400002。

5.1 判断设备模块固件是否需要升级


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/device/fw/ota/check" \
    -d '[
        {
            "devTid" : "esp_2m_bb8",                    // 设备id
            // 产品公开码
            "productPublicKey" : "56dce943d4149",
            "binType" : "A",                            // 固件类型
            "binVer" : "2.0.3.0"                        // 固件版本
        },
        {
            "devTid" : "esp_2m_bb9",
            "productPublicKey" : "56dcf1b5d14e",
            "binType" : "B",
            "binVer" : "1.2.0.0"
        }
    ]'

返回

如果productPublicKey不合法,将不返回相应任何设备信息。


< 200
< [
    {
        "devTid" : "esp_2m_bb8",
        "update" : false                                // 是否需要升级:true,是;false,否
    },
    {
        "devTid" : "esp_2m_bb9",                      
        "update" : true,
        "devFirmwareOTARawRuleVO" : {                   // 如果需要升级,该值非空
            // 新固件地址
            "binUrl" : "http://fs.hekr.me/dev/fw/ota/xxx.bin",
            "md5" : "5d41402abc4b2a76b9719d911017c592", // 固件md5  
            "latestBinType" : "B",                      // 新固件类型
            "latestBinVer" : "1.2.3.4",                 // 新固件版本
            "size" : 77                                 // 固件大小,单位Byte
        }
    }
]

5.2 根据pid获取企业资讯


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/vc/getByPid?pid=12121212121&page=5&size=1"

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 企业id
page 可选 int [0, ?],默认为是0 页码
size 可选 int [1, 100],默认是20 每页大小

返回


< 200
< {
    "page" : 5,
    "size" : 1,
    "totalResults" : 117,
    "totalPages" : 117,
    "first" : false,
    "last" : false,
    "result" : [
        {
        "id" : "56de99337d845ab213487607",               // 资讯id
        "authorName" : "健康小助手",                  
        "updateTime" : 1457611920,
        "title" : "每日饮水小贴士",
        "infoTags" : [                                  // 资讯标签
            "健康",
            "饮水"
        ],
        // 资讯url
        "infoContent" : "http://media.hekr.me/pid/vc/xxxx.html"
        }
    ]
}

5.3 根据ppk获取企业资讯

该接口支持根据ppk列表批量获取企业资讯(企业资讯按最后更新时间倒序排序)。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Hekr-ProdPubKey: {ppk}" \
    "https://console-openapi.hekr.me/external/vc/getByPPK?page=5&size=1"

参数

参数名 是否可选 参数类型 取值范围 说明
page 可选 int [0, ?],默认是0 获取第几页的企业资讯
size 可选 int [1, 100],默认是20 每页企业资讯的数量

返回


< 200
< 同 5.2 格式

5.4 售后管理 - 获取反馈问题分类


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ppk}" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/feedbackType"

返回


< 200
< [
    {
        "id" : "56dd3c1fce1a8abe539b78ee",
        "type" : "APP界面不好看"                             // 分类名称
    }
]

5.5 售后管理 - 针对设备反馈问题


curl -v -X POST \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "X-Hekr-ProdPubKey: {ppk}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/feedback"
    -d '{
        "username" : "example@hekr.me",
        "title" : "温度统计不灵",
        "typeId" : "56de99337d845ab213487607",
        "content" : "温度统计功能,时灵时不灵...",    // 具体的反馈内容
        // 反馈内容如有图片,则存放图片链接,多张图片以","分隔。如果没有图片,可以不填
        "images" : "http://media.hekr.me/xx1.png,http://media.hekr.me/xx2.png"
    }'

返回

如果username不存在,将不返回任何信息。


< 200
< {
    "id" : "56de96dd46ea0f809999b8cc"    // 反馈问题的id
}

5.6 售后管理 - 批量获取用户的反馈问题和问题处理结果


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/user/feedback?page=10&size=2"

参数

参数名 是否可选 参数类型 取值范围 说明
page 可选 int [0, ?],默认是0 获取第几页的反馈问题
size 可选 int [1, 100],默认是20 每页问题的数量

返回


< 200
< {
  "page": 5,
  "size": 2,
  "totalResults": 20,
  "totalPages": 10,
  "first": false,
  "last": false,
  "result": [
    {
      "id": "56de959d84ef43a521757054",
      "title": "设备无法控制",
      "type": "产品质量",
      "content": "我的设备无法控制",
      "handleStatus": 1,
      "createTime": 1457947833
    },
    {
      "id": "56de626884efc280586a5fd6",
      "title": "设备无法获取PM2.5的值",
      "type": "产品功能不可用",
      "content": "我的设备无法获取PM2.5的值",
      "images": "http://media.hekr.me/xx1.png",
      "handleTime": 1456874520,
      "handleContent": "请将设备的保护薄膜撕掉",
      "handleStatus": 2,
      "createTime": 1456824900
    }
  ]
}

5.7 售后管理 - 获取厂商提供的常见问题


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Hekr-ProdPubKey: {ppk}" \
    "https://console-openapi.hekr.me/external/faq/list?page=1&size=10"

参数

参数名 是否可选 参数类型 取值范围 说明
page 可选 int [0, ?],默认是0 页码
size 可选 int [1, 100],默认是20 分页大小

返回


< 200
< {
    "page" : 5,
    "size" : 1,
    "totalResults" : 117,
    "totalPages" : 117,
    "first" : false,
    "last" : false,
    "result" : [
        {
            "id" : "56de99337d845ab213487607",
            "productName" : "xxxx",
            "title" : "xxxx使用规范",
            "username" : "yyyy",
            "content" : "健康",
            "updateTime" : 1457611920
        }
    ]
}

5.8 获取APP H5模板

如果APP采用纯H5页面开发模式,可以通过该接口获取APP H5模板。


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/app/h5/template?pid=12121212121"

参数

参数名 是否可选 参数类型 取值范围 说明
pid 必选 String 企业id

返回


{
    // zip地址
    "url" : "http://media.hekr.me/h5/template/android/xxx.zip",
    // zip包中解压文件的路径前缀,注意返回的前缀最后不带斜杠“/”
    "urlPathParam" : "http://media.hekr.me/h5/template/f84fb91d54664ccd861e4ad2aa335579",
    // 更新时间
    "updateTime" : 1456824900
}

5.9 获取产品协议模板


curl -v -X GET \
  -H "Accept: application/json" \
  -H "X-Hekr-ProdPubKey: {productPublicKey}" \
  "https://console-openapi.hekr.me/external/device/protocolTemplate"

返回


< 200
< {
    "mid": "1ccb5e2ed8",
    "pid": "062801590",
    "cid": "02af881daf",
    "accessProtocol": 0,                                // 设备工作方式: 0是JSON透传、1是JSON主控
    "fixedLength": false,                               // 是否是定长
    "statistics": false,                                // 是否需要统计
    "createTime": "2016-02-22 16:15:47",
    "protocol": {                                       // 协议命令集合
        "3": {                                          // 命令的key,与具体命令中的cmdId保持一致
            "cmdTag": "SetLight",                       // 命令名称
            "cmdId": 3,                                 // 命令的Id
            "desc": "设置亮度",                          // 命令描述
            "frameType": 2,                             // 命令帧类型:1是上报帧、2是下发帧
            "usedForIFTTT": true,                       // 是否在IFTTT规则中展示
            "fields": [                                 // 命令使用到的产品参数
                {
                    "name": "Light",                    // 参数名称
                    "desc": "亮度",                     // 参数描述
                    "units": "百分比",                  // 参数单位,可选
                    "unitsDesc": "%",                   // 参数单位的符号表示,可选
                    "dataType": "INT",                  // 参数的数据类型,JSON主控包括“INT”、“FLOAT”、“STRING”,JOSN透传包括“NUMBER”、“STRING”
                    "dataLength": 1,                    // 数据长度,单位“Byte”,JSON透传下有该属性,JSON主控下无该属性
                    "save": true,                       // 云端是否保存该参数的值
                    "reportedFrequency": 5,             // 该参数上报云端的频率,单位是“分钟/次”,即多少分钟上报一次该参数
                    "available": true,                  // 该参数在此命令中是否是有效数据
                    "usedForIFTTT": true,               // 是否在IFTTT规则中展示
                    "maxValue": "100",                  // 参数的最大取值
                    "minValue": "0",                    // 参数的最小取值
                    "maxValueMean": "亮度100%",          // 参数最大值的含义,可选
                    "minValueMean": "亮度0%",            // 参数最小值的含义,可选
                    "enumeration": [                    // 参数的枚举值,可选
                        {
                            "value": 150,               // 参数的枚举取值
                            "desc": "超亮状态"           // 枚举取值说明
                        }
                    ]
                }
            ]
        }
    }
}

5.10 获取默认演示设备


curl -v -X GET \
    -H "Authorization: Bearer {JWT_TOKEN}" \
    -H "Accept: application/json" \
    "https://console-openapi.hekr.me/external/device/default/static"

返回


< 200
< [
      {
        "deviceName": "dev1",
        "logo": "http://example.com/example1.png",
        "desc": "first vir dev",
        "androidH5Page": "http://example.com/index.html",
        "iosH5Page": "http://example.com/index.html"
      },
      {
        "deviceName": "dev2",
        "logo": "http://example.com/example2.png",
        "desc": "second vir dev",
        "androidH5Page": "http://example.com/index.html",
        "iosH5Page": "http://example.com/index.html"
      }
]

错误码表

错误码 提示信息 中文释义 可能造成的原因
8200000 Success 调用成功
8400000 Product does not exist 产品不存在
8400001 Protocol template does not exist 协议模板不存在
8400002 Illegal argument 非法参数
8400003 The param of platform is not illegal. The client should be Android or IOS 平台参数错误;应为Android或IOS
8400004 The pid does not exist 指定pid不存在
8400005 The h5 template does not exist h5模板不存在