一、接口總覽
| 接口名稱 | 功能描述 | 請求方式 | 授權方式 | 接口版本 |
|---|---|---|---|---|
| 創(chuàng)建合約（createContract） | 創(chuàng)建用戶/設備的服務合約，基于GraphQL協(xié)議實現(xiàn) | POST | JWT / Bearer Token 授權 | v1 |
| 修改合約（updateContract） | 修改合約狀態(tài)（激活/取消），支持延長或終止合約 | PATCH | JWT / Bearer Token 授權 | v1 |
| 刪除合約（deleteContract） | 刪除指定ID的合約，立即終止合約服務 | DELETE | JWT / Bearer Token 授權 | v1 |
二、創(chuàng)建合約接口（createContract）
用于創(chuàng)建用戶/設備的服務合約，基于GraphQL協(xié)議實現(xiàn)POST請求調(diào)用，需傳遞用戶賬號、產(chǎn)品ID、支付訂單號等核心參數(shù)，參數(shù)缺失或格式錯誤會返回400參數(shù)錯誤。前置條件：所有接口調(diào)用前需獲取對應權限的 Token（服務器 Token/用戶 Token），且調(diào)用者需具備對應操作權限。
（一）請求說明
1. 請求URL
POST: https://vsaas-domain/vsaas/api/v1/ss/contract
說明：僅支持POST請求方式，基于GraphQL協(xié)議實現(xiàn)
說明：核心參數(shù)
account、productId、transactionId為必填項，用于指定合約關聯(lián)的用戶、產(chǎn)品和支付訂單信息。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權令牌，格式：Bearer {Oauth token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
account | String | 是 | BODY POST | 用戶的email或者手機號，格式：base64("{\"email\":\"12345666\"}") |
productId | String | 是 | BODY POST | 套餐ID（plan id），關聯(lián)具體的服務套餐 |
transactionId | String | 是 | BODY POST | 支付訂單編號，唯一標識支付記錄 |
note | String | 否 | BODY POST | 合約備注信息（可選） |
purpose | String | 否 | BODY POST | 設備UID（合約關聯(lián)設備時必填，關聯(lián)賬號時無需填寫） |
payment_type | int | 否 | BODY POST | 支付類型（僅內(nèi)部記錄用，TUTK不做處理） |
4. 請求體（POST 方式專用）
{
"account":"ewoJImVtYWlsIjogIjEwMDE3ODY1Igp9",
"productId":"fsajhfkjahfkjasdhfsakfha",
"transactionId":"PAY20240520001",
"purpose":"UUUUUUUUUUUUUUUUUUUU",
"note":"測試合約",
"payment_type":1
}
說明：account、productId、transactionId為必填參數(shù)，為空或格式錯誤會返回400參數(shù)錯誤；purpose參數(shù)在合約關聯(lián)設備時需填寫設備UID，關聯(lián)賬號時可忽略。
（二）響應說明
1. 響應狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回合約信息 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)缺失或格式錯誤（如account格式錯誤、必填參數(shù)為空） |
| 401 | 授權失敗 | Oauth token無效或過期 |
| 500 | 服務器錯誤 | 服務器內(nèi)部錯誤，請聯(lián)系技術支持排查 |
2. 響應數(shù)據(jù)結構
{
"data": {
"contractId": "String", // 合約唯一標識
"expires": "String", // 合約到期時間（UTC格式）
"startTime": "String" // 合約生效時間（UTC格式）
}
}
3. 響應參數(shù)說明
| 字段名 | 類型 | 說明 | 返回規(guī)則 |
|---|---|---|---|
contractId | String | 合約唯一標識ID | 必返回 |
expires | String | 合約到期時間（UTC格式，如2024-02-30T01:35:18.312174281Z） | 必返回 |
startTime | String | 合約生效時間（UTC格式） | 必返回 |
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer' \
-d '{"account":"ewoJImVtYWlsIjogIjEwMDE3ODY1Igp9","productId":"fsajhfkjahfkjasdhfsakfha","transactionId":"PAY20240520001","purpose":"UUUUUUUUUUUUUUUUUUUU"}' \
https://vsaas-domain/vsaas/api/v1/ss/contract
2. 響應示例（成功）
創(chuàng)建合約響應（示例）
{
"data": {
"contractId": "66fa0056f35e358c2arewrqggg",
"expires": "2024-02-30T01:35:18.312174281Z",
"startTime": "2024-01-30T01:35:18.312174281Z"
}
}
三、修改合約接口（updateContract）
用于修改合約狀態(tài)（激活/取消），支持延長合約到期日或立即終止合約，需傳遞合約ID和目標狀態(tài)參數(shù)，參數(shù)錯誤會返回400參數(shù)錯誤。前置條件：調(diào)用者需具備合約的修改權限，且Oauth token有效。
（一）請求說明
1. 請求URL
PATCH: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
說明：僅支持PATCH請求方式，{id}為合約ID路徑參數(shù)
說明：
id為合約ID（路徑參數(shù)），state為目標狀態(tài)（cancel/activate），均為必填項。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權令牌，格式：Bearer {Oauth token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
id | String | 是 | PATH PATCH | 合約ID（URL路徑參數(shù)），唯一標識待修改的合約 |
state | String | 是 | BODY PATCH | 目標狀態(tài)："cancel"（立即終止）或 "activate"（延長到期日） |
4. 請求體（PATCH 方式專用）
{
"state":"cancel"
}
說明：state參數(shù)僅支持"cancel"或"activate"兩個值，傳入其他值會返回400參數(shù)錯誤；"activate"表示合約延長至下一個到期日，"cancel"表示合約立即終止。
（二）響應說明
1. 響應狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，合約狀態(tài)修改完成 |
| 400 | 參數(shù)錯誤 | 合約ID無效或state值錯誤（非cancel/activate） |
| 401 | 授權失敗 | Oauth token無效或過期 |
| 500 | 服務器錯誤 | 服務器內(nèi)部錯誤，請聯(lián)系技術支持排查 |
2. 響應數(shù)據(jù)結構
{
"data": {
"contractId": "String", // 合約唯一標識
"expires": "String" // 修改后的合約到期時間（UTC格式）
}
}
3. 響應參數(shù)說明
| 字段名 | 類型 | 說明 | 返回規(guī)則 |
|---|---|---|---|
contractId | String | 合約唯一標識ID | 必返回 |
expires | String | 修改后的合約到期時間（UTC格式） | 必返回 |
（三）接口示例
1. 請求示例（curl）
PATCH方式請求（示例）
curl -X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer' \
-d '{"state":"cancel"}' \
http://vsaas-domain/vsaas/api/v1/ss/contract/93FEE01553D71FE0AA0F
2. 響應示例（成功）
修改合約響應（示例）
{
"data": {
"contractId": "93FEE01553D71FE0AA0F",
"expires": "2024-01-30T01:35:18.312174281Z"
}
}
四、刪除合約接口（deleteContract）
用于刪除指定ID的合約，立即終止合約服務，僅需傳遞合約ID路徑參數(shù)，參數(shù)無效會返回400參數(shù)錯誤。注意：該操作不可逆，刪除后合約服務立即終止，請謹慎操作。
（一）請求說明
1. 請求URL
DELETE: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
說明：僅支持DELETE請求方式，{id}為合約ID路徑參數(shù)
說明：
id為合約ID（路徑參數(shù)），是唯一必填項，用于指定待刪除的合約。2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權令牌，格式：Bearer {Oauth token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
id | String | 是 | PATH DELETE | 合約ID（URL路徑參數(shù)），唯一標識待刪除的合約 |
4. 請求體（DELETE 方式專用）
// DELETE請求無需請求體，僅需在URL中傳遞合約ID參數(shù)
說明：DELETE請求無需提交請求體，僅需確保URL中的合約ID參數(shù)有效；該操作不可逆，刪除前請確認合約無需保留。
（二）響應說明
1. 響應狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，合約已刪除 |
| 400 | 參數(shù)錯誤 | 合約ID無效或格式錯誤 |
| 401 | 授權失敗 | Oauth token無效或過期 |
| 500 | 服務器錯誤 | 服務器內(nèi)部錯誤，請聯(lián)系技術支持排查 |
2. 響應數(shù)據(jù)結構
{
"data": {
"message": "String" // 操作結果提示信息
}
}
3. 響應參數(shù)說明
| 字段名 | 類型 | 說明 | 返回規(guī)則 |
|---|---|---|---|
message | String | 操作結果提示（如"Terminate contract success."） | 必返回 |
（三）接口示例
1. 請求示例（curl）
DELETE方式請求（示例）
curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer' \
http://vsaas-domain/vsaas/api/v1/ss/contract/93FEE01553D71FE0AA0F
2. 響應示例（成功）
刪除合約響應（示例）
{
"data": {
"message": "Terminate contract success."
}
}
