Smarthome API 说明文档

版本: 1.0

发布日期: 2024-03-28

历史记录

修订日期	版本	作者	说明
2024-3-28	V1.0	alva.huang	初始版本
2024-5-11	V1.0.1	alva.huang	增加头像上传，手机验证码

[toc]

前言

概述

本文档旨在说明爱智居服务端的API接口，帮助开发人员如何使用smarthome api 进行开发，并详细介绍了各API的功能，调用方式，返回结果和错误码。

范围说明

此开发文档只针对智能家居控制app，小程序，以及相应的控制端app，面板app等的开发。

账户系统

账户系统主要功能是用户注册，登录，修改密码，忘记密码，注销账号。用户信息维护和更新。用户权限控制。角色映射等和用户相关的功能。

HTTP返回状态码说明

200-299 请求成功 400-499 请求失败，客户端参数或信息错误 500-599 请求失败，服务端错误

状态码	说明
200	请求成功
201	新增成功
204	删除成功/更新成功
401	请求失败，无权限，没有登陆认证或认证token错误
403	请求失败，无权限
404	请求失败，资源不存在
405	请求失败，请求方法不支持
406	请求失败，参数错误
400	请求失败，参数错误
408	请求失败，请求超时
415	请求失败，不支持的媒体类型
500	请求失败，服务端内部错误

URL地址说明

url前缀地址为 https://account.izhiju.cn/realms/zhiju 接口中未指定url前缀地址，则默认使用此前缀地址如：{{url}}/account 实际地址为 https://account.izhiju.cn/realms/zhiju/account

用户登陆认证

微信用户注册登陆接口

用户通过微信小程序登陆，并使用微信code换取token，调用此接口完成注册和登录。当用户第一次使用微信小程序登陆，并且没有绑定过账号时，需要传入手机号码和验证码，进行注册绑定手机号码。后续使用微信小程序登陆，不需要传入手机号码和验证码。

POST 请求URL： https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
client_id	string	wechatapp	客户端id，微信小程序固定为wechatapp，必须字段
client_secret	string	平台相关的密钥	客户端密钥，必须字段
grant_type	string	password	授权类型，固定为password，必须字段
wechatCode	string	code	wx.login()返回的code,必须传值
smsCode	string	NULL	手机收到的验证码，已绑定的用户可不传
phoneNumber	string	NULL	手机号，可不传
areaCode	string	NULL	区号,可不传

返回结果：

成功，状态码200，返回如下内容：

{
  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
  "expires_in": 1800,           //token有效期，单位秒
  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
  "token_type": "Bearer",       //token类型，Bearer
  "not-before-policy": 0,
  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
  "scope": "profile"     //token权限，profile表示用户信息
}

微信授权码无效，状态码401，返回如下内容：

{
  "error": "wechat_code_invalid",
  "error_description": "微信授权码无效，过期或已使用"
}

手机验证码错误，状态码401，返回如下内容：

{
  "error": "sms_code_invalid",
  "error_description": "手机验证码无效"
}

手机号已绑定其他账号，状态码401，返回如下内容：

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

应用客户端用户名密码登陆认证接口

POST 请求URL： https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
client_id	string	wechatapp	客户端id，微信小程序固定为wechatapp，必须字段
client_secret	string	平台相关的密钥	客户端密钥，必须字段
grant_type	string	password	授权类型，固定为password，必须字段
username	string	username	用户名
password	string	user password	用户秘密

返回结果：

成功,状态码200，返回结果如下

{
  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
  "expires_in": 1800,           //token有效期，单位秒
  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
  "token_type": "Bearer",       //token类型，Bearer
  "not-before-policy": 0,
  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
  "scope": "profile"     //token权限，profile表示用户信息
}

客户端授权无效，用户名或秘密错误，状态码401

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

客户端id或secret错误，状态码401

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

不支持的授权类型，状态码401

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant_type"
}

应用客户端手机号码密码登陆认证接口

POST 请求URL： https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
client_id	string	wechatapp	客户端id，微信小程序固定为wechatapp，必须字段
client_secret	string	平台相关的密钥	客户端密钥，必须字段
grant_type	string	password	授权类型，固定为password，必须字段
phoneNumber	string		手机号码
areaCode	string	86	国家区号
password	string	user password	用户秘密

返回结果：

成功,状态码200，返回结果如下：

{
  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
  "expires_in": 1800,           //token有效期，单位秒
  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
  "token_type": "Bearer",       //token类型，Bearer
  "not-before-policy": 0,
  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
  "scope": "profile"     //token权限，profile表示用户信息
}

客户端授权无效，手机号或秘密错误，状态码401

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

客户端id或secret错误，状态码401

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

不支持的授权类型，状态码401

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant_type"
}

用户信息管理

获取用户信息

GET 请求URL： https://account.izhiju.cn/realms/zhiju/account

请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

返回结果：

未授权，状态码401

{
  "error": "HTTP 401 Unauthorized",
  "error_description": "For more on this error consult the server log at the debug level."
}

成功，状态码200, 返回如下内容：

{
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "alva",
  "firstName": "alva1",
  "lastName": "huang",
  "email": "alva@izhiju.cn",
  "emailVerified": false,
  "attributes": {
    "phoneNumber": [
      "18680533727"
    ],
    "picture": [
      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
    ],
    "nickname": ["test"]
  }
}

通过用户ID获取用户信息

GET 请求 url： https://account.izhiju.cn/realms/zhiju/sms/user/{{userId}} 请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

路径参数：{{userId}} 用户ID

返回结果：

成功，状态码200, 返回如下内容：

{
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "test",
  "email": "test@example.com",
  "attributes": {
    "phoneNumber": [
      "+86 15889485045"
    ],
    "nickname": [
      "testtest"
    ],
    "picture": [
      "https://account.izhiju.cn/realms/zhiju/avatar/by-userid/3333c9a4-52e1-4ff8-bfb2-d17ba01ad528"
    ]
  }
}

为登陆或token过期，状态码401，返回如下内容：

   {
    "error": "HTTP 401 Unauthorized",
    "error_description": "For more on this error consult the server log at the debug level."
   }

用户不存在，状态码404，返回如下内容：

    {
     "error_description": "user not found",
     "error": "user_not_found"
   }

通过用户手机号获取用户信息

GET 请求 url： https://account.izhiju.cn/realms/zhiju/sms/user/byphone?phoneNumber=12345678901

请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

查寻参数： | 参数名 | 参数类型 | 默认值 | 说明 | | ------------- | -------- | -------------- | --------------------------------------------- | | phoneNumber | string | | 用户手机号 | | areaCode | string | 86 | 手机号所属地区码，默认不填为中国86 |

返回结果：

成功，状态码200, 返回如下内容：

{
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "test",
  "email": "test@example.com",
  "attributes": {
    "phoneNumber": [
      "+86 1111234434"
    ],
    "nickname": [
      "testtest"
    ],
    "picture": [
      "https://account.izhiju.cn/realms/zhiju/avatar/by-userid/3333c9a4-52e1-4ff8-bfb2-d17ba01ad528"
    ]
  }
}

为登陆或token过期，状态码401，返回如下内容：

   {
    "error": "HTTP 401 Unauthorized",
    "error_description": "For more on this error consult the server log at the debug level."
   }

用户不存在，状态码404，返回如下内容：

    {
     "error_description": "user not found",
     "error": "user_not_found"
   }

更新用户信息

POST 请求URL： https://account.izhiju.cn/realms/zhiju/account

请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

{
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "alva",  //// username 6-12个字符，仅支持字母、数字和下划线，不区分大小写
  "firstName": "alva1",
  "lastName": "huang",
  "email": "alva@izhiju.cn",
  "emailVerified": false,
  "attributes": {
    "phoneNumber": [
      "18680533727"
    ],
    "picture": [
      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
    ]
  }
}

返回结果：

未认证授权，状态码401, token错误或过期

{
  "error": "HTTP 401 Unauthorized",
  "error_description": "For more on this error consult the server log at the debug level."
}

更新成功，状态码204, 无内容返回
更新失败，状态码400，下面为用户名不可修改返回的错误信息

{
  "errors": [
    {
      "field": "username",
      "errorMessage": "error-user-attribute-read-only",
      "params": [
        "${username}"
      ]
    },
    {
      "field": "username",
      "errorMessage": "readOnlyUsernameMessage",
      "params": [
        "${username}"
      ]
    }
  ]
}

用手机号注册用户

POST 请求 url： https://account.izhiju.cn/realms/zhiju/sms/user

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数： | 参数名 | 参数类型 | 默认值 | 说明 | | ------------- | -------- | -------------- | --------------------------------------------- | | phoneNumber | string | | 用户手机号 | | areaCode | string | 86 | 手机号所属地区码，默认不填为中国86 | | password | string | | 密码，6-12个字符，字母、数字 | | smsCode | string | | 短信验证码，6位数字 |

返回结果：

成功，状态码200, 返回如下内容：


  {
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "alva",  //// username 6-12个字符，仅支持字母、数字和下划线，不区分大小写
  "firstName": "alva1",
  "lastName": "huang",
  "email": "alva@izhiju.cn",
  "emailVerified": false,
  "attributes": {
    "phoneNumber": [
      "18680533727"
    ],
    "picture": [
      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
    ]
    }
  }

状态码400, 返回如下内容：

{
  "error": "phonenumber_is_empty",
  "error_description": "Must inform a cellphone number."
}

{
  "error": "phonenumber_area_not_supported",
  "error_description": "This area is not supported"
}

{
  "error": "password_is_empty",
  "error_description": "Must inform a password."
}

{
  "error": "user_already_exists",
  "error_description": "用户已存在，无需重复注册"
}

{
  "error": "user_already_exists",
  "error_description": "用户名和手机号冲突，请更换手机号"
}

{
  "error": "invalid_verification_code",
  "error_description": "Invalid verification code"
}

修改用户手机号码

URL： put {{url}}/sms/update-profile http/1.1 请求头参数： Authorization: Bearer {{token}} Content-Type: application/x-www-form-urlencoded

请求体参数： &smsCode=867014 &phoneNumber=18680533727 &areaCode=86

修改成功，状态码204, 无内容返回
未登录，状态码401, token错误或过期
失败，状态码400，参数错误

修改用户秘密

通过手机验证码重置密码

URL： put {{url}}/sms/update-profile/reset-password 请求头参数： Authorization: Bearer {{token}} Content-Type: application/x-www-form-urlencoded

请求体参数： password=4223261 //密码规则 8-16个字符，需至少包含大、小写字母和数字 &smsCode=531495 //短信验证码

通过手机验证码重置密码

URL： put {{url}}/sms/update-profile/forgot-password http/1.1 请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数： password=422326 &smsCode=867014 &phoneNumber=18680533727 &areaCode=86

通过旧密码修改密码

URL： put {{url}}/sms/update-profile/update-password http/1.1 请求头参数： Authorization: Bearer {{token}} Content-Type: application/x-www-form-urlencoded

请求体参数： password=422326 //新密码 8-16个字符，需至少包含大、小写字母和数字 &oldPassword=4223261 //旧密码

返回结果:

成功，状态码204, 无内容返回
未登录，状态码401, token错误或过期

   {
    "error": "HTTP 401 Unauthorized",
    "error_description": "For more on this error consult the server log at the debug level."
   }

失败，状态码400，参数错误

小程序用户名片二维码格式

{
  "app": "smarthome", //app值固定为smarthome
  "uid": "3333c9a4-52e1-4ff8-bfb2-d17ba01ad528" //其中uid值是用户id
}

发送短信验证码

POST 请求URL： https://account.izhiju.cn/realms/zhiju/sms/verification-code 请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
areaCode	string	86	手机号所属的区号，默认86
phoneNumber	string		手机号，11位数字

返回结果

正确状态码200,返回结果：

   {
   "expires_in": 1714988276153,
   "resend_expires": 1714988036153,
   "status": 1
   }

错误状态码400,参数错误，返回结果：

   {
   "error": "sms_code_send_error",
   "error_description": "短信发送失败,请检查手机号码或网络状态"
   }

错误状态码400,参数数据错误，返回结果：

   {
   "error": "phonenumber_is_empty",
   "error_description": "Must inform a cellphone number."
   }

错误状态码400,参数数据错误，返回结果：

   {
   "error": "area_not_supported",
   "error_description": "不支持该区号"
   }

错误状态码400,参数数据错误，返回结果：

   {
   "error": "sms_code_send_error",
   "error_description": "短信发送失败,请检查手机号码或网络状态"
   }

通过短信验证码修改手机号码

POST 请求URL：https://account.izhiju.cn/realms/zhiju/sms/update-profile

请求头参数： Authorization: Bearer {{token}} Content-Type: application/x-www-form-urlencoded 请求体参数：

参数名	参数类型	默认值	说明
areaCode	string	86	手机号所属的区号，默认86
phoneNumber	string		手机号，11位数字
smsCode	string		短信验证码，6位数字

修改手机号码返回结果

修改成功，状态码204,无内容返回
错误状态码401,token过期或错误，返回结果：

  {
  "error_description": "need login",
  "error": "auth_invalid"
  }

错误状态码400,返回结果：

 {
  "error_description": "Must inform a phone number",
  "error": "phone_number_code_empty"
}

错误状态码400,smsCode错误，返回结果：

{
"error_description": "Token code cannot be empty",
"error": "smscode_be_empty"
}

用户头像管理

头像配置 spi-avatar-provider-config-

参数名	参数类型	默认值	说明
defaultAvatar	`string`	`/`	URL for default avatar
alwaysRedirect	`boolean`	`false`	Should always redirect to static image url
defaultSize	`string`	`lg`	Default avatar size
storageService	`string`	`file`	Provider to store avatar files

头像存储配置 spi-avatar-storage-file-

参数名	参数类型	默认值	说明
root	`string`	`/`	FS storage root path
route	`string`	`/{realm}/avatar/{avatar_id}/avatar-{size}.png`	URL and path to avatar file (Not need change)
baseurl	`string`	`/realms/`	Keycloak base url
default-avatar	`string`	`/{realm}/avatar/default.png`	Path to default avatar

接口基本参数

参数名	参数类型	默认值	说明
size	`enum<String>("xs", "sm", "md", "lg", "xl", "xxl")`	`{Config.defaultSize}`	Avatar file size
format	`enum<String>("raw", "json")`	`raw`	Response format

通过用户ID获取头像

请求： GET /realms/{realm}/avatar/by-userid/{user_id}

返回结果

没有size参数时，返回默认lg大头像，没有format参数时，默认format为raw，返回原始图片
请求参数中指定format参数为json时，返回json格式数据:

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

通过用户名获取头像

Request:

GET /realms/{realm}/avatar/by-username/{username}

Respose (While format=json):

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

获取默认头像

Request:

GET /realms/{realm}/avatar/default

Respose (While format=json):

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

上传头像

Request:

POST /realms/{realm}/avatar
Authorization: Bearer {{token}}
Content-Type: multipart/form-data

image=<image file>

account.md 23 KB Geschiedenis Ruwe

前言

概述

范围说明

账户系统

HTTP返回状态码说明

URL地址说明

用户登陆认证

微信用户注册登陆接口

应用客户端用户名密码登陆认证接口

应用客户端手机号码密码登陆认证接口

用户信息管理

获取用户信息

通过用户ID获取用户信息

通过用户手机号获取用户信息

更新用户信息

用手机号注册用户

修改用户手机号码

修改用户秘密

通过手机验证码重置密码

通过手机验证码重置密码

通过旧密码修改密码

返回结果:

小程序用户名片二维码格式

发送短信验证码

返回结果

通过短信验证码修改手机号码

修改手机号码返回结果

用户头像管理

头像配置 spi-avatar-provider-config-

头像存储配置 spi-avatar-storage-file-

接口基本参数

通过用户ID获取头像

返回结果

通过用户名获取头像

获取默认头像

上传头像

account.md 23 KB

Geschiedenis Ruwe