Smarthome API 说明文档
**版本: 1.0 **
**发布日期: 2024-03-28 **
历史记录
| 修订日期 | 版本 | 作者 | 说明 |
| --------- | ---- | ---------- | -------- |
| 2024-3-28 | V1.0 | alva.huang | 初始版本 |
| | | | |
[toc]
# 前言
## 概述
本文档旨在说明爱智居服务端的API接口，帮助开发人员如何使用smarthome api 进行开发，并详细介绍了各API的功能，调用方式，返回结果和错误码。
## Codebase
此开发文档只针对智能家居控制app，小程序，以及相应的控制端app，面板app等的开发。
# 账户系统
账户系统主要功能是用户注册，登录，修改密码，忘记密码，注销账号。用户信息维护和更新。用户权限控制。角色映射等和用户相关的功能。
## 用户登陆认证
### 微信用户注册登陆接口
用户通过微信小程序登陆，并使用微信code换取token，调用此接口完成注册和登录。
当用户第一次使用微信小程序登陆，并且没有绑定过账号时，需要传入手机号码和验证码，进行注册绑定手机号码。后续使用微信小程序登陆，不需要传入手机号码和验证码。
POST 请求URL：
[https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token](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 | 区号,可不传 |
返回结果：
1. 成功，状态码200，返回如下内容：
```json
{
"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表示用户信息
}
```
2. 微信授权码无效，状态码401，返回如下内容：
```json
{
"error": "wechat_code_invalid",
"error_description": "微信授权码无效，过期或已使用"
}
```
3. 手机验证码错误，状态码401，返回如下内容：
```json
{
"error": "sms_code_invalid",
"error_description": "手机验证码无效"
}
```
4. 手机号已绑定其他账号，状态码401，返回如下内容：
```json
{
"error": "invalid_grant",
"error_description": "Invalid user credentials"
}
```
### 客户端登陆认证接口
POST 请求URL：
[https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token](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 | 用户秘密 |
| | | | |
返回结果：
1. 成功,状态码200
```json
{
"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表示用户信息
}
```
2. 客户端授权无效，用户名或秘密错误，状态码401
```json
{
"error": "invalid_grant",
"error_description": "Invalid user credentials"
}
```
3. 客户端id或secret错误，状态码401
```json
{
"error": "invalid_client",
"error_description": "Invalid client or Invalid client credentials"
}
```
4. 不支持的授权类型，状态码401
```json
{
"error": "unsupported_grant_type",
"error_description": "Unsupported grant_type"
}
```
## 用户信息管理
### 获取用户信息
GET 请求URL：
[https://account.izhiju.cn/realms/zhiju/account](https://account.izhiju.cn/realms/zhiju/account)
请求头参数：
Content-Type: application/json
Authorization: Bearer {{token}}
返回结果：
1. 未授权，状态码401
```json
{
"error": "HTTP 401 Unauthorized",
"error_description": "For more on this error consult the server log at the debug level."
}
```
2. 成功，状态码200, 返回如下内容：
```json
{
"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"
]
}
}
```
### 更新用户信息
POST 请求URL：
[https://account.izhiju.cn/realms/zhiju/account](https://account.izhiju.cn/realms/zhiju/account)
请求头参数：
Content-Type: application/json
Authorization: Bearer {{token}}
```json
{
"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"
]
}
}
```
返回结果：
1. 未认证授权，状态码401, token错误或过期
```json
{
"error": "HTTP 401 Unauthorized",
"error_description": "For more on this error consult the server log at the debug level."
}
```
2. 更新成功，状态码204, 无内容返回
3. 更新失败，状态码400，下面为用户名不可修改返回的错误信息
```json
{
"errors": [
{
"field": "username",
"errorMessage": "error-user-attribute-read-only",
"params": [
"${username}"
]
},
{
"field": "username",
"errorMessage": "readOnlyUsernameMessage",
"params": [
"${username}"
]
}
]
}
```
### 删除用户信息