文档编辑

概述

智城云具备对企业开放数据的能力，OpenAPI个人版是专门针对用户级别的数据访问的接口，一般为APP或者第三方开发者提供，比如用户的注册、鉴权、绑定设备、控制设备等等，通过OpenAPI个人版，几乎可以使用智城云的所有功能，对于较强开发能力的企业来说，可以通过OpenAPI个人版提供用户体验更好的用户接入解决方案。

名词解释

名词	含义
openId	用户开放ID，智城云平台内部用户的唯一标识，区分每一个用户
openKey	用户开放密钥，用户鉴权后返回的随机字符串，72小时内有效，开发者需要定期更新该密钥
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数
sign	请求签名，每次请求需要带上一个签名，验证请求是否有效，签名方式可以参考安全规范
content-type	请求中的媒体类型信息，默认application/json;charset=utf-8
did/deviceId	设备ID，设备唯一标识
uid/openid	用户ID，用户唯一标识
platformId	用户所属的用户系统，可以在企业管理后台查看

接口规范

命名规范

OpenAPI采用标准的Restful规范定义接口，HTTP请求的几大关键要素：

请求协议
包括安全的和非安全的协议，安全的一般为：HTTPS，非安全的为：HTTP
请求主机域名
请求的域名，决定请求哪种环境，例如：api.machtalk.net
请求地址
请求的相对路径，类似 /v1/user,请求地址一般为名词
请求头信息
头信息包括标准的头信息，如：Accept-Language，Keep-Alive等，智城云的标准开放参数也放在头信息中，如openid，openkey，applicationid，applicationkey，开放参数统一使用大写。注意Content-Type头信息对于文本型的请求统一使用application/json
请求方式
请求方式包括四种：GET，POST，PUT，DELETE；标识请求的操作类型

请求方式	含义
GET	获取资源
POST	增加资源
PUT	修改资源
DELETE	删除资源

OpenAPI命名规范

使用有含义的英文单词
API中包含版本号
使用请求方式决定操作类型，而不是将操作类型放在API地址上
同一模块尽量使用相同的层级，比如用户模块使用/v1/user/XX/YY,保证可读性
API的参数会进行业务校验

输入和输出

OpenAPI的输入与输出都是JSON，提交的参数以流的形式传参给服务器，服务器会把每个请求都理解为JSON字符串
智城云OpenAPI采用标准的Restful接口风格，标准的文本类接口的content-type使用application/json，输入和输出均使用标准的JSON格式,设备输入的参数长度不能超过2K

安全规范

接口请求，必须保证每次请求的安全合法，智城云OpenAPI使用SHA1对请求信息进行运算得到一个摘要进行请求的签名

智城云OpenAPI分为两类API：需要鉴权的和不需要鉴权的

不需要用户鉴权的：例如用户信息重复性检查，发送验证码，获取验证码凭证等，不需要对请求进行签名计算
需要用户鉴权的：例如查看用户信息，修改密码等，具体的可以看参数说明；现支持两种鉴权方式：
1. 账号鉴权，加密方法为：SHA1(请求方式(大写)+RequestURI+requestBody+ts+openKey)
2. OAuth2.0鉴权，请求时需要在url中添加access_token参数

接口限制

平台的接口调用并不是无限制的。为了防止开发者号的程序错误而引发服务器负载异常，默认情况下，每个应用调用接口都不能超过一定限制，当即将超过一定限制时，调用对应接口会收到错误码，同时会发送告警邮件给企业负责人和平台运维人员，基本的访问限制规则为同一IP每5分钟调用接口1000次，同一用户5分钟内调用300次，超过阈值则抛错，1小时后恢复接口调用。

接口调试

调试接口的地址为：https://papi.zcyun.cn/swagger/index.html
对于那些需要用户鉴权的接口，需要首先调用用户鉴权接口进行鉴权，鉴权一次有效期8小时，重新鉴权会覆盖上次鉴权信息，不需要鉴权的接口则不用用户鉴权

注意事项

请求头信息

使用账号鉴权的接口，基本的Headers应该至少包括如下内容：

Header_Key	Header_Value
openId	用户的唯一标识，参考鉴权接口
ts	精确到毫秒的13位时间戳
sign	加密签名，算法为SHA1(请求方式(大写)+RequestURI+requestBody+ts+openKey)，openKey是鉴权返回的，参考鉴权接口，requestBody是请求的json参数字符串，保留原始的请求内容

使用OAuth2.0鉴权的接口，在访问开放接口时，不需要在header中添加openid，sign，ts等信息，只需要在url中添加授权过的access_token
例如：

1	https://papi.zcyun.cn/v1/user?access_token=ACCESS_TOKEN

失败返回

所有接口的请求，失败时会统一返回固定格式：

{
    "code": 0,
    "msg": "error message"
}

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
msg	失败描述	String	错误描述

请求域名

默认所有API的请求域名为：

1	https://papi.zcyun.cn

请求时请在接口URL加上这个前缀

请求时间戳

在鉴权之前，最好同步一下服务器时间戳，并记录一下客户端与服务器端的时间差，每次请求接口的时候客户端时间戳转换成服务器端时间戳进行访问，不然接口会返回时间戳不合法，获取最新服务器时间接口

接口基础

接口列表

用户类

接口名称	接口地址	请求方式	接口含义
检查注册信息	/v1/user/valid?value={value}&platformId={platformId}&type={type}	GET	检查注册信息
验证码发送	/v1/validCode/send	POST	验证码发送
图形验证码地址	/v1/validCodeImg?ukey=XXXXXXXXXX	GET	图形验证码地址
用户注册	/v1/user/regist	POST	用户注册
用户鉴权接口	/v1/auth	POST	用户鉴权
OAuth2.0鉴权	/v1/oauth2/authorize	GET	OAuth2.0鉴权
查看用户信息	/v1/user	GET	查看用户信息
用户信息修改	/v1/user	PUT	修改用户的信息
用户修改密码	/v1/user/editpassword	PUT	用户修改密码
用户找回密码	/v1/user/forgetpassword	PUT	用户找回密码
用户重置手机号	/v1/user/telephone	PUT	用户重置手机号
获取离线消息	/v1/user/offMsgs	POST	获取离线消息

设备类

接口名称	接口地址	请求方式	接口含义
设备列表与分组信息	/v1/user/devices	GET	设备列表与分组信息
用户绑定设备	/v1/user/device/bind/{did}	POST	用户绑定设备
用户解绑设备	/v1/user/device/unbind/{did}	POST	用户解绑设备
设备所属的用户列表	/v1/user/device/users/{did}	GET	设备所属的用户列表
生成设备分享码	/v1/user/device/share/{deviceId}	GET	生成设备分享码
通过分享码绑定	/v1/user/device/share/bind/{sk}	POST	通过分享码绑定
添加设备分组	/v1/user/device/group	POST	添加设备分组
获取设备分组列表	/v1/user/device/group/list	GET	获取设备分组列表
删除设备分组	/v1/user/device/group/{groupId}	DELETE	删除设备分组
修改设备分组	/v1/user/device/group/{groupId}	PUT	修改设备分组
转让主人权限	/v1/user/device/transfer	POST	转让主人权限
设置客人的设备属性权限	/v1/user/device/auth	POST	设置客人的设备属性权限
查看设备描述	/v1/device/desc/{did}	GET	查看设备描述
控制设备	/v1/device/opt/{did}	POST	控制设备
查询设备快照	/v1/device/snapshots/{did}	GET	查询设备快照
查询设备实时状态	/v1/device/status/{did}	GET	查询设备实时状态
初始化设备	/v1/device/reset/{did}	POST	初始化设备
设备排序设置	/v1/device/sort	POST	设备排序设置
修改设备信息	/v1/device/{deviceId}	PUT	修改设备信息
查看设备版本信息	/v1/device/version/{deviceId}	GET	查看设备版本信息

数据类

接口名称	接口地址	请求方式	接口含义
设备上报数据	/v1/data/datapoints/post	POST	设备上报数据
设备故障上报	/v1/data/faults/post	POST	设备故障上报
设备上报数据查询	/v1/data/datapoints	POST	设备上报数据查询
设备上下线日志数据	/v1/data/device/logins/{did}	POST	设备上下线日志数据
设备上报数据周期统计查询	/v1/data/stats/{gid}/{did}/{aid}/{type}/{period}/{date}	GET	设备上报数据周期统计查询
用户操作数据查询	/v1/data/user/opts	POST	用户操作数据查询
用户上下线日志数据	/v1/data/user/logins	POST	用户上下线日志数据

通用类

接口名称	接口地址	请求方式	接口含义
获取服务器最新时间	/v1/system/timestamp	GET	获取服务器最新时间
通过IP获取地理信息	/v1/ip/{ip}	GET	通过IP获取地理信息
获取请求客户端IP	/v1/ip/clientip	GET	获取请求客户端的公网IP
获取省列表	/v1/address/{countryId}	GET	获取省列表
获取省信息	/v1/provinces/{provinceId}	GET	根据id获取省信息
获取市信息	/v1/cities/{cityId}	GET	根据id获取市信息
获取区信息	/v1/districts/{districtId}	GET	根据id获取区县级信息
获取错误码信息	/v1/errorcodes/{errorcode}	GET	根据id获取错误码信息

鉴权

实现用户的鉴权，访问需要权限的接口必须首先鉴权用户信息，否则没有访问权限。
现支持两种鉴权方式：账号鉴权；OAuth2.0鉴权

用户鉴权接口

说明：实现用户的鉴权，访问需要权限的接口必须首先鉴权用户信息，否则没有访问权限，鉴权返回openId与openKey，以后每次访问接口都需要携带openId信息，签名需要用到openKey，返回的expiredAt表示该openKey到什么时候点失效，使用者需要定期调用鉴权接口，重新获取openKey，openKey72小时内有效，在有效期内如果再次申请openKey则在申请成功的时刻起新的openKey顺延72小时有效期。
URL：/v1/auth
请求方式：POST
Header参数：无
请求参数：

{
	"account": "用户名/邮箱/电话号码",
	"ts": 1512197640123,
	//请求时间戳，要求13位数字
	"sign": "8102b22a5e81e840176d9f381ec6f837",
	"platformId": 1
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
account	用户账号	String	32	是	用户名/邮箱/电话号码
ts	请求时间戳	int	13	是	13位精确到毫秒的时间戳
sign	签名	String	32	是	计算方式MD5（password+ts），其中password为原密码的md5
platformId	用户系统ID	int	11	是	用户所属的平台系统ID，可以在企业后台中查看

成功返回

{
  	"code": 0,
  	"openId": "bae5ad877197461aa9be85a62c97338a",
  	"openKey": "7ee8f0d2adc2491b8e1c3e58d7f714bf",
  	"expiredAt": 1512227042190
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	int	成功固定为0，请求是否成功的标志
openId	用户唯一标识	String	用户的唯一标识
openKey	用户访问Key	String	用户的访问Key，访问接口时做签名时需要
expiredAt	过期时间戳	int	openKey的到期时间戳，一般openKey的有效期为72小时

接口调试：接口调试地址:用户鉴权
OAuth2.0鉴权
说明：使用OAuth2.0协议，对用户进行身份鉴权。鉴权成功后返回access_token，之后访问开放接口时，只需要在URL中添加参数access_token信息；返回的expires_in为有效期，单位秒，一般为7天，到期后，需要重新获取access_token；返回的refresh_token，有效期同access_token，可在有效期内刷新access_token，即延长过期时间。
接口文档

接口名称	接口地址	请求方式	接口含义
访问鉴权页面	/v1/oauth2/authorize	GET	访问鉴权页面
获取accessToken	/v1/oauth2/accessToken	GET	获取accessToken

授权流程如下
1. 访问鉴权页面

引导需要授权的用户到如下地址(GET请求)：

1	https://papi.zcyun.cn/v1/oauth2/authorize

请求参数说明：

参数名称	必须	说明
client_id	是	注册成功后分配的clientId，为32位字符串，可登陆平台查看
response_type	是	授权类型，目前只支持code

返回说明：请求成功后，将显示用户授权界面

请求示例：

1	https://papi.zcyun.cn/v1/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code

2. 输入用户名，密码，同意授权后，页面自动跳转至YOUR_CONFIGURED_REDIRECT_URI?code=CODE

YOUR_CONFIGURED_REDIRECT_URI需要在平台（账户中心->鉴权中心->企业OAuth2.0鉴权信息）中提前配置好，必须以http:// 或 https://开头

3.换取Access Token

请求URL(GET):

1	https://papi.zcyun.cn/v1/oauth2/accessToken

请求参数说明：

参数名称	必须	说明
client_id	是	注册成功后分配的clientId，为32位字符串，可登陆平台查看
client_secret	是	注册成功后分配的client_secret，为32位字符串，可登陆平台查看
grant_type	是	描述获取授权的方式，支持authorization_code 和 refresh_token
code	否	第二步中获取的授权code，为32位字符串
refresh_token	否	用于刷新access_token的refresh_token，为32位字符串

成功返回：

{
	"access_token": "bae5ad877197461aa9be85a62c97338a",
	"expires_in": 604800,
	"refresh_token": "7ee8f0d2adc2491b8e1c3e58d7f714bf"
}

返回说明：

参数名称	必须	说明
access_token	是	授权过的access_token
expires_in	是	有效期，单位秒，access_token和refresh_token的有效期，一般的有效期为7天
refresh_token	是	有效期内，用于刷新access_token

错误返回：

{
	"error_code": "bae5ad877197461aa9be85a62c97338a",
	"error_description": "操作失败"
}

返回说明：

参数名称	必须	说明
error_code	是	错误码
error_description	是	错误描述

请求示例 1：通过授权code获取access_token

1	https: //papi.zcyun.cn/v1/oauth2/accessToken?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=CODE

请求示例 2：通过refresh_token获取新的access_token

1	https: //papi.zcyun.cn/v1/oauth2/accessToken?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

4.通过access_token访问开放接口

不同于用户接口鉴权方式，OAuth2.0鉴权，在访问开放接口时，不需要在header中添加openid，sign，ts等信息，只需要在url中添加授权过的access_token
例如获取用户信息接口：

1	https://papi.zcyun.cn/v1/user?access_token=ACCESS_TOKEN

目前OAuth2.0支持的接口如下：

接口名称	接口地址	请求方式	接口含义
查看用户信息	/v1/user	GET	查看用户信息
设备列表与分组信息	/v1/user/devices	GET	设备列表与分组信息
控制设备	/v1/device/opt/{did}	POST	控制设备
查询设备快照	/v1/device/snapshots/{did}	GET	查询设备快照
查询设备实时状态	/v1/device/status/{did}	GET	查询设备实时状态
设备上报数据查询	/v1/data/datapoints	POST	设备上报数据查询

终端用户

检查注册信息

说明：验证邮箱、电话号码是否已注册。
URL：/v1/user/valid?value={value}&platformId={platformId}&type={type}
Header参数：无
请求方式：GET
请求参数说明：参数放在URL上,例如:/v1/user/valid?value=18660473575@129.com&platformId=10&type=email

参数名称	中文名称	类型	限制（长度）	必须	说明
type	发送方式	String	11	是	标识校验类型，有两种取值类型：email，telephone
value	邮箱或手机号	String	11	是	邮箱或手机号
platformId	用户系统ID	int	11	是	用户系统的平台ID

成功返回

1
2
3

{
	"code": 0
}

接口调试：接口调试地址:检查注册信息
验证码发送

说明：当用户注册、重置密码、修改手机号、修改邮箱时，会要求用户发送验证码对信息进行验证，该接口会根据手机号来发短信，短信内容包含用户注册时所需的验证码。短信内容模板可以根据平台ID来自动选择
URL：/v1/validCode/send
Header参数：无
请求方式：POST

{
	"platformId": 1,
	"flag": 1,
	"sendMode": 1,
	"value": "abc"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
value	手机号码/邮箱地址	String	11	是	邮箱或手机号
sendMode	发送方式	int	11	是	短信（sendMode=2）/邮件(sendMode=1)
flag	类型值	int	11	是	类型，1注册 2重置密码 3修改邮箱 4修改手机号
platformId	用户系统ID	int	11	是	用户系统的平台ID

成功返回

1
2
3

{
	"code": 0
}

接口调试：接口调试地址:验证码发送
校验验证码

说明：用户首先输入通过短信或者邮件获取到的服务器发送的验证码，本接口需要提交用户输入的验证码，由服务器校验验证码是否正确，正确则返回一个UUID随机串作为下一步数据提交的凭证，错误则返回对应的错误码信息
URL：/v1/validCode/validate
Header参数：无
请求方式：POST

{
	"flag": 1,
	"platformId": 0,
	"sendMode": 1,
	"value": "abc",
	"valCode": "abc"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
value	手机号码/邮箱地址	String	11	是	邮箱或手机号
sendMode	发送方式	int	11	是	邮件（sendMode=1）/短信(sendMode=2)
flag	类型值	int	11	是	类型，1注册 2重置密码 3修改邮箱 4修改手机号
platformId	用户系统ID	int	11	是	用户系统的平台ID
valCode	验证码	String	6	是	用户收到的验证码

成功返回

{
	"code": 0,
	"token": "32位UUID，数据提交时使用"
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	int	成功固定为0，可以作为判断请求是否成功的标志
token	验证码通过凭证	String	32位UUID，数据提交时使用

接口调试：接口调试地址:校验验证码

图形验证码地址
说明：可以请求该地址生成一个验证码图片，验证的时候需要用户输入这个验证码请求时携带生成验证码的ukey
URL：/v1/validCodeImg?ukey=XXXXXXXXXX
请求方式：GET
Header参数：无
请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
ukey	验证码唯一标识	String	32	否	请求验证码时指定的key

成功返回

验证码图片

接口调试：接口调试地址:直接访问

用户注册

说明：用户注册接口，如果需要验证码，需要首先调用验证码发送或者图形验证码地址获取验证码，提交注册时需要带上用户输入的验证码。可以不传验证码直接注册。sendMode和token成对出现，ukey和valcode成对出现，ukey和sendMode只能传一个，如果不传token，则sendMode不用传,如果不传valcode, 则ukey不用传。sendMode=2时telephone为必填，sendMode=1时,email为必填
URL：/v1/user/regist
请求方式：POST
Header参数：无
请求参数：

 {
	"birthday": "2021-04-08",
	"provinceId": 1,
	"cityId": 1,
	"districtId": 72,
	"email": "123@163.com",
	"extPropVal": {},
	"nickname": "zcyun",
	"note": "zcyun",
	"platformId": 1,
	"sex": 0,
	"telephone": "16666666666",
	"username": "zcyun",
	"password": "******",
	"token": "123456",
	"sendMode": 1,
	"ukey": "123456",
	"valcode": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
username	账号	String	6-32	否	用户名、手机号或邮箱
telephone	手机号	String	11	否	sendMode=2时telephone为必填
email	邮箱	String	128	否	sendMode=1时,email为必填
birthday	生日	String	20	否	生日
sex	性别	Integer	1	否	性别，0男性 1女性 2保密
note	note	String	256	否	note
nickname	昵称	String	64	否	昵称
extPropVal	用户拓展信息	JSONObject	1024	否	用户拓展信息
districtId	地区ID	Integer	11	否	地区ID
cityId	城市ID	Integer	11	否	城市ID
provinceId	省ID	Integer	11	否	省ID
password	用户密码	String	32	是	用户密码MD5加密后的32位字符串
platformId	用户系统id	Integer	11	是	平台id
token	token	String	32	否	用户验证码通过后返回的token
sendMode	发送方式	int	11	否	邮件（sendMode=1）/短信(sendMode=2)
ukey	验证码唯一标识	String	32	否	请求图形验证码时指定的key
valcode	图形验证码	String	32	否	图形验证码

成功返回

{
  	"code": 0,
  	"openId": "bae5ad877197461aa9be85a62c97338a",
  	"openKey": "7ee8f0d2adc2491b8e1c3e58d7f714bf",
  	"expiredAt": 1512227042190
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	int	成功固定为0，可以作为判断请求是否成功的标志
openId	用户唯一标识	String	用户的唯一标识，访问其他接口时会用到，确定用户的身份
openKey	用户访问Key	String	用户的访问Key，访问接口时做签名时需要
expiredAt	过期时间戳	int	openKey的到期时间戳（毫秒数），一般openKey的有效期为72小时

接口调试：接口调试地址:用户注册

查看用户信息

说明：用户查询自身用户基本信息。
URL：/v1/user
请求方式：GET
Header参数：参考请求头信息
成功返回

  {
	"code": 0,
	"data": {
		"birthday": "string",
		"cityId": 0,
		"email": "string",
		"extPropVal": {},
		"lastLoginTime": "string",
		"nickname": "string",
		"note": "string",
		"provinceId": 0,
		"sex": 0,
		"telephone": "string",
		"openId": "string",
		"avatar": "string"
	}
}

返回说明：

参数名称	中文名称	类型	说明
openId	用户ID	String	用户ID
username	账号	String	账号
telephone	手机号	String	手机号
email	邮箱	String	邮箱
birthday	生日	String	生日
sex	性别	Integer	性别，0男性 1女性 2保密
note	note	String	note
nickname	昵称	String	昵称
lastLoginTime	上次登陆时间	String	上次登录时间
extPropVal	用户拓展信息	JSONObject	用户拓展信息
avatar	用户头像	String	用户头像URL地址

接口调试：接口调试地址:查看用户信息

用户信息修改

说明：用户资料修改，主要修改用户的基本信息，比如性别、生日、昵称、扩展属性等。手机号码或者邮箱有单独的修改接口。
URL：/v1/user
请求方式：PUT
Header参数：参考请求头信息

请求参数：

{
	"birthday": "2021-04-08",
	"extPropVal": {},
	"nickname": "zcyun",
	"sex": 0
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
birthday	生日	String	20	否	生日
sex	性别	Integer	1	否	性别，0：男性，1：女性， 2：保密
nickname	昵称	String	64	否	昵称
extPropVal	用户拓展信息	JSONObject	1024	否	用户拓展信息

成功返回：
1
2
3
{
"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
msg	失败描述	String	错误描述

接口调试：接口调试地址:用户信息修改

用户找回密码

说明：需要首先调用验证码发送获取验证码，通过用户填的验证码和新密码找回密码。sendMode和token成对出现
URL：/v1/user/forgetpassword
请求方式：PUT
Header参数：无
请求参数：

{
	"newPassword": "******",
	"value": "abc",
	"sendMode": 1,
	"token": "32位uuid",
	"platformId": 2
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
value	验证方式值	String	128	是	邮箱或手机号
sendMode	发送方式	int	11	是	邮件（sendMode=1）/短信(sendMode=2)
newPassword	新密码	String	32	是	用户新密码MD5加密后的32位字符串
token	用户验证码通过后返回的token	String	32	是	用户验证码通过后返回的token
platformId	用户系统ID	int	11	是	平台ID

接口调试：接口调试地址:用户找回密码

用户修改密码

说明：用户登录后，可以修改密码，需要提供正确的老密码
URL：/v1/user/editpassword
请求方式：PUT
Header参数：参考请求头信息
请求参数：

{
	"newPassword": "******",
	"oldPassword": "******"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
oldPassword	旧密码	String	32	是	用户旧密码MD5加密后的32位字符串
newPassword	新密码	String	32	是	用户新密码MD5加密后的32位字符串

成功返回：

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:用户修改密码

用户重置手机号

说明：修改手机号，需要向新手机号发送一个验证码，用户获取验证码后需要再提交一次新的电话号码和验证码，如果验证码正确则修改手机号成功。短信内容根据平台ID设置。用户新的手机号收到验证码后，把验证码和新手机一起发送给服务器，如果验证码输入正确，则认为修改手机号成功。
URL：/v1/user/telephone
请求方式：PUT
Header参数：参考请求头信息
请求参数：

{
	"telephone": "16666666666",
	"valcode": "abc"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
telephone	新手机号	String	11	是	新手机号
valcode	验证码	String	6	是	用户手机短信收到的验证码

成功返回：

1
2
3

{
	"code": 0
}

接口调试：接口调试地址:用户重置手机号

获取离线消息

说明：根据查询条件查询最近7天内的离线消息。
URL： /v1/user/offMsgs
请求方式：POST
Header参数：参考请求头信息
请求参数：

1
2
3

{
	"count": 0
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
count	离线消息条数	Integer	6	否	每次返回的离线消息数量条数，默认50

成功返回

{
	"code": 0,
	"rest": 3,
	"data": [{
		"cmd": "fault",
		"fids": "4",
		"did": "110000001000076005",
		"timestamp": 1481529882441
	},
	{
		"mid": "142",
		"from": "110000001000076005",
		"cmd": "fault",
		"fids": [1],
		"ts": "1481529921298"
	},
	{
		"cmd": "fault",
		"fids": "1",
		"did": "110000001000076005",
		"timestamp": 1481529921597
	}]
}

返回说明：

参数名称	中文名称	类型	说明
rest	离线消息剩余数	Integer	离线消息剩余数
data	离线消息内容	JSonObject	离线消息内容

接口调试：接口调试地址:获取离线消息

用户设备关系

设备列表与分组信息

说明：查询用户绑定的设备列表以及分组信息
URL：/v1/user/devices?appId={appId}
请求方式：GET
Header参数：参考请求头信息
请求参数

参数名称	中文名称	类型	限制（长度）	必须	说明
appId	app唯一id	int	11	否	app的唯一id

成功返回

{
	"code": 0,
	"data": {
		"devs": [{
			"devs": [{
				"firm": "007",
				"product": "007",
				"modelId": "kpwjlv",
				"name": "红外报警器",
				"model": "P01",
				"sid": "BS1021000011478"
			}],
			"firm": "007",
			"product": "007",
			"modelId": "kpwjlv",
			"bindTime": null,
			"name": "迷你狗",
			"lanPin": "5eb0416d07e74414",
			"model": "P01",
			"did": "110000001000002020",
			"gateway": 1,
			"online": "1",
			"order": 2
		}],
		"group": [{
			"children": [{
				"name": "组2",
				"icon": null,
				"id": 2
			}],
			"name": "组1",
			"icon": null,
			"id": 1,
			"dids": ["000000001000000298"]
		}]
	}
}

返回说明

参数名称	中文名称	类型	限制（长度）	必须	说明
code	返回码	Integer	11	否	成功固定为0
data	数据区	JSONArray		否	数据区
did	网关或者设备的唯一编号	Integer	1	否	网关或者设备的唯一编号
sid	网关下子设备的唯一编号	string	32	否	网关下子设备的唯一编号
gateway	是否为网关设备	Integer	8	否	1：是网关 0：不是网关
name	网关或者设备的名称	string	45	否	网关或者设备的名称
online	网关或者设备是否在线	Integer	32	否	1：在线，0：离线
firm	设备的厂商编号	string	32	否	设备的厂商编号
product	设备的产品类型	string	128	否	设备的产品类型
model	网关或者设备的型号	string	128	否	网关或者设备的型号
order	网关或者设备的排序号	string	128	否	网关或者设备的排序号
resVer	版本号	string	128	否	网关或者设备的资源文件的版本号
bindTime	网关或者设备的绑定时间	string	128	否	网关或者设备的绑定时间
icon	分组的图标路径	string	128	否	分组的图标路径
dids	分组中包含的设备列表	string	128	否	分组中包含的设备列表
children	子分组	string	128	否	分组中的子分组，可以支持多级分组

接口调试：接口调试地址:设备列表与分组信息
用户绑定设备

说明：用户绑定设备
URL:/v1/user/device/bind/{deviceId}
请求方式:POST
Header参数：参考请求头信息
请求参数

{
	"latitude": 0,
	"longitude": 0,
	"model": "abc",
	"name": "zcyun",
	// 用32位设备PIN码的后16位对timestamp进行AES 128 CBC/PKCS5加密后的值，然后将该值按字节转为16进制字符文本表示
	"pin": "123456",
	"timestamp": "123456"
}

请求参数说明:

参数名称	中文名称	类型	限制（长度）	必须	说明
latitude	纬度	double	合法维度	否	设备添加时的纬度
longitude	经度	double	合法维度	否	设备添加时的经度
model	设备的型号	String	12	是	6位型号
name	设备的名称	String	128	否	设备的名称
pin	PIN码	String	32	是	用32位设备PIN码的后16位对timestamp进行AES
timestamp	时间戳	String	13	是	客户端的本地时间秒数值

成功返回

1
2
3

{
	"code": 0
}

失败返回

{
	"code": 0,
	"msg": "error message",
	"bindLimit": "1"
}

返回说明:

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
msg	失败描述	String	错误描述
bindLimit	达到设备最大绑定数才返回	String	达到设备最大绑定数才返回

接口调试：接口调试地址:用户绑定设备
用户解绑设备

请求地址：用户解除对设备的绑定
URL:/v1/user/device/unbind/{deviceId}
请求方式: POST
Header参数：参考请求头信息
请求参数

{
	"host": "新主人uid",
	"sid": "sid",
	"usr": "abc"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
host	新主人UID	String	32	否	解绑时指定一个新的主人
sid	子设备ID	String	32	否	网关的子设备ID，表示要删除网关下的子设备
usr	非主人用户UID	String	32	否	设备的某个非主人用户，解除其与设备的绑定关系
did	设备id	String	32	是	设备id

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:用户解绑设备

设备所属的用户列表

说明：设备所属的用户列表
URL：/v1/user/device/users/{deviceId}
请求方式:GET
Header参数：参考请求头信息
请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
deviceId	设备id	String	32	是	设备id

成功返回

{
	"code": 0,
	"data": [{
		"uid": "aaa",
		"host": 0,
		"nickname": "ccc",
		"telephone": "ddd",
		"avatar": "eee"
	},
	......]
}

返回说明

参数名称	中文名称	类型	限制（长度）	必须	说明
code	返回码	Integer	11	否	成功固定为0
data	数据区	JSONArray		否	数据区
isHost	主人客人	Integer	1	否	厂商id
uid	用户uid	String	32	否	用户uid
nickname	昵称	String	128	否	昵称
telephone	电话号码	String	11	否	电话号码
avatar	头像	String	无	否	头像地址

接口调试：接口调试地址:设备所属的用户列表

设备排序设置

说明：设定用户下所有设备在显示列表中的先后顺序
URL：/v1/device/sort
请求方式:POST
Header参数：参考请求头信息
请求参数：

{
	"dids": {
		"deviceId1": order1,
		"deviceId2": order2
	}
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
dids	排序对象	json		是	键值对
键值对	键值对	json		是	设备ID为键，排序的序号为值

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	限制（长度）	必须	说明
code	返回码	Integer	11	否	成功固定为0

接口调试：接口调试地址:设备排序设置

设备分享

生成设备分享码

说明：通过指定的设备ID生成分享的key（32位唯一字符串），十分钟内有效
URL:/v1/user/device/share/{did}
请求方式：GET
Header参数：参考请求头信息
请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备id	string	32	是	设备id

成功返回

{
	"code": 0,
	"sk": "4ae6d12e11f84f648844bc9742cf8c5e"
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	int	0成功，非0表示失败错误码
sk	分享码	String	32位随机字符串

接口调试：接口调试地址:设备分享

通过分享码绑定

说明：通过扫描设备的分享码建立用户与设备的绑定关系
URL:/v1/user/device/share/bind/{sk}
请求方式:POST
Header参数：参考请求头信息
请求参数：

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
sk	32位设备分享码	String	32	是	32位设备分享码

成功返回

{
	"code": 0,
	"did": "110000001000002020"
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	int	0成功，非0表示失败错误码
did	设备id	string	设备ID

接口调试：接口调试地址:通过分享码绑定

设备分组

添加设备分组

说明：添加一个设备分组，传入分组名称，会在该用户下创建一个新的设备分组。
URL：/v1/user/device/group
请求方式：POST
Header参数：参考请求头信息
请求参数:

{
	"dids": ["110000001000002020", "000000001000000297"],
	"icon": "abc",
	"name": "zcyun",
	"pid": 4
}

请求参数说明:

参数名称	中文名称	类型	限制（长度）	必须	说明
dids	设备列表	字符串数组	32	否	设备ID列表，为空表示新建空分组
icon	图片	String	128	否	设备分组图标
name	分组名称	String	32	是	分组名称
pid	父分组id	int	11	否	如果携带表示加的是子分组，其父分组id为pid

成功返回

{
	"code": 0,
	"id": 19
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	int	0成功，非0表示失败错误码
id	分组id	int

接口调试：接口调试地址:设备分组

获取设备分组列表

说明：返回用户设备分组列表。
URL:/v1/user/device/group/list
请求方式:GET
Header参数：参考请求头信息
请求参数：

成功返回

{
	"code": 0,
	"data": [{
		"children": [{
			"children": [{
				"icon": "roomc_2",
				"name": "卧室",
				"pid": 10,
				"dids": ["110000001000001000"],
				"id": 11
			},
			{
				"icon": "roomc_2",
				"name": "卧室",
				"pid": 10,
				"dids": [],
				"id": 14
			},
			{
				"icon": "roomc_11",
				"name": "办公室g",
				"pid": 10,
				"dids": ["110000001000001002"],
				"id": 15
			}],
			"name": "Cc",
			"pid": 9,
			"dids": [],
			"id": 10
		}],
		"name": "顾",
		"dids": ["110000001000000004"],
		"id": 9
	}],
	"total": 1
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
children	子分组	jsonarray	子分组
name	分组名称	string	分组名称
icon	分组图标	string	分组图标
id	分组id	Integer	分组id
dids	分组设备	jsonarray	分组设备

接口调试：接口调试地址:获取设备分组列表

删除设备分组

说明：根据分组id删除分组信息，包括分组下边的设备
URL： /v1/user/device/group/{groupId}
请求方式: DELETE
Header参数：参考请求头信息
请求参数

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
groupId	设备数组id	int	11	是	设备数组id

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:删除设备分组

修改设备分组

说明：修改设备分组名称或者分组设备
URL：/v1/user/device/group/{groupId}
请求方式: PUT
Header参数：参考请求头信息
请求参数:

{
	"name": "groupName",
	"dids": ["did1", "did2", ......]
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
name	分组名称	String	32	否（ name和dids至少选择一个）	设置的分组名称
dids	设备id列表	jsonarray		否（ name和dids至少选择一个）	name

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:修改设备分组

设备权限

转让主人权限

说明：主人主动转让某个设备的主人权限给非主人用户，转移之后主人将成为客人，被转让者将成为该设备的新主人
URL: /v1/user/device/transfer
请求方式: POST
Header参数：参考请求头信息
请求参数

{
	"did": "deviceId",
	"to": "user"
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
did	要转移权限的设备ID	String	32	是	要转移权限的设备ID
to	主人权限转移到的目的用户	String	32	是	主人权限转移到的目的用户

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:设备权限

设置客人的设备属性权限

说明：一般情况下，设备的主人拥有设备的所有权限，比如查看、控制等。设备的主人可以给设备的非主人用户设置设备的权限，比如仅允许查看、某个功能不能进行远程控制等。当主人把设备转让给非主人后，之前对该非主人的权限设置无效。有个例外情况是在设备端也可以设定用户的权限，此时也可以对主人的权限进行设置。
URL: /v1/user/device/auth
请求方式: POST
Header参数：参考请求头信息

Header_Key	Header_Value
uid/did	用户的唯一标识或者设备的唯一标识，放在请求头中，用于表示请求的发起者

请求参数

{
	"did": "123",
	"uids": ["uid1", "uid2,......],
	"readOnly ":0/1
}
或
{
	"did": "456",
	"uids": ["uid1", "uid2,......],
	"aids ": {
		"aid1 ":1, 	//值为1表示只读属性
		"aid2 ":0, 	//值为0表示读写
		......
	}
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备id	String	32	是	设备id
uids	uid列表	数组		是	要设置权限的用户uid列表
readOnly	只读标志	int	1	否	是否对所有属性仅允许查看
aids	属性ID列表	数组		否	属性列表，目前主要有两种权限设置，只读和禁止读写，readOnly和aids有且仅有一个

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:设置客人的设备属性权限

设备功能

查看设备描述

说明：获取该设备所有属性的详细描述信息列表，包括设备的基本信息及其属性的名称、类型、值范围等信息。
URL: /v1/device/desc/{did}
请求方式: GET
Header参数：参考请求头信息
请求参数

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备id	String	32	是	设备id

成功返回

{
	"code": 0,
	"data": {
		"lastLoginTime": "2017-12-21T09:26:25",
		"modelId": "kpwjlv",
		"createTime": "2017-01-06T09:20:10",
		"moduleVersion": "1.0.0.0",
		"latitude": 104.08296,
		"deviceVersion": "1.0.0.0",
		"deviceName": "智能插座插排4",
		"longitude": 38.65777,
		"attrs": [{
			"symbol": "KW▪H",
			"unit": "千瓦时",
			"min": 0.0,
			"max": 4.294967296E9,
			"name": "有功能量总量值",
			"readOnly": 0,
			"store": 0,
			"type": 1,
			"cond": 0,
			"aid": 7
		},
		{
			"name": "校正命令",
			"readOnly": 0,
			"store": 0,
			"type": 5,
			"cond": 0,
			"aid": 8,
			"vs": {
				"0": "保存",
				"1": "删除",
				"2": "校准"
			}
		}]
	}
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	int	0成功，非0表示失败错误码
deviceName	设备名称	string	用户定义的设备名称
companyId	厂商id	String	厂商编码
productId	产品id	String	产品编码
modelId	型号ID	string	3位型号编码
latitude	经度	double	设备所在位置，经度
longitude	纬度	double	设备所在位置，纬度
createTime	创建时间	string	设备创建时间
lastLoginTime	上次登录时间	string	设备上次登录时间
deviceVersion	固件版本	string	设备固件版本
moduleVersion	模块版本	string	设备模块版本
aid	属性ID	int	属性ID
type	属性类型	int	1数值、2开关、4泛型、5枚举
name	属性名称	string	属性名称
readOnly	只读标志	int	0读写、1只读
cond	联动标志	int	1联动条件、2联动结果、3条件结果
symbol	符号	string	如升
unit	单位	string	如 L
max	最大值	long	最大值
min	最小值	long	最小值
vs	枚举值	JSON对象	枚举类型具体映射关系

接口调试：接口调试地址:查看设备描述

控制设备：

说明：控制设备
URL: /v1/device/opt/{did}
请求方式: POST
Header参数：参考请求头信息
请求参数：

{
	"as": {
		"1": 1
	},
	"sid": "123456"
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
as	属性对象	json		是	控制设备的属性键值对信息
sid	子设备ID	string	32	否	子设备ID不为空时，表示操控网关下子设备

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:控制设备

查询设备快照

说明：查询距离当前时间点最近的设备上报的所有属性值
URL: /v1/device/snapshots/{did}
请求方式: GET
Header参数：参考请求头信息
请求参数

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
did/sid	设备id/子设备id	String	32	是	设备id

成功返回

{
	"code": 0,
	"data": {
		"0": "3"
	},
	"ts": "1512813930939"
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
data	属性集合	JSON对象	数据区
ts	时间戳	Long	属性最新上报的精确到ms的时间戳
key	属性id	String	data里边的对象，key是属性id
value	属性值	String	data里边的对象，value是属性值

接口调试：接口调试地址:查询设备快照

查询设备实时状态

说明：向设备发送query，并发设备上报的最新状态返回
URL: /v1/device/status/{did}
请求方式: GET
Header参数：参考请求头信息
请求参数：

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备id	String	32	是	设备id

成功返回

{
	"code": 0,
	"data": {
		"as": {
			"1": 2,
			"2": 3
		},
		"fids": [1, 23, 45],
		"ota": [0, 1, 85]
	}
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
as	属性对象	json对象	key:属性值，value:属性值
fids	故障值列表	json数组	故障值列表
ota	设备的升级状态	json数组	1开始下载 2下载中 3下载成功 4下载失败 5开始升级 6升级中 7升级成功 8升级失败

接口调试：接口调试地址:查询设备实时状态

初始化设备

说明：清空设备与所有用户的绑定关系和历史数据。包括清除绑定关系、修改设备分组、删除历史数据、删除定时任务、清空预约时间、清空联动规则、新增恢复出厂设置记录。
URL: /v1/device/reset/{did}
请求方式 : POST
Header参数：参考请求头信息
请求参数：

{
	"ts": "123",
	// 用32位设备PIN码的后16位作为Key和偏移量对ts进行AES 128 CBC/PKCS5加密后的值，然后将该值按字节转为16进制字符文本表示
	"pin": "32位密文"
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
ts	时间戳	String	14	是	客户端精确到毫秒时间戳
pin	校验的密码	String	32	是	校验密码

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:初始化设备

修改设备信息

说明：修改设备或者网关的信息，目前主要是修改名称信息
URL: /v1/device/{deviceId}
请求方式 : PUT
Header参数：参考请求头信息
请求参数：

{
	"name": "device1",
	"sid": "subDeviceID"
}

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
name	设备名称	String	128	是	设备的新名字
sid	网关下子设备	String	32	否	指定表示修改网关下子设备名称

成功返回

1
2
3

{
	"code": 0
}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码

接口调试：接口调试地址:修改设备信息

查看设备版本信息

说明：返回设备的最新版本信息，如果设备是最新版本则只显示当前版本，如果设备不是最新版本则返回当前和最新版本。
URL: /v1/device/version/{deviceId}
请求方式: GET
Header参数：参考请求头信息
请求参数

请求参数说明

参数名称	中文名称	类型	限制（长度）	必须	说明
deviceId	设备id	String	32	是	设备id

成功返回

{
	"code": 0,
	"data": {
		"device": {
			"ver": "version",
			"newVer": "newVersion",
			"cancel": 0 / 1,
			"info": "upgradeInfo",
			"ts": "timestamp"
		},
		"module": {
			"ver": "version",
			"newVer": "newVersion",
			"cancel": 0 / 1,
			"info": "upgradeInfo",
			"ts": "timestamp"
		}
	}

}

返回说明

参数名称	中文名称	类型	说明
code	成功标识	int	0成功，非0表示失败错误码
ver	当前版本	string	设备或模块的当前版本信息
newVer	最新版本号	String	设备或模块的最新版本
cancel	是否可以取消	Integer	通知到达用户后，用户是否可以取消升级0：不能取消1：可以取消
info	升级说明	string	升级信息，用于通知用户新版本的特性，以及升级原因
ts	时间戳	string	返回新固件的发布时间
device	设备	JSON对象	设备版本信息
module	模块	JSON对象	模块版本信息

接口调试：接口调试地址:查看设备版本信息

设备数据

设备上报数据

说明：对于不能直接联网的设备，如蓝牙类设备，数据上报需要依赖手机的网络进行数据上报，客户端可以利用此接口实现数据上报,一次可以上报多条属性的数据
URL：/v1/data/datapoints/post
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"gid": "string",
	"did": "string",
	"data": [{
		"aid": 1,
		"value": "1",
		"ts": 1529477976000
	}]
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
gid	型号ID	String	6	是	型号ID
did	设备ID	String	32	是	设备ID，设备唯一标识
aid	属性ID	Integer	11	否	属性ID
value	属性值	String	20	是	属性值
ts	数据产生时间	Long	20	是	时间戳，毫秒级的

成功返回
1
2
3
{
"code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0

接口调试：接口调试地址:设备上报数据查询

设备故障上报

说明：对于不能直接联网的设备，如蓝牙类设备，需要通过APP来上报设备故障数据
URL：/v1/data/faults/post
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"did": "string",
	"fids": "0,1,2,3"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备ID	String	32	是	设备ID，设备唯一标识
fids	属性ID	Integer	11	否	设备故障编码，一次上报多个故障需要用逗号分开

成功返回
1
2
3
{
"code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0

接口调试：接口调试地址:设备上报数据查询

设备上报数据查询

说明：根据条件查询某一时间段内设备上报（post）的原始数据。startTime，endTime必填，间隔必须在7天范围以内，否则提示参数非法。
URL：/v1/data/datapoints
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"gid": "123456",
	"did": "123456",
	"aid": 1,
	"startTime": "2017-12-21T09:26:25",
	"endTime": "2017-12-22T09:26:25"
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
gid	型号ID	String	6	是	型号ID
did	设备ID	String	32	是	设备ID，设备唯一标识
aid	属性ID	Integer	11	否	属性ID
startTime	开始时间	String	20	是	开始时间，yyyy-MM-ddTHH:mm:ss
endTime	结束时间	String	20	是	结束时间，yyyy-MM-ddTHH:mm:ss

成功返回

{
  	"code": 0,
  	"data": [{
  		"aid": 1,
  		"key": "2017-09-27T11:00:00",
  		"value": "22.22"
  	},
  	{
  		"aid": 1,
  		"key": "2017-09-27T10:00:00",
  		"value": "22.22"
  	}]
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
data	数据区	JSONArray	返回的数据
aid	属性ID	Integer	属性ID
key	时间戳	String	时间，yyyy-MM-ddTHH:mm:ss
value	值	String	数据

接口调试：接口调试地址:设备上报数据查询

设备上报数据周期统计查询

说明：查询某设备某属性的周期性统计数据。周期说明： period为day时，date传入2015-03-15；period为week时，date传入2015-40表示2015年第40周；period为month时，date传入2015-03；period为year时，date传入2015
URL：/v1/data/stats/{gid}/{did}/{aid}/{type}/{period}/{date}
请求方式：GET
Header参数：参考请求头信息
请求参数：

参数名称	中文名称	类型	限制（长度）	必须	说明
gid	设备型号ID	String	6	是	设备型号ID
did	设备ID	String	32	是	设备ID
aid	设备属性ID	Integer	11	是	设备ID
type	统计维度	String	20	是	统计维度，目前支持sum、avg、max、min
period	统计周期	String	20	是	统计周期可以传入的值:day、week、month、year
date	统计日期	String	20	是	统计日期

成功返回

{
	"code": 0,
	"data": [{
		"2017-10-18T00:00:00": 66.33
	},
	{
		"2017-10-18T01:00:00": 70
	},
	{
		"2017-10-18T02:00:00": 0
	},
	{
		"2017-10-18T03:00:00": 0
	},
	{
		"2017-10-18T04:00:00": 0
	},
	{
		"2017-10-18T05:00:00": 0
	},
	{
		"2017-10-18T06:00:00": 0
	},
	{
		"2017-10-18T07:00:00": 0
	},
	{
		"2017-10-18T08:00:00": 0
	},
	{
		"2017-10-18T09:00:00": 0
	},
	{
		"2017-10-18T10:00:00": 0
	},
	{
		"2017-10-18T11:00:00": 70
	},
	{
		"2017-10-18T12:00:00": 0
	},
	{
		"2017-10-18T13:00:00": 0
	},
	{
		"2017-10-18T14:00:00": 0
	},
	{
		"2017-10-18T15:00:00": 0
	},
	{
		"2017-10-18T16:00:00": 0
	},
	{
		"2017-10-18T17:00:00": 0
	},
	{
		"2017-10-18T18:00:00": 0
	}],
	"total": 206.33,
	"max": 206.33,
	"min": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
data	数据区	JSONArray	返回的数据
total	所有值累加和	Double	所有值累加和
max	最大值	Double	最大值
min	最小值	Double	最小值

接口调试：接口调试地址:设备上报数据周期统计查询

设备上下线日志数据

说明：查询设备上下线日志记录，默认按上下线时间降序排列。startTime，endTime必填，间隔必须在7天范围以内，必须是同一月份的数据。
URL：/v1/data/device/logins/{did}
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"online": 0,
	"startTime": "2017-12-21T09:26:25",
	"endTime": "2017-12-22T09:26:25",
	"pageNo": 1,
	"pageSize": 10
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备ID	String	32	是	设备ID
online	上、下线日志	Integer	1	否	0：下线日志，1：上线日志
startTime	开始时间	String	20	是	开始时间，yyyy-MM-ddTHH:mm:ss
endTime	结束时间	String	20	是	结束时间，yyyy-MM-ddTHH:mm:ss
pageNo	第几页	Integer	11	否	从1开始，默认为1
pageSize	每页数据大小	Integer	11	否	默认为10

成功返回

{
  	"code": 0,
  	"data": [{
  		"loginTime": "2017-09-27T11:00:00",
  		"clientIp": "192.168.0.11",
  		"online": 0,
  		"onlineTime": 3600000,
  		"serverIp": "192.168.0.177:7778",
  		"provinceId": 1,
  		"cityId": 11,
  		"districtId": 111
  	}],
  	"total": 1
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
total	符合条件的记录总数	Integer	符合查询条件的记录总数
data	数据区	JSONArray	返回的数据
loginTime	上、下线时间	String	上、下线时间
online	上、下线日志	Integer	0：下线日志，1：上线日志
serverIp	服务器IP	String	长连接服务器地址
clientIp	客户端IP	String	客户端地址
onlineTime	本次在线时长	Long	本次在线时长
provinceId	省id	Integer	省id
cityId	市id	Integer	市id
districtId	区县id	Integer	区县id

接口调试：接口调试地址:设备上下线日志数据

用户数据

用户操作数据查询

说明：查询用户操作设备日志记录，默认按操作时间降序排列。startTime，endTime必填，间隔必须在7天范围以内。
URL：/v1/data/user/opts
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"did": "did",
	"aid": 0,
	"startTime": "2017-12-21T09:26:25",
	"endTime": "2017-12-22T09:26:25",
	"pageNo": 1,
	"pageSize": 10
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
did	设备id	String	32	是	设备id
aid	属性ID	Integer	11	否	属性ID
startTime	开始时间	String	20	是	开始时间
endTime	结束时间	String	20	是	结束时间
pageNo	第几页	Integer	11	否	从1开始，默认为1
pageSize	每页数据大小	Integer	4	否	默认为10

成功返回

{
  	"code": 0,
  	"data": [{
  		"uid": "00004786e5794d84a4239b79c55333ca",
  		"productId": "007",
  		"modelId": "P01",
  		"aid": 8,
  		"gid": "cacaca",
  		"optTime": "2017-09-24T10:00:00",
  		"value": 190,
  		"did": "110000001000081233"
  	}],
  	"total": 1
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
total	符合条件的记录总数	Integer	符合查询条件的记录总数
data	数据区	JSONArray	返回的数据
uid	用户ID	String	用户ID
did	设备id	String	设备id
aid	属性ID	Integer	属性ID
optTime	操作时间	String	操作时间
productId	产品ID	String	产品ID
modelId	型号ID	String	型号ID
value	值	Double	操作属性值
gid	设备型号ID	String	6位型号编码

接口调试：接口调试地址:用户操作数据查询

用户上下线日志数据

说明：查询用户上下线日志记录，默认按上下线时间降序排列。startTime，endTime必填，间隔必须在7天范围以内，必须是同一月份的数据。
URL：/v1/data/user/logins
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"online": 0,
	"startTime": "2017-12-21T09:26:25",
	"endTime": "2017-12-22T09:26:25",
	"pageNo": 1,
	"pageSize": 10
}

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
online	上、下线日志	Integer	1	否	0：下线日志，1：上线日志
startTime	开始时间	String	20	是	开始时间，yyyy-MM-ddTHH:mm:ss
endTime	结束时间	String	20	是	结束时间，yyyy-MM-ddTHH:mm:ss
pageNo	第几页	Integer	11	否	从1开始，默认为1
pageSize	每页数据大小	Integer	11	否	默认为10

成功返回

{
  	"code": 0,
  	"data": [{
  		"loginTime": "2017-09-27T11:00:00",
  		"clientIp": "192.168.0.11",
  		"online": 0,
  		"onlineTime": 3600000,
  		"serverIp": "192.168.0.177:7778",
  		"provinceId": 1,
  		"cityId": 11,
  		"districtId": 111
  	}],
  	"total": 1
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
total	符合条件的记录总数	Integer	符合查询条件的记录总数
data	数据区	JSONArray	返回的数据
loginTime	上、下线时间	String	上、下线时间
online	上、下线日志	Integer	0：下线日志，1：上线日志
serverIp	服务器IP	String	长连接服务器地址
clientIp	客户端IP	String	客户端地址
onlineTime	本次在线时长	Long	本次在线时长
provinceId	省id	Integer	省id
cityId	市id	Integer	市id
districtId	区县id	Integer	区县id

接口调试：接口调试地址:用户上下线日志数据

通用接口

获取服务器最新时间

说明：获取服务器最新时间
URL：/v1/system/timestamp
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数:

成功返回

{
	"code": 0,
	"data": {
		"ts": 1516605629073,
		"date": "2017-12-18T14:30:25"
	}
}

返回说明：

参数名称	中文名称	类型	限制（长度）
code	返回码	Integer	成功固定为0
ts	当前系统时间戳	Long	当前系统时间戳，精确到ms
date	当前系统时间	Long	当前系统时间，智城云内部标准日期格式

接口调试：接口调试地址:获取服务器最新时间

通过IP获取地理信息

说明：根据IP查询IP所在地址
URL：/v1/ip/{ip}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	说明
ip	IP地址	String	IP地址，路径上的参数

成功返回

{
	"code": 0,
	"data": {
		"districtId": "-1",
		"cityName": "鞍山市",
		"isp": "联通",
		"cityId": "579",
		"provinceName": "辽宁",
		"ispId": "10050",
		"provinceId": "8"
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
cityId	城市ID	Integer	城市ID
districtId	区ID	Integer	区ID
provinceId	省ID	Integer	省ID
cityName	城市名称	String	城市名称
districtName	区名称	String	区名称
provinceName	省名称	String	省名称
ispId	结束时间	Integer	运营商代码
isp	错误码	String	运营商名称

接口调试：接口调试地址:通过IP获取地理信息
获取请求客户端IP
说明：获取请求客户端的公网IP
URL：/v1/ip/clientip
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

成功返回

{
	"code": 0,
	"data": {
		"clientIp": "192.168.1.120",
		"info": {
			"districtId": "-1",
			"cityName": "鞍山市",
			"isp": "联通",
			"cityId": "579",
			"provinceName": "辽宁",
			"ispId": "10050",
			"provinceId": "8"
		}
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
clientIp	客户端IP	String	客户端IP

接口调试：接口调试地址:获取请求客户端IP
获取省列表

说明：获取省列表
URL：/v1/address/{countryId}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
countryId	国家编码	Integer	32	否	国家编码，中国固定为1

成功返回：返回请求省的详细信息

{
	"code": 0,
	"data": [{
		"provinceName": "北京",
		"text": "北京",
		"provinceId": 1,
		"value": 1,
		"countryId": 1
	},
	{
		"provinceName": "上海",
		"text": "上海",
		"provinceId": 2,
		"value": 2,
		"countryId": 1
	},
	{
		"provinceName": "台湾",
		"text": "台湾",
		"provinceId": 32,
		"value": 32,
		"countryId": 1
	},
	{
		"provinceName": "香港",
		"text": "香港",
		"provinceId": 42,
		"value": 42,
		"countryId": 1
	},
	{
		"provinceName": "澳门",
		"text": "澳门",
		"provinceId": 43,
		"value": 43,
		"countryId": 1
	}],
	"total": 34
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
provinceName	省名	String	省名
text	中文名称	String	中文名称
value	省编码	Integer	省编码
provinceId	省编码	Integer	省编码
countryId	国家ID	Integer	国家ID

接口调试：接口调试地址:获取省信息

获取省信息

说明：根据id获取省信息
URL：/v1/provinces/{provinceId}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
provinceId	省编码	Integer	32	否	省编码

成功返回：返回请求省的详细信息

{
	"code": 0,
	"data": {
		"cityList": [{
			"fullCityName": "黑龙江哈尔滨市",
			"cityName": "哈尔滨市",
			"cityId": 698,
			"text": "哈尔滨市",
			"provinceId": 10,
			"value": 698,
			"countryId": 1
		},
		......],
		"provinceName": "黑龙江",
		"text": "黑龙江",
		"provinceId": 10,
		"value": 10,
		"countryId": 1
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
provinceName	省名	String	省名
text	中文名称	String	中文名称
value	省编码	Integer	省编码
provinceId	省编码	Integer	省编码
countryId	国家ID	Integer	国家ID
cityList	城市列表	JSONArray	省下的市列表

接口调试：接口调试地址:获取省信息

获取市信息

说明：根据id获取市信息
URL：/v1/cities/{cityId}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
cityId	市编码	Integer	11	是	市编码，路径上的参数

成功返回：返回请求市的详细信息

{
	"code": 0,
	"data": {
		"districtList": [{
			"districtId": 699,
			"districtName": "阿城区",
			"ytfee": 15,
			"cityId": 698,
			"text": "阿城区",
			"provinceId": 10,
			"value": 699,
			"countryId": 1,
			"fullDistrictName": "黑龙江哈尔滨市阿城区"
		},
		......],
		"fullCityName": "黑龙江哈尔滨市",
		"cityName": "哈尔滨市",
		"cityId": 698,
		"text": "哈尔滨市",
		"provinceId": 10,
		"value": 698,
		"countryId": 1
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
fullCityName	完整市名称	String	完整市名称
cityName	市名	String	市名
text	中文名称	String	中文名称
cityId	市编码	Integer	市编码
value	市编码	Integer	市编码
provinceId	省编码	Integer	省编码
countryId	国家ID	Integer	国家ID
districtList	区列表	JSONArray	市下面的区列表

接口调试：接口调试地址:获取市信息

获取区信息

说明：根据id获取区县级信息
URL：/v1/districts/{districtId}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
districtId	区编码	Integer	11	是	区编码，路径上的参数

成功返回：返回请求区的详细信息

{
	"code": 0,
	"data": {
		"districtId": 11432,
		"districtName": "新林区",
		"ytfee": 15,
		"cityId": 793,
		"text": "新林区",
		"provinceId": 10,
		"value": 11432,
		"countryId": 1,
		"fullDistrictName": "黑龙江大兴安岭地区新林区"
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
districtId	区编码	JSONArray	区编码
districtName	区名称	String	区名称
fullDistrictName	完整区名称	String	完整区名称
text	区中文名称	String	区中文名称
cityId	市编码	Integer	市编码
value	区编码	Integer	区编码
provinceId	省编码	Integer	省编码
countryId	国家ID	Integer	国家ID

接口调试：接口调试地址:获取区信息

获取错误码信息

说明：根据错误码ID获取错误码详细信息
URL：/v1/errorcodes/{errorcode}
请求方式：GET
Header参数：

Header_Key	Header_Value
暂无	暂无

请求参数：

请求参数说明：

参数名称	中文名称	类型	限制（长度）	必须	说明
errorcode	错误码	Integer	11	是	错误码

成功返回：返回请错误码的详细信息

{
	"code": 0,
	"data": {
		"zh_CN": "请求太频繁",
		"errorcode": "20002"
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	返回码	Integer	成功固定为0
zh_CN	中文说明	String	错误码中文说明
errorcode	错误码	String	错误码

接口调试：接口调试地址:错误码

概述

名词解释

接口规范

命名规范

OpenAPI命名规范

输入和输出

安全规范

接口限制

接口调试

注意事项

请求头信息

失败返回

请求域名

请求时间戳

接口基础

接口列表

用户类

设备类

数据类

通用类

鉴权

用户鉴权接口

OAuth2.0鉴权

终端用户

检查注册信息

验证码发送

校验验证码

图形验证码地址

用户注册

查看用户信息

用户信息修改

用户找回密码

用户修改密码

用户重置手机号

获取离线消息

用户设备关系

设备列表与分组信息

用户绑定设备

用户解绑设备

设备所属的用户列表

设备排序设置

设备分享

生成设备分享码

通过分享码绑定

设备分组

添加设备分组

获取设备分组列表

删除设备分组

修改设备分组

设备权限

转让主人权限

设置客人的设备属性权限

设备功能

查看设备描述

控制设备：

查询设备快照

查询设备实时状态

初始化设备

修改设备信息

查看设备版本信息

设备数据

设备上报数据

设备故障上报

设备上报数据查询

设备上报数据周期统计查询

设备上下线日志数据

用户数据

用户操作数据查询

用户上下线日志数据

通用接口

获取服务器最新时间

通过IP获取地理信息

获取请求客户端IP

获取省列表

获取省信息

获取市信息

获取区信息

获取错误码信息