FogCloud应用端接口文档

token说明

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

Authorization: jwt eyJhbGciOiJ...

ErrorCode说明

• 所有接口里，成功的code为0，其他code请参考接口说明。

参数说明

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

获取用户注册验证码

POST /enduser/getVerCode/

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

请求参数

返回值

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

错误码

验证码检查

POST /enduser/checkVerCode/

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

请求参数

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

字段说明

错误码

注意事项
- 该接口调用结束并不会设置用户密码，仅仅更新mqtt的登录密码为验证码；若要设置用户密码，需要调用/enduser/resetPassword/接口设置。
- clientid用于登录mqtt，登录密码同用户密码，如果使用验证码登录，则mqtt的登录密码为验证码。

登录

POST /enduser/login/

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

请求参数

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

注意
目前请根据返回值中的错误信息，自行判断错误类型，后期会拆分到不同ErrorCode。

错误码

刷新应用端授权

POST /enduser/refreshToken/

• 刷新应用端的授权。

请求参数

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

注意
目前请根据返回值中的错误信息，自行判断错误类型，后期会拆分到不同ErrorCode。

错误码

验证应用端授权

POST /enduser/verifyToken/

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

请求参数

返回值

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "clientid": "466f491a-9753-11e6-9baf-00163e120d98"
}

返回值字段说明

注意
目前请根据返回值中的错误信息，自行判断错误类型，后期会拆分到不同ErrorCode。

错误码

密码重置（jwt认证）

POST /enduser/resetPassword/

• 用于注册结束后设置密码，或者终端用户密码遗忘时，重置密码

请求参数

返回值

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

错误码

绑定设备（jwt认证）

POST /enduser/bindDevice/

• 接口调用成功后，当前用户被绑定为设备的超级用户，一个设备只允许一个超级用户，拥有设备的最高权限（具体内容参考设计文档）。

请求参数

返回值

{
    "meta": {
        "message": "Bind superuser to device successfully.",
        "code": 0
    },
    "data": {
        "devicepw": "123456",
        "deviceid": "7d0d8430-759a-11e6-a169-f8cab81d2727",
        "devicename": "test"
    }
}

或者

{
    "meta": {
        "message": "Rebind device to this User",
        "code": 0
    },
    "data": {
        "devicepw": "123456",
        "deviceid": "7d0d8430-759a-11e6-a169-f8cab81d2727",
        "devicename": "test"
    }
}

返回值字段说明

错误码

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

POST /enduser/getShareVerCode/

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

请求参数

返回值

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

错误码

设备授权（jwt认证）

POST /enduser/grantDevice/

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

请求参数

返回值

{
    "meta": {
        "message": "Grant successfully.",
        "code": 0
    },
    "data": {
        "id": 32,
        "devicepw": "123456",
        "bindingtype": "home",
        "role": 2,
        "remark": "",
        "bindingtime": "2016-10-28T15:41:35.817000",
        "validitytime": null,
        "status": 1,
        "deleteflag": false,
        "alias": "test",
        "extra": {},
        "enduser": 11,
        "app": "c57a6240-4e6e-11e6-96c8-dc536017523b",
        "device": 12
    }
}

返回值字段说明

错误码

应用端发送指令（jwt认证）

POST /enduser/sendCommandAdv/

• 应用端下发指令给设备。

请求参数

参数备注
flag采用各bit位是否为1标识是否启用对应的功能，对应关系如下：
0位→是否发送mqtt消息到设备topic（c2d/deviceid/commands）
1位→是否将payload数据存入数据库
默认情况下会发送mqtt消息和存储payload到数据库

返回值

{
    "meta": {
        "message": "Send command successfully",
        "code": 0
    },
    "data": {}
}

错误码

更新用户信息（jwt认证）

PUT /enduser/updateUserInfo/

• 更新用户信息。

请求参数

返回值

{
    "meta":{
        "message":"success",
        "code":0
    },
    "data":{
        "nickname":"nickname",
        "realname":"realname",
        "gender":"f",
        "city":"shanghai",
        "avatar":"https://storecloud.com/1.jpg",
        "note":"App User"
    }
}

错误码

用户详情（jwt认证）

GET /enduser/getUserInfo/

• 获取用户的信息详情。

请求参数
无

返回值

{
    "meta":{
        "message":"success to user info",
        "code":0
    },
    "data":{
        "last_login":"2016-10-31T15:47:02.600000",
        "enduserid":"330f9fc0-57c3-11e6-a624-f8cab81d2727",
        "phone":"",
        "phonearea":"+86",
        "phoneverified":false,
        "email":"zrg1231@126.com",
        "emailverified":true,
        "nickname":"nickname",
        "realname":"realname",
        "gender":"f",
        "city":"shanghai",
        "avatar":"https://storecloud.com/1.jpg",
        "note":"App User",
        "is_active":true,
        "date_joined":"2016-08-01T16:37:36.828000",
        "is_virtual":false,
        "app":"c57a6240-4e6e-11e6-96c8-dc536017523b"
    }
}

返回值字段说明

错误码
无

解绑设备（jwt认证）

PUT /enduser/unbindDevice/

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

请求参数

返回值

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

错误码

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

PUT /enduser/removeBindRole/

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

请求参数

返回值

{
    "meta":{
        "message":"Remove successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

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

PUT /enduser/transferAdmin/

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

请求参数

返回值

{
    "meta":{
        "message":"Transfer superuser successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

更新授权级别（jwt认证）

PUT /enduser/updateBindRole/

• 超级用户/管理员更新用户的授权级别：管理员只能更新普通用户为管理员，不能将管理员降级为普通用户。

请求参数

返回值

{
    "meta":{
        "message":"Update role successfully.",
        "code":0
    },
    "data":{
        "enduserid":"78212721-759e-11e6-b860-f8cab81d2727"
    }
}

错误码

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

GET /enduser/devicelistbyenduser/

• 获取用户的设备列表。

请求参数
无

返回值

{
    "meta":{
        "message":"device list by user",
        "code":0
    },
    "data":[
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "parentid":null,
            "device_name":"test",
            "is_sub":false,
            "mac":"123qwe",
            "role":1,
            "online":false,
            "product_name":"test",
            "device_id":"7d0d8430-759a-11e6-a169-f8cab81d2727"
        },
        {
            "device_pw":"123456",
            "product_icon":"",
            "gatewaytype":1,
            "parentid":null,
            "device_name":"test",
            "is_sub":false,
            "mac":"faagaaffabbb",
            "role":2,
            "online":true,
            "product_name":"test",
            "device_id":"471c6700-73d9-11e6-a28a-f8cab81d2727"
        }
    ]
}

返回值字段说明

错误码
无

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

GET /enduser/enduserlistbydevice/

• 管理员或者超级用户获取某个设备的所有用户；其中，超级用户可以看到除了自己的所有绑定用户，管理员只能看到普通用户。

请求参数

返回值

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

返回值字段说明

错误码

设备详情（jwt认证）

GET /enduser/deviceInfo/

• 获取设备的信息详情。

请求参数

返回值

{
    "meta":{
        "message":"Device info",
        "code":0
    },
    "data":{
        "devicepw":"123456",
        "is_sub":false,
        "gatewaytype":1,
        "parentid":null,
        "alias":"test",
        "online":false
    }
}

返回值字段说明

错误码

更新设备名称（jwt认证）

PUT /enduser/updateDeviceAlias/

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

请求参数

返回值

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

错误码

获取设备上报的所有数据（jwt认证）

GET /enduser/eventHistory/

• 获取设备上报的所有数据。

请求参数

返回值

{
    "meta":{
        "message":"Get history data successfully.",
        "code":0
    },
    "data":{
        "content":[
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:31"
            },
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:30"
            },
            {
                "payload":"{"a":1}",
                "time":"2016-10-26 16:22:23"
            }
        ],
        "totalnum":18925
    }
}

返回值字段说明

错误码

设备上下线数据（jwt认证）

GET /enduser/onlineStatus/

• 按日期获取设备上下线数据；注意：当网络不稳定时也会出现上下线情况。

请求参数

返回值

{
    "meta":{
        "message":"Get online data successfully.",
        "code":0
    },
    "data":{
        "onlines":"[
        ["2016-10-26T10:43:40.978", false],            
        ["2016-10-26T08:20:45.529", true], 
        ["2016-10-26T03:22:04.914", false], 
        ["2016-10-26T02:47:09.820", true], 
        ["2016-10-26T02:47:07.836", false], 
        ["2016-10-26T01:29:35.020", true],
        ["2016-10-25T01:02:19.278", true], 
        ["2016-10-25T01:00:34.221", false]
    }
}

返回值字段说明

备注
每一条记录的第一项为上/下线时间，第二项为状态：true为上线，false为下线

错误码

添加子设备（jwt认证）

POST /enduser/addSubDevice/

• 超级管理员通知父设备（网关设备）添加子设备；仅仅超级管理员有权限发起添加子设备。

请求参数

返回值

{
    "meta":{
        "message":"notice gateway to add sub device successfully.",
        "code":0
    },
    "data":{
    }
}

错误码

应用端发送命令至子设备（jwt认证）

POST /enduser/sendCommandSub/

• 应用端发送命令至子设备；子设备的Mqtt消息由父设备接收。

请求参数

参数备注
flag采用各bit位是否为1标识是否启用对应的功能，对应关系如下：
0位→是否发送mqtt消息到设备topic(c2d/deviceid/commands)
1位→是否将payload数据存入数据库
默认情况下会发送mqtt消息和存储payload到数据库

返回值

{
    "meta":{
        "message":"Send command successfully",
        "code":0
    },
    "data":{
    }
}

错误码