FogCloud应用端接口文档（V3.1）

V3.1

服务地址

• https://cnapitest.fogcloud.io

版本

• v3_1
• 使用示例

/v3_1/enduser/getVerCode/

token说明

所有标明jwt认证的接口，需要在请求header中添加Authorization头域，值为：jwt token，如下示例：

Authorization: jwt eyJhbGciOiJ...

ErrorCode说明

• 所有接口里，成功的code为0，其他code请参考接口说明。
• token认证失败相关的ErrorCode：

参数说明

• GET/DELETE参数：请封装在请求的URL中
• POST/PUT参数：请封装在请求的body里

获取用户注册验证码(旧，弃用)

POST /enduser/getVerCode/

• 应用端通过手机号码或者邮箱注册APP账户时，调用该接口获取注册验证码。

请求参数

返回值

{
    "meta": {
        "message": "Send message to phone successfully.",
        "code": 0
    },
    "data": {}
}

错误码

获取用户验证码

POST /enduser/verCode/

• 应用端通过手机号码或者邮箱注册APP账户时，调用该接口获取注册验证码。

请求参数

返回值

{
    "meta": {
        "message": "Send message to phone successfully.",
        "code": 0
    },
    "data": {}
}

错误码

验证码检查

POST /enduser/checkVerCode/

• 检查验证码合法性，确认注册的是否本人；接口调用成功后将注册一个App用户，并返回token和client_id。

请求参数

返回值

{
    "meta": {
        "message": "signup ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "client_id": "b6d21b047bed11e78d170016..."
    }
}

字段说明

错误码

注意事项

• 该接口调用结束并不会设置用户密码，若要设置用户密码，需要调用/enduser/resetPassword/接口设置。

登录

POST /enduser/login/

• 用户登录用接口，登录成功后会返回授权token。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "client_id": "b6d21b047bed11e78d170016..."
    }
}

返回值字段说明

错误码

获取MQTT登录信息（jwt认证）

GET /enduser/mqttInfo/

• 应用端通过该接口获取登录MqttServer所需的信息。

请求参数
无

返回值

{
    "meta": {
        "message": "mqtt info",
        "code": 0
    },
    "data": {
        "endpoint": "8d69e5821..."
        "login_name": "8d69e58212cd11e7a...",
        "client_id": "d53azsf..."
        "mqtt_port": 1883,
        "password": "iLBZ48jfB6tUBIoS8MS...",
        "mqtt_host": "8d69e58212cd11e7...e.com",
        "ssl_port": 1884
    }
}

返回值字段说明

错误码
无

刷新应用端授权

POST /enduser/refreshToken/

• 刷新应用端的授权。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIUzI1N...",
        "client_id": "b6d21b047bed11e78d170016..."
    }
}

返回值字段说明

错误码

验证应用端授权

POST /enduser/verifyToken/

• 验证应用端授权token是否有效。

请求参数

返回值

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGciOiJIU...",
        "client_id": "2faf79d67cb111e7b..."
    }
}

返回值字段说明

错误码

更新密码（jwt认证）

PUT /enduser/updatePassword/

• 用于终端用户更新密码。

请求参数

返回值

{
    "meta": {
        "message": "Update password ok.",
        "code": 0
    },
    "data": {}
}

错误码

重置密码

PUT /enduser/resetPassword/

• 用于终端用户密码遗忘时，重置密码

请求参数

返回值

{
    "meta": {
        "message": "Reset password ok.",
        "code": 0
    },
    "data": {}
}

错误码

使用设备ID绑定设备（jwt认证）

POST /enduser/bindDevice/

• 接口调用成功后，当前用户被绑定为设备的超级用户，一个设备只允许一个超级用户，拥有设备的最高权限。
• 目前绑定需要的device_id等信息，需要通过endpoint/enduser_id/m2m/json Topic来获取，app需要订阅该主题；设备在激活完成后，服务端会主动推送该消息，格式为:

{
    "type":"bind_info",
    "data":{
        "device_id":"abxs..."
    }
}

请求参数

返回值

{
    "meta": {
        "message": "Bind superuser to device successfully.",
        "code": 0
    },
    "data": {
        "superuser": "1761211...",
        "device_alias": "test"
    }
}

或者

{
    "meta": {
        "message": "Rebind device to this User",
        "code": 0
    },
    "data": {
        "superuser": "1761211...",
        "device_alias": "test"
    }
}

或者

  {
    "meta": {
        "message": "Device has superuser.",
        "code": 10352
    },
    "data": {
        "superuser": "1761211...",
        "device_alias": "test"
    }
}  

返回值字段说明

错误码

用户的设备列表（jwt认证）

GET /enduser/deviceList/

• 获取用户的设备列表。

请求参数

无

返回值

{
    "meta":{
        "message":"device list by user",
        "code":0
    },
    "data":[
        {
            "product_id": "ajfax..."
            "product_icon":"https://pro_icon.png",
            "device_name":"hall",
            "mac":"123qwe",
            "role":1,
            "online":false,
            "product_name":"light",
            "device_id":"7d0d843..."
        },
        {
            "product_id": "bxfax..."
            "product_icon":"https://pro_icon1.png",
            "device_name":"bedroom",
            "mac":"123qwe",
            "role":1,
            "online":true,
            "product_name":"light",
            "device_id":"7d0d843..."
        }
    ]
}

返回值字段说明

错误码

无

解绑设备（jwt认证）

PUT /enduser/unbindDevice/

• 用户解绑设备；普通用户、管理员自解绑，对其他绑定人无影响
  超级管理员解除，将解除与设备绑定的所有用户。

请求参数

返回值

{
    "meta":{
        "message":"Unbind user successfully.",
        "code":0
    },
    "data":{
    }
}

错误码

设备详情（jwt认证）

GET /enduser/deviceInfo/

• 获取指定设备的详情。

请求参数

返回值

{
    "meta":{
        "message":"Device info",
        "code":0
    },
    "data":{
        "dsn":"test01",
        "device_image":"http://fog-pub-test...",
        "product":{
            "name":"test",
            "product_id":"5a9643142...",
            "model":"HCB_M2"
        },
        "alias":"测试",
        "new_version":"1.1.4",
        "binding_time":"2018-05-28 15:59:47.129392",
        "is_online":false,
        "is_ota":false,
        "current_version":"1.1.4",
        "device_id":"7c1544595ca..."
    }
}

字段说明

错误码

更新授权级别（jwt认证）

PUT /enduser/updateBindRole/

• 超级用户更新其他用户的授权级别。

请求参数

返回值

{
    "meta":{
        "message":"update ok",
        "code":0
    },
    "data":{
        "enduserid":"78212..."
    }
}

错误码

管理员、超级用户解除指定人（jwt认证）

PUT /enduser/removeBindRole/

• 管理员、超级用户解除指定人；管理员不能移除管理员。

请求参数

返回值

{
    "meta":{
        "message":"Remove successfully.",
        "code":0
    },
    "data":{
        "enduser_id":"782127..."
    }
}

错误码

超级用户权限转移（jwt认证）

POST /enduser/transferAdmin/

• 超级用户将自身的权限转移给其他用户。

请求参数

返回值

{
    "meta":{
        "message":"Transfer superuser successfully.",
        "code":0
    },
    "data":{
        "enduserid":"7821272..."
    }
}

错误码

设备授权（jwt认证）

POST /enduser/grantDevice/

• 管理员/超级用户对用户进行设备授权；只能授权管理员或者普通用户。该接口为被授权人调用。

请求参数

返回值

{
    "meta": {
        "message": "Grant successfully.",
        "code": 0
    },
    "data": {
        "binding_type": "home",
        "role": 2,
        "binding_time": "2016-10-28 15:41:35.817000",
        "status": 1,
        "is_deleted": false,
        "alias": "test",
        "extra": {},
        "enduser": "afgxrty...",
        "app": "c57a6240-4e...",
        "device": "tywww..."
    }
}

返回值字段说明

错误码

获取设备授权码（jwt认证）

POST /enduser/shareCode/

• 管理员/超级用户授权设备时，需要使用该验证码。

请求参数

返回值

{
    "meta": {
        "message": "Generate captcha successfully.",
        "code": 0
    },
    "data": {
        "vercode": "ac137a1e-9cda-11e6-993c-dc536017523b"
    }
}

错误码

获取用户详情（jwt认证）

GET /enduser/userInfo/

• 获取用户的信息详情。

请求参数
无

返回值

{
    "meta":{
        "message":"get user info ok",
        "code":0
    },
    "data":{
        "enduser_id":"b6d21b047bed11e...",
        "last_login":"2017-08-09T15:39:32.742454",
        "phone":"",
        "phone_area":"+86",
        "phone_verified":false,
        "email":"test1231@126.com",
        "email_verified":true,
        "nick_name":"",
        "real_name":"",
        "gender":"",
        "city":"",
        "avatar":"",
        "note":"",
        "is_active":true,
        "date_joined":"2017-08-08T11:57:36.258161",
        "is_virtual":false,
        "is_online":false,
        "online_times":0,
        "app_id":"2c357408-7730-11e7-8d17-00163e03b4d6"
        "user_id":"", 
        "tmall_flag": True
    }
}

返回值字段说明

错误码

无

更新用户详情（jwt认证）

PUT /enduser/userInfo/

• 获取用户的信息详情。

请求参数

返回值

{
    "meta":{
        "message":"get user info ok",
        "code":0
    },
    "data":{
        "enduser_id":"b6d21b047bed11e...",
        "last_login":"2017-08-09T15:39:32.742454",
        "phone":"",
        "phone_area":"+86",
        "phone_verified":false,
        "email":"test1231@126.com",
        "email_verified":true,
        "nick_name":"",
        "real_name":"",
        "gender":"",
        "city":"",
        "avatar":"",
        "note":"",
        "is_active":true,
        "date_joined":"2017-08-08T11:57:36.258161",
        "is_virtual":false,
        "is_online":false,
        "online_times":0,
        "app_id":"2c357408-7730-11e7-8d17-00163e03b4d6"
    }
}

返回值字段说明

错误码

无

指定设备的用户列表（jwt认证）

GET /enduser/enduserList/

• 管理员或者超级用户获取某个设备的所有用户。

请求参数

返回值

{
    "meta":{
        "message":"Get user list successfully.",
        "code":0
    },
    "data":[
        {
            "real_name":"",
            "enduser_id":"78212721-759e-11e6-b860-f8cab81d2727",
            "app":"c57a6240-4e6e-11e6-96c8-dc536017523b",
            "is_active":true,
            "phone":"13026532187",
            "role":2,
            "nick_name":"",
            "email":""
        },
        {
            "real_name":"",
            "enduser_id":"f2e836cf-57c4-11e6-96bb-f8cab81d2727",
            "app":"c57a6240-4e6e-11e6-96c8-dc536017523b",
            "is_active":true,
            "phone":"",
            "role":3,
            "nick_name":"",
            "email":"zhangrg@mxchip.com"
        }
    ]
}

返回值字段说明

错误码

更新设备名称（jwt认证）

PUT /enduser/updateDeviceAlias/

• 每个用户都可以更新自己绑定的设备的名字，但用户之间不会有影响；该名字在重新绑定后会重置为产品的名字。

请求参数

返回值

{
    "meta":{
        "message":"Update alias successfully.",
        "code":0
    },
    "data":{
    }
}

错误码

推送OTA（jwt认证）

PUT /enduser/otaPush/

• 当设备需要升级时，调用该接口去推送升级文件给设备。请通过设备详情的current_version和new_version字段来判断是否需要OTA设备。

请求参数

返回值

{
    "meta":{
        "message":"OTA push ok.",
        "code":0
    },
    "data":{
    }
}

错误码

彩云天气接口（jwt认证）

GET /enduser/weather/caiyun/

• 应用端通过彩云接口获取天气数据，需要在Fogcloud控制台中，配置App的彩云天气组件。

请求参数

错误码

应用下产品类别接口(JWT认证)

GET /enduser/product/category/
- 获取产品类别

请求参数示例

GET /enduser/product/category/?app_id=dlfkl83803jef&language_id=1

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": [
        {
            "default_picture": "https://mxchip-fog...",
            "type_id": 3,
            "name": "球泡灯"
        },
        {
            "default_picture": "https://mxchip-fog...",
            "type_id": 1,
            "name": "景观灯"
        }
    ]
}

返回参数说明

按类别获取产品接口(JWT认证)

GET /enduser/product/productList/
- 按类别获取所有产品

请求参数

GET /enduser/product/productList/?type_id=1&app_id=cklretk4kndfg

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": [
        {
            "picture": "",
            "product_id": "7405d040f9b...",
            "name": "test7"
        },
        {
            "picture": "",
            "product_id": "09646efef9a111e7...",
            "name": "test5"
        },
        {
            "picture": "",
            "product_id": "176b4d88f6a41...",
            "name": "test"
        }
    ]
}

返回参数说明

语音接入状态 接口(JWT认证)

GET /enduser/product/voiceSupport/

请求参数示例

GET /enduser/product/voiceSupport/?app_id=3375ba62f1cd11e7998d000c299d4a8e

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "ali_genie": ["test","test2"],
        "aws_echo": ["test","test2"],
        "google_home": ["test","test2"]
    }
}

返回参数说明

关于应用详情接口

GET /enduser/app/aboutApp/
- 获取应用信息

请求参数示例

GET /enduser/app/aboutApp/?app_id=3375ba62f1cd11e7998d000c299d4a8e&language_id=1

• 现移动端未配置语言，默认英文的语言id为1,中文的语言id为2

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "app_id": "3375ba62f...",
        "language_id":1,
        "app_info": "应用XX是一款智能控...",
            {
                contact_title": "热线",
                "contact": "1235546464",
                "contact_display": "0"
                },
            {    
                "website_title": "官网",
                "website": "www.google.com",
                "website_display": "1"
                },
            {
                "email_title": "反馈邮箱",
                "email": "hotpot@hotmail.com",
                "email_display": "1"
                }  
    }
}

返回参数说明

获取帮助列表接口（JWT认证）

GET /enduser/product/helpList/
- 获取web后台设置的帮助信息列表

请求示例

GET /enduser/product/helpList/?product_id=kdlflrk4lt5kylw3

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": o
    },
    "data": [
                {"product_id": "kdlflrk4lt5kylw3",
                 "help_id":3,
                 "subject": "网络连接错误的说明"
                 },
                {"product_id":"kdlflrk4lt5kylw3",
                 "help_id": 8,
                 "subject": "使用智能音箱控制灯",
                }
      ]
}

返回参数说明

获取产品帮助支持详情接口(JWT认证）

GET /enduser/product/helpInfo/
- 获取帮助详情

请求示例

GET /v3_1/enduser/product/helpInfo/?help_id=7

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": o
    },
    "data": 
                {
                 "help_id":7,
                 "subject": "网络连接错误的说明",
                 "detail": "1.请确认你的设备已连接上网络；2.请尝试重新连接网络"
                 }
}

返回参数说明

获取终端语音接入状态接口(JWT认证)

GET /enduser/voiceStatus/

请求示例

GET /v3_1/enduser/voiceStatus/

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "enduser_id": "ce7d893a227511e8804bfa163e431402",
        "ali_genie": true,
        "aws_echo": false,
        "google_home": false
    }
}

返回参数说明

更新终端语音接入状态接口(JWT认证)

PUT /enduser/voiceStatus/

请求示例

{
    "google_home":1
}

• 请求参数与需要开启关闭的音响名称一致

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "enduser_id": "ce78bd...",
        "ali_genie": true,
        "aws_echo": false,
        "google_home": true
    }
}

返回参数说明

获取设备位置信息接口(JWT认证)

GET /enduser/deviceLocaiton/

请求示例

GET /enduser/deviceLocation/?device_id=kldgjlerkgtl3455l454

• 获取设备位置信息接口应在绑定设备时请求

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {"location": "310000"}
}

共享设备邀请接口(JWT认证)

POST /enduser/inviteUser/

请求示例

* POST /v3_1/enduser/inviteUser/
{
    "app_id":"0b4c4e80f73f11e7804bfa163e431403",
    "device_id":"6ee2d4680d8411e8804bfa163e431402",
    "invitee":"13918846727"
}

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {}
}

登陆查看是否有邀请 接口(JWT认证)

GET /enduser/invitationState/

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": [
        {
            "inviter": "17656677890",
            "invitee": "18321937749",
            "app_id": "0b4c4e80f73f11e7804bfa163e431403",
            "device_id": "6ee2d4680d8411e8804bfa163e431402"
        }
    ]
}

返回参数说明

确认邀请接口(JWT认证)

POST /enduser/invitationConfirm/

请求示例

* POST /v3_1/enduser/invitationConfirm/
{
    "is_accept": 1,
    "app_id": "0b4c4e80f73f11e7804bfa163e431402",
    "device_id": "6ee2d4680d8411e8804bfa163e431402"
}

请求参数说明

返回参数

{
    "meta": {
        "message": "Bind success",
        "code": 0
    },
    "data": {}
}

获取产品type_id 接口

GET /enduser/product/productType/

请求示例

GET /v3_1/enduser/product/productType/?product_id=dlkflsdfjllds

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "product_id": "5ab4642b3hpfrqd7",
        "type_id": "1102"
    }
}

返回参数说明

Atomi获取Token 接口

POST /atomi/obtainToken/

请求示例

{
    "app_id": "0b4c4e80f73f11e7804bfa163e431402",
    "enduser_id":"thisisatokentestofatomi2018",
    "time_zone":"+8",
    "token": ""
}

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    },
    "data": {
        "token": "eyJhbGc...",
        "enduser_id": "thisisatokentestofatomi2018"
    }
}

返回参数说明

错误信息说明

atomi绑定设备信息更新(别名，图片)接口(JWT认证)

PUT /atomi/boundDeviceInfo/

请求示例

{
    "device_id": "ldkgjl43t40trrefjklefje",
    "alias": "Smart Light",
    "device_image": "http://baidu.com/image/23l4k345f.png"
}

请求参数说明

返回参数

{
    "meta": {
        "message": "ok",
        "code": 0
    }
}