接口文档（不推荐使用，未来可能会下线，请使用新版v2文档）

1. 授权相关

通用说明： 授权相关接口遵循标准OAuth 2.0授权规范，所有请求返回遵循HTTP请求状态的Http状态编码，在HTTP Status Code不为200的时候才返回相对应的错误提示

HTTP状态码说明：

HTTP Status Code	描述
200	OK
409	业务异常
4xx	请求错误，参考
500	服务器异常

返回结果：

字段	类型	说明
error	String	错误码
error_description	String	错误提示

返回示例：

{
    "error": "1000",
    "error_description": "system error"
}

1.1 授权码授权方案

1.1.1 获取授权页

接口说明： 根据颁发的clientId返回相应的授权登录页面，不同的clientId可能会产生不同的定制化页面，默认是美居登录页样式。获取美居标准授权需要用OAuth2授权方式，目前只支持response_type=code

请求协议： HTTPS

请求方式： GET

请求地址： /v1/open/oauth2/authorize

参数格式： query 参数

请求参数：

字段	必选	类型	说明
client_id	true	String	唯一的第三方开发者ID
state	true	String	请求授权方的校验字段，授权服务透传原值返回
response_type	true	String	授权类型 code - 授权码方式
redirect_url	false	String	重定向 URI

请求示例：

/v1/open/oauth2/authorize?client_id=client_id********************1234&state=1&response_type=code

返回结果：

返回登录页面，让用户输入用户名、密码

返回示例：

1.1.2 获取令牌

接口说明： 该接口获取或刷新AccessToken

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/oauth2/token2

参数格式： body 参数

请求参数：

字段	必选	类型	说明
client_id	true	String	唯一的第三方开发者ID
client_secret	true	String	第三方开发者密钥
grant_type	false	String	使用的授权模式，获取/刷新AccessToken分别传值如下。 获取：authorization_code 刷新：refresh_token
code	false	String	上一步获得的授权码，grant_type为authorization_code时需要
refresh_token	false	String	上一步获得的refresh_token，grant_type为refresh_token时需要

请求示例：

{
  "client_id": "client_id********************1234",
  "grant_type": "authorization_code",
  "client_secret": "client_secret******************abcd",
  "code": "code*****************45678"
}

返回结果：

字段	类型	说明
access_token	String	访问令牌
expires_in	Integer	令牌有效期
refresh_token	String	刷新令牌
token_type	String	令牌类型

返回示例：

{
  "access_token": "access_token***************1234",
  "expires_in": 7200,
  "refresh_token": "refresh_token****************abcd",
  "token_type": "bearer"
}

1.2 扫码授权方案

1.2.1 获取授权二维码

接口说明： 设备发起请求获取二维码信息

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/user/qrcode/get

参数格式： body 参数

请求参数：

字段	必选	类型	说明
clientId	true	String	唯一的第三方开发者ID
reqId	true	String	请求ID
uuid	true	String	加密后的第三方开放用户唯一标识 加密方式：AES128(uuid,MD5(client_sec).substring(0,16))
responseType	true	String	授权类型 code - 扫码授权
state	false	String	请求授权方的校验字段，授权服务透传原值返回

请求示例：

{
  "clientId": "clientId*************************1234",
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "uuid": "423wtwet34342346796ikfjdr68e",
  "responseType": "code",
  "state": "MIDEA"
}

返回结果：

字段	类型	说明
reqId	String	请求Id
qrcode	String	二维码信息

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "qrcode": "http://iot4.midea.com.cn/downloads/app?type=auth&qrcodeToken=qrcodeToken*****************1234&clientId=clientId**************abcd&uuid=25345ui5i34ih5hllhi2yf253365285r&responseType=qrcode&expired=600&state=MIDEA"
}

1.2.2 获取令牌

接口说明： 该接口获取或刷新AccessToken

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/oauth2/token2

参数格式： body 参数

请求参数：

字段	必选	类型	说明
client_id	true	String	唯一的第三方开发者ID
client_secret	true	String	第三方开发者密钥
grant_type	false	String	使用的授权模式，获取/刷新AccessToken分别传值如下。 获取：authorization_code 刷新：refresh_token
code	false	String	美居成功扫码后给回的授权码，grant_type为authorization_code时需要
refresh_token	false	String	上一步获得的refresh_token，grant_type为refresh_token时需要

请求示例：

{
  "client_id": "client_id********************1234",
  "client_secret": "client_secret******************abcd",
  "grant_type": "authorization_code",
  "code": "code******************abcd"
}

返回结果：

字段	类型	说明
access_token	String	访问令牌
expires_in	Integer	令牌有效期
refresh_token	String	刷新令牌
token_type	String	令牌类型

返回示例：

{
  "access_token": "access_token***************1234",
  "expires_in": 7200,
  "refresh_token": "refresh_token****************abcd",
  "token_type": "bearer"
}

1.3 取消授权

接口说明： 取消当前access token的授权

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/user/cancel

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
openUid	false	String	第三方开放用户唯一标识
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID

返回示例：

{
  "reqId": "b3540cc225bbf99dd789609edef91edd"
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法

1.4 获取用户基本信息

接口说明： 获取美居开放的用户信息以及家庭信息

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/user/get

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
openUid	String	用户ID
userName	String	用户名称
homegroupList	List	用户创建的家庭列表（不包含加入的家庭）
homegroupId	Long	用户创建的家庭ID
homegroupName	String	用户创建的家庭名字

返回示例：

{
  "openUid": "b3540cc225bbf99dd789609edef91edd",
  "userName": "小明",
  "homegroupList": [{
    "homegroupId": 3121311,
    "homegroupName": "我的家1"
  }, {
    "homegroupId": 3121312,
    "homegroupName": "我的家2"
  }]
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法

2. 设备控制相关

2.1 获取设备列表

接口说明： 该接口用于获取用户名下的设备列表

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/list/get

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
homegroupId	false	String	家庭ID，传入查询指定家庭下的设备
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
applianceList	JSONArray	设备列表
modelNumber	String	设备子型号
applianceCode	String	设备虚拟ID，用于设备相关操作
type	List	设备类型
name	String	设备名称
onlineStatus	String	设备在线状态，1为在线，0为离线

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "applianceList": [{
    "applianceCode": "17592186044420",
    "type": "0xAC",
    "name": "客厅空调",
    "modelNumber": "1",
    "onlineStatus": "1"
  }]
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法

2.2 绑定设备

接口说明： 该接口用于绑定设备，需要结合美居配网用的OpenSDK

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/bind

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
bindType	false	String	绑定类型，默认AP配网可不传，例如大屏扫码的类型为qrcode
qrcodeToken	false	String	扫描的二维码字符串，bindType为qrcode时必传
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	false	String	设备虚拟ID，bindType不传或者为ap时必传
verificationCode	false	String	验证码，bindType不传或者为ap时必传
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420",
  "verificationCode": "000100",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01"
}

错误码说明：

error	说明
1000	未知系统错误
1300	设备不存在
1307	设备离线
1383	绑定超时（设备连接上云端到绑定操作时间间隔不能大于60s）

2.3 解绑设备

接口说明： 该接口用于绑定设备

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/unbind

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	false	String	设备虚拟ID，bindType不传或者为ap时必传
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01"
}

错误码说明：

error	说明
1000	未知系统错误
1300	设备不存在
1304	设备不属于此用户

2.4 控制设备

接口说明： 该接口用于发送控制设备指令至设备

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/lua/control

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	false	String	设备虚拟ID，bindType不传或者为ap时必传
command	true	String	设备控制命令，内容需要进行转义 示例："{\"control\":{\"power\":\"on\"}}" 注：control为控制设备指令，格式为JSON字符串，具体指令请联系不同品类对接人
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420",
  "command": "{\"control\":{\"power\":\"on\"}}",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
status	Object	设备状态返回值

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "status": {
    "power": "on",
    "dry": "on"
  }
}

错误码说明：

error	说明
1000	未知系统错误
1300	设备不存在
1304	设备不属于此用户
1307	设备离线
1321	设备未确权

2.5 查询设备

接口说明： 该接口用于查询设备状态

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/status/lua/get

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	true	String	设备虚拟ID
command	true	String	设备查询,可查询全状态 示例："{"query":{}}" 注：query为控制设备指令，格式为JSON字符串，具体属性请联系不同品类对接人
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420",
  "command": "{\"query\":{}}",
  "sign": ""
}

返回结果：

字段	类型	说明
reqId	String	请求ID
status	Object	设备状态返回值

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "status": {
    "power": "on",
    "dry": "on"
  }
}

错误码说明：

error	说明
1000	未知系统错误
1300	设备不存在
1304	设备不属于此用户
1321	设备未确权

3. 设备通知相关

3.1 设备订阅

接口说明： 设备订阅接口，被订阅的设备才会有消息通知

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/subscribe

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	true	String	设备ID，以英文分号分隔开
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420;1099511824211;1099511824212",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01"
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法
1300	设备不存在

3.2 取消设备订阅

接口说明： 取消设备订阅，取消后第三方不会再收到这些设备的通知

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/device/subscribe/cancel

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
applianceCode	true	String	设备ID，以英文分号分隔开
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "applianceCode": "17592186044420;1099511824211;1099511824212",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01"
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法
1300	设备不存在

3.3 消息通知

接口说明： 此接口由第三方定义及实现，由美的云调用，用于通知设备订阅信息，接口鉴权方式由第三方定义，通知内容基于下面请求体定义

请求协议： HTTPS

请求方式： POST

请求地址： 由第三方定义，并提前注册到美的IoT开发者平台（申请开发者ID时）

参数格式： body 参数

请求头：

字段	必选	类型	说明
clientId	true	String	唯一的第三方开发者ID
signature	true	String	三方接口验签的签名字段 验签方式：Base64(HMAC_SHA_256(第三方开发者密钥clientSecret, HttpMethod["POST","GET"] + RequestURI["/X/XX/XXX"] + QueryString[如有] + 请求消息体bodyBytes的字符串(取UTF-8编码)))

请求参数：

字段	必选	类型	说明
header	true	Object	请求体头部
namespace	true	String	通知事件类型 ApplianceBind - 设备绑定 ApplianceUnbind - 设备解绑 ApplianceState - 设备状态
reqId	true	String	请求ID
stamp	true	String	请求时间戳，毫秒级区分
openUid	true	String	第三方用户ID
payload	true	Object	请求体负载，不同namespace时内容不同，下列示例中分别说明

设备绑定通知payload内容及示例：

字段	必选	类型	说明
appliance	true	Object	设备实体
name	true	String	设备名称
type	true	String	设备类型
applianceCode	true	String	设备ID
modelNumber	true	String	设备子型号

{
  "header": {
    "namespace": "ApplianceBind",
    "reqId": "1",
    "stamp": "201902251110111",
    "openUid": "123"
  },
  "payload": {
    "appliance": {
      "name": "空调A",
      "type": "0xAC",
      "applianceCode": "1099511824210",
      "modelNumber": "1"
    }
  }
}

设备解绑通知payload内容及示例：
​

字段	必选	类型	说明
applianceCode	true	String	设备ID

{
  "header": {
    "namespace": "ApplianceUnbind",
    "reqId": "1",
    "stamp": "201902251110111",
    "openUid": "123"
  },
  "payload": {
    "applianceCode":"1099511824210"
  }
}

设备状态通知payload内容及示例：
​

字段	必选	类型	说明
onlineStatus	true	String	设备在线状态，0代表离线，1代表在线
applianceCode	true	String	设备ID
status	true	Object	设备状态

{
  "header": {
    "namespace": "ApplianceState",
    "reqId": "1",
    "stamp": "201902251110111",
    "openUid": "123"
  },
  "payload": {
    "onlineStatus":"1",
    "applianceCode":"1099511824210",
    "status": {
      "power": "on",
      "light": "off",
      "dry": "on"
    }
  }
}

返回结果：

美的IoT开发者平台不处理

4. 场景相关

4.1 获取场景列表

接口说明： 获取美居家庭下的一键场景列表

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/scene/item/list

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
homegroupId	true	String	家庭ID，从用户信息接口中选择
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "homegroupId": "12099672",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
sceneList	List	场景列表
sceneId	String	场景ID
sceneType	String	场景类型 2 - 一键场景 注：目前云云对接只返回一键场景数据
sceneName	String	场景名称
enable	String	场景是否禁用 0 - 禁用 1 - 启用
homegroupId	String	家庭ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "sceneList": [{
    "sceneId": "4512121",
    "sceneType": "2",
    "sceneName": "回家",
    "enable": "1",
    "homegroupId": "12099672"
  }]
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法

4.2 获取场景详情

接口说明： 获取美居家庭下的一键场景详情

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/scene/item/get

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
sceneId	true	String	场景ID，从场景列表接口中选择
homegroupId	true	String	家庭ID，从用户信息接口中选择
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "sceneId": "4512121"
  "homegroupId": "12099672",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
sceneId	String	场景ID
sceneName	String	场景名称
enable	String	场景是否禁用 0 - 禁用 1 - 启用
homegroupId	String	家庭ID
applianceList	List	设备列表
applianceCode	String	设备虚拟ID
applianceName	String	设备名称
applianceType	String	设备类型
command	JSONObject	设备执行动作

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "sceneId": "4512121",
  "sceneName": "回家",
  "enable": "1"
  "applianceList": [{
    "applianceCode": "4565215",
    "applianceType": "0xAC",
  	"applianceName": "空调",
    "command": {
        "mode": "auto",
        "power": "on"
    }
  }]
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法

4.3 执行场景

接口说明： 执行场景

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/scene/item/execute

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
homegroupId	true	String	家庭ID，从用户信息接口中选择
sceneId	true	String	场景ID
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "homegroupId": "12099672",
  "sceneId": "4512121",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
resultId	String	执行记录ID

返回示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "resultId": "5746727"
}

错误码说明：

error	说明
1000	未知系统错误
1002	参数非法
1202	非主人无法操作

5. 语音相关

5.1 语音nlu能力

接口说明： 请求美的语音nlu能力

请求协议： HTTPS

请求方式： POST

请求地址： /v1/open/voice/nlu

参数格式： body 参数

请求头：

字段	必选	类型	说明
Authorization	true	String	Bearer开头的访问令牌 例如：Bearer 0lemRvfLicjkHtno8r6wolAq8V7oLGe6

请求参数：

字段	必选	类型	说明
reqId	true	String	请求ID
clientId	true	String	唯一的第三方开发者ID
stamp	true	String	请求时间戳，毫秒级区分
text	true	String	asr文本
homegroupId	true	String	家庭ID
sign	true	String	签名摘要

请求示例：

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "clientId": "clientId*************************1234",
  "stamp": "20181201160518000",
  "text": "开始煮饭",
  "sign": "sign*************************abcd1234"
}

返回结果：

字段	类型	说明
reqId	String	请求ID
text	String	语音播报文本
endSession	String	是否结束当轮会话，“0”：当轮会话未结束，“1”：结束当轮会话

{
  "reqId": "fe8234bf-e94c-4cdf-8ea9-c3112962ab01",
  "text": "控制成功",
  "endSession": "1"
}

附录

1. HTTP请求信息摘要

1.1 方案

为保证消息的完整性，防止消息在途中被第三方修改。在请求的参数中增加一个sign参数作为信息摘要值。服务器端与手机端用相同的规则生成sign值，服务器端接收到请求后对比sign值是否正确，如果正确才处理请求，否则视为非法请求。

1.2 生成摘要原串

请求信息摘要（即sign值）生成规则：

摘要原串 = 请求URI串（去除URL串host部分，如：v1/open/device/list/get）+ 请求参数 + client_secret

其中请求参数按参数名称字母进行升序排序（见如下示例），中间用&分隔；一个clientId对应一个clientSecret。

签名原串示例：

/v1/open/device/list/getclientId=clientId*************************1234&reqId=fe8234bf-e94c-4cdf-8ea9-c3112962ab01&stamp=20140710123434ff1a109e0255347e0137b8406e127353

1.3 由摘要原串生成sign值

对原串进行HASH，取哈希值的算法为SHA256，并将哈希值转换为16进制的小写字符，作为sign值。

2. HTTP返回信息摘要

2.1 方案

返回数据的信息摘要放在HTTP返回头"IHAP-Sign"，手机端接收到返回的sign值与手机端生成的sign值对比即可判断是否为合法返回。

2.2 生成摘要原串

返回信息的摘要原串与请求摘要原串生成规则类似，只是将"请求参数"换成"返回数据的字符串"（需要将整个JSON格式的返回数据转换为字符串），返回信息摘要（即IHAP-Sign值）生成规则：

摘要原串 = 请求URI串（去除URL串host部分，如：v1/open/device/list/get）+ 返回数据的字符串 + client_secret

签名原串示例：

/v1/open/device/list/get{"reqId":"fe8234bf-e94c-4cdf-8ea9-c3112962ab01","applianceList":[{"applianceCode":"17592186044420","type":"0xAC","name":"客厅空调","modelNumber":"1","onlineStatus":"1"}]}ff1a109e0255347e0137b8406e127353

2.3 由摘要原串生成IHAP-Sign值

由原串生成IHAP-Sign值与请求信息摘要由原串生成sign值规则相同。即对原串进行HASH，取哈希值的算法为SHA256，并将哈希值转换为16进制的小写字符，作为IHAP-Sign值。

3. 签名SDK

Java SDK：下载

Go SDK：下载