一、接口总览
| 接口名称 | 功能描述 | 请求方式 | 授权方式 | 接口版本 |
|---|---|---|---|---|
| 创建合约（createContract） | 创建用户/设备的服务合约，基于GraphQL协议实现 | POST | JWT / Bearer Token 授权 | v1 |
| 修改合约（updateContract） | 修改合约状态（激活/取消），支持延长或终止合约 | PATCH | JWT / Bearer Token 授权 | v1 |
| 删除合约（deleteContract） | 删除指定ID的合约，立即终止合约服务 | DELETE | JWT / Bearer Token 授权 | v1 |
二、创建合约接口（createContract）
用于创建用户/设备的服务合约，基于GraphQL协议实现POST请求调用，需传递用户账号、产品ID、支付订单号等核心参数，参数缺失或格式错误会返回400参数错误。前置条件：所有接口调用前需获取对应权限的 Token（服务器 Token/用户 Token），且调用者需具备对应操作权限。
（一）请求说明
1. 请求URL
POST: https://vsaas-domain/vsaas/api/v1/ss/contract
说明：仅支持POST请求方式，基于GraphQL协议实现
说明：核心参数
account、productId、transactionId为必填项，用于指定合约关联的用户、产品和支付订单信息。
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization
|
String | 是 |
授权令牌，格式：Bearer {Oauth token}
|
Content-Type
|
String | 是 |
固定值：application/json
|
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
account
|
String | 是 | BODY POST | 用户的email或者手机号，格式：base64("{\"email\":\"12345666\"}") |
productId
|
String | 是 | BODY POST | 套餐ID（plan id），关联具体的服务套餐 |
transactionId
|
String | 是 | BODY POST | 支付订单编号，唯一标识支付记录 |
note
|
String | 否 | BODY POST | 合约备注信息（可选） |
purpose
|
String | 否 | BODY POST | 设备UID（合约关联设备时必填，关联账号时无需填写） |
payment_type
|
int | 否 | BODY POST | 支付类型（仅内部记录用，TUTK不做处理） |
4. 请求体（POST 方式专用）
{
"account":"ewoJImVtYWlsIjogIjEwMDE3ODY1Igp9",
"productId":"fsajhfkjahfkjasdhfsakfha",
"transactionId":"PAY20240520001",
"purpose":"UUUUUUUUUUUUUUUUUUUU",
"note":"测试合约",
"payment_type":1
}
说明：account、productId、transactionId为必填参数，为空或格式错误会返回400参数错误；purpose参数在合约关联设备时需填写设备UID，关联账号时可忽略。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回合约信息 |
| 400 | 参数错误 | 请求参数缺失或格式错误（如account格式错误、必填参数为空） |
| 401 | 授权失败 | Oauth token无效或过期 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"contractId": "String", // 合约唯一标识
"expires": "String", // 合约到期时间（UTC格式）
"startTime": "String" // 合约生效时间（UTC格式）
}
}
3. 响应参数说明
| 字段名 | 类型 | 说明 | 返回规则 |
|---|---|---|---|
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. 响应示例（成功）
创建合约响应（示例）
{
"data": {
"contractId": "66fa0056f35e358c2arewrqggg",
"expires": "2024-02-30T01:35:18.312174281Z",
"startTime": "2024-01-30T01:35:18.312174281Z"
}
}
三、修改合约接口（updateContract）
用于修改合约状态（激活/取消），支持延长合约到期日或立即终止合约，需传递合约ID和目标状态参数，参数错误会返回400参数错误。前置条件：调用者需具备合约的修改权限，且Oauth token有效。
（一）请求说明
1. 请求URL
PATCH: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
说明：仅支持PATCH请求方式，{id}为合约ID路径参数
说明：
id为合约ID（路径参数），state为目标状态（cancel/activate），均为必填项。
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization
|
String | 是 |
授权令牌，格式：Bearer {Oauth token}
|
Content-Type
|
String | 是 |
固定值：application/json
|
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
id
|
String | 是 | PATH PATCH | 合约ID（URL路径参数），唯一标识待修改的合约 |
state
|
String | 是 | BODY PATCH | 目标状态："cancel"（立即终止）或 "activate"（延长到期日） |
4. 请求体（PATCH 方式专用）
{
"state":"cancel"
}
说明：state参数仅支持"cancel"或"activate"两个值，传入其他值会返回400参数错误；"activate"表示合约延长至下一个到期日，"cancel"表示合约立即终止。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，合约状态修改完成 |
| 400 | 参数错误 | 合约ID无效或state值错误（非cancel/activate） |
| 401 | 授权失败 | Oauth token无效或过期 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"contractId": "String", // 合约唯一标识
"expires": "String" // 修改后的合约到期时间（UTC格式）
}
}
3. 响应参数说明
| 字段名 | 类型 | 说明 | 返回规则 |
|---|---|---|---|
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路径参数，参数无效会返回400参数错误。注意：该操作不可逆，删除后合约服务立即终止，请谨慎操作。
（一）请求说明
1. 请求URL
DELETE: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
说明：仅支持DELETE请求方式，{id}为合约ID路径参数
说明：
id为合约ID（路径参数），是唯一必填项，用于指定待删除的合约。
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization
|
String | 是 |
授权令牌，格式：Bearer {Oauth token}
|
Content-Type
|
String | 是 |
固定值：application/json
|
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
id
|
String | 是 | PATH DELETE | 合约ID（URL路径参数），唯一标识待删除的合约 |
4. 请求体（DELETE 方式专用）
// DELETE请求无需请求体，仅需在URL中传递合约ID参数
说明：DELETE请求无需提交请求体，仅需确保URL中的合约ID参数有效；该操作不可逆，删除前请确认合约无需保留。
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，合约已删除 |
| 400 | 参数错误 | 合约ID无效或格式错误 |
| 401 | 授权失败 | Oauth token无效或过期 |
| 500 | 服务器错误 | 服务器内部错误，请联系技术支持排查 |
2. 响应数据结构
{
"data": {
"message": "String" // 操作结果提示信息
}
}
3. 响应参数说明
| 字段名 | 类型 | 说明 | 返回规则 |
|---|---|---|---|
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."
}
}
