一、概述
本文檔涵蓋 VSaaS 平臺核心接口，包含兩大部分：
1. Token 獲取：分為服務(wù)器級 VSaaS Token（server oauth token）和用戶級 VSaaS Token（user vsaas token），是調(diào)用所有接口的前置條件；
2. 強綁設(shè)備：解決用戶退貨未解綁設(shè)備的場景，支持將設(shè)備強制綁定到新賬戶。
前置條件：所有接口調(diào)用前需獲取對應(yīng)權(quán)限的 Token（服務(wù)器 Token/用戶 Token），且調(diào)用者需具備對應(yīng)操作權(quán)限（如設(shè)備所有權(quán)、服務(wù)器級授權(quán)）。
1. Token 獲取：分為服務(wù)器級 VSaaS Token（server oauth token）和用戶級 VSaaS Token（user vsaas token），是調(diào)用所有接口的前置條件；
2. 強綁設(shè)備：解決用戶退貨未解綁設(shè)備的場景，支持將設(shè)備強制綁定到新賬戶。
前置條件：所有接口調(diào)用前需獲取對應(yīng)權(quán)限的 Token（服務(wù)器 Token/用戶 Token），且調(diào)用者需具備對應(yīng)操作權(quán)限（如設(shè)備所有權(quán)、服務(wù)器級授權(quán)）。
二、VSaaS Token 獲取接口
（一）獲取服務(wù)器級 VSaaS Token（server oauth token）
從 TUTK VSaaS 平臺獲取服務(wù)器級 Token，用于后續(xù)調(diào)用用戶 Token 獲取、強綁設(shè)備等需要服務(wù)器級權(quán)限的接口，需使用 TUTK 提供的 client_id 和 client_secret 進行 Base64 編碼授權(quán)。
1. 請求說明
| 項 | 說明 |
|---|---|
| HTTP請求方式 | POST |
| 請求URL | https://vsaas-domain/vsaas/api/v1/ss/oauth_token |
| 請求頭（Header） | Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/x-www-form-urlencoded（必傳） |
2. 請求參數(shù)
| 參數(shù)類型 | 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|---|
| URL參數(shù) | realm | String | 是 | 由TUTK提供，用以區(qū)分不同客戶 |
| 表單參數(shù) | grant_type | String | 是 | 固定值：client_credentials |
3. 響應(yīng)說明
3.1 響應(yīng)參數(shù)
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| data.token.access_token | String | 服務(wù)器級 VSaaS Token（server oauth token） |
| data.token.token_type | String | 固定返回：Bearer |
| data.token.expires_in | Number | Token 有效期（秒），示例：2592000 |
| data.token.refresh_token | String | 空值，無需刷新 Token |
| data.token.scope | String | 權(quán)限類型，示例：vsaas.ss.contract.action.all |
3.2 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回 Token 信息 |
| 400 | 參數(shù)錯誤 | 必填參數(shù)缺失、realm 無效、grant_type 錯誤 |
| 401 | 授權(quán)失敗 | client_id/client_secret 無效、Base64 編碼錯誤 |
4. 請求示例（curl）
curl --location --request POST 'https://vsaas-domain/vsaas/api/v1/ss/oauth_token?realm=aaaa' \
--header 'Authorization: Basic TVZPVUJRMzVsYnNTNmJGVzlQQmNMc2UzVjNaWkRZUUtmYno0UXlYTjpTZXJjck12czM2VXVjbXZnVk1UOHQ3dFc3eHJpMG56bnhwNlRuT3VCOHVuNkU3RjJreW5SWllxSmJFc2RiTEh4WmFsbUlncllCZnQ0NjdmSUx6aXRjaGxCM0RSdUxUR3djM2RYY0d2N3c5NlR3dVRkMEx5WEFKM1hMNE4zRTdUWg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=client_credentials'
5. 響應(yīng)示例（成功）
{
"data": {
"token": {
"access_token": "Sz05S5sWOrssssssPsi5M",
"expires_in": 2592000,
"refresh_token": "",
"scope": "vsaas.ss.contract.action.all",
"token_type": "Bearer"
}
}
}
（二）獲取用戶級 VSaaS Token（user vsaas token）
基于服務(wù)器級 Token 獲取指定用戶的 VSaaS Token，用于后續(xù)操作該用戶的設(shè)備（如分享、管理），支持通過郵箱/手機號/用戶ID指定用戶。
1. 請求說明
| 項 | 說明 |
|---|---|
| HTTP請求方式 | POST |
| 請求URL | https://vsaas-domain/vsaas/api/v1/ss/login |
| 請求頭（Header） | Authorization: Bearer {server_token}（服務(wù)器級 Token） Content-Type: application/json（必傳） |
2. 請求參數(shù)
| 參數(shù)類型 | 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|---|
| JSON參數(shù) | email/account | String | 是 | 用戶標識：郵箱、手機號或用戶ID（二選一傳入） |
3. 響應(yīng)說明
3.1 響應(yīng)參數(shù)
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
| data.access_token | String | 用戶級 VSaaS Token（user vsaas token） |
| data.token_type | String | 固定返回：Bearer |
| data.expires_in | String | Token 有效期（秒），示例：3600 |
| data.refresh_token | String | 空值，無需刷新 Token |
| data.scopes | Array | 權(quán)限列表，示例：["read", "write"] |
3.2 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回用戶 Token 信息 |
| 400 | 參數(shù)錯誤 | 用戶標識缺失、格式錯誤 |
| 401 | 授權(quán)失敗 | 服務(wù)器 Token 無效/過期、用戶不存在 |
4. 請求示例（curl）
curl --location --request POST 'https://vsaas-domain/vsaas/api/v1/ss/login' \
--header 'Authorization: Bearer LKdkjlk8873BNN' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "abc@def.com"
}'
5. 響應(yīng)示例（成功）
{
"data": {
"access_token": "WpgE1ke2squVznSSvJiJ",
"expires_in": "3600",
"refresh_token": "",
"scopes": ["read", "write"],
"token_type": "Bearer"
}
}
