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

请求头参数： 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"
}

用户信息管理

获取用户信息

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."
}
```
1. 成功，状态码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

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

{
  "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"
    ]
  }
}

返回结果：

未认证授权，状态码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}"
]
}
]
}

account.md 7.8 KB

تاريخچه خام

前言

概述

Codebase

账户系统

用户登陆认证

微信用户注册登陆接口

客户端登陆认证接口

用户信息管理

获取用户信息

更新用户信息

删除用户信息

account.md 7.8 KB تاريخچه خام

前言

概述

Codebase

账户系统

用户登陆认证

微信用户注册登陆接口

客户端登陆认证接口

用户信息管理

获取用户信息

更新用户信息

删除用户信息

account.md 7.8 KB

تاريخچه خام