一、接口总览
| 接口名称 | 功能描述 | 请求方式 | 授权方式 | 接口版本 |
|---|---|---|---|---|
| 合约绑定设备（create_binding） | 将方案绑定到指定设备 | POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 查询合约（getContract） | 根据合约ID查询合约详情 | GET | JWT / Bearer Token 授权 | v1 |
| 设备合约解绑（remove_binding） | 将方案与设备解绑 | POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 方案列表查询（get_contract_list） | 查询当前用户的所有方案列表 | POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 方案转移（transferContract） | 将方案从源设备转移到目标设备 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
本章节介绍TUTK VSaaS平台合约管理核心API接口（GraphQL版本），第三方系统可通过这些接口完成合约绑定、查询、解绑、方案列表查询、方案转移等操作，所有接口均需携带有效的VSaaS Token完成身份认证。
二、合约绑定设备接口（create_binding）
用于将方案绑定到指定设备，需传递方案Contract ID和设备UDID，两个参数均为必填项，为空或格式错误会返回400参数错误。
（一）请求说明
1. 请求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
说明：仅支持POST方式，基于GraphQL协议提交请求
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
contract | String | 是 | GraphQL参数 MUTATION | 方案的Contract ID，不能为空或格式错误 |
device | String | 是 | GraphQL参数 MUTATION | 设备端的UDID（唯一标识），不能为空或格式错误 |
4. 请求体（POST 方式专用）
{
"query": "mutation {create_binding(contract:\"方案Contract ID\",device:\"设备UDID\")}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回绑定结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、Contract ID/设备UDID为空/格式错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
2. 响应数据结构
{
"data": {
"create_binding": "方案绑定结果（Bind contract finish. 或错误信息）"
}
}
（三）接口示例
1. 请求示例（curl）
POST方式请求（示例）
curl -XPOST -H 'Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
-H 'Content-Type: application/json' \
-d '{"query": "mutation {create_binding(contract:\"5c3c685d023bde0e7828aa4a\",device:\"QWERTYUIOPPOIUYTREWQ\")}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 响应示例（成功）
合约绑定响应（示例）
{
"data": {
"create_binding": "Bind contract finish."
}
}
三、查询合约接口（getContract）
用于根据合约ID查询合约详情，需在URL路径中传递合约ID，该参数为空或格式错误会返回400参数错误。
（一）请求说明
1. 请求URL
GET: http://vsaas-domain/vsaas/api/v1/ss/contract/{id}
说明：仅支持GET方式，合约ID需拼接在URL路径中
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 路径参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
id | String | 是 | URL路径 PATH | 合约ID，不能为空或格式错误 |
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回合约详情 |
| 400 | 参数错误 | 请求参数错误（如合约ID为空/格式错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
2. 响应数据结构
{
"data": {
"durationType": "时长类型",
"expires": "到期时间",
"state": "合约状态",
"contractId": "合约ID"
}
}
（三）接口示例
1. 请求示例（curl）
GET方式请求（示例）
curl \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer yJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
http://vsaas-domain/vsaas/api/v1/ss/contract/93FEE01553D71FE0AA0F
2. 响应示例（成功）
查询合约响应（示例）
{
"data": {
"durationType": "Regular",
"expires": "2019-10-02T03:12:19.948Z",
"state": "Expired",
"contractId": "93FEE01553D71FE0AA0F"
}
}
四、设备合约解绑接口（remove_binding）
用于将方案与设备解绑，需传递设备UDID，该参数为空或格式错误会返回400参数错误。
（一）请求说明
1. 请求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
说明：仅支持POST方式，基于GraphQL协议提交请求
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 MUTATION | 设备端的UDID（唯一标识），不能为空或格式错误 |
4. 请求体（POST 方式专用）
{
"query": "mutation {remove_binding(device:\"设备UDID\")}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回解绑结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、设备UDID为空/格式错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
2. 响应数据结构
{
"data": {
"remove_binding": "方案解绑结果（remove contract finish. 或错误信息）"
}
}
（三）接口示例
1. 请求示例（curl）
POST方式请求（示例）
curl -XPOST -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
-H 'Content-Type: application/json' \
-d '{"query": "mutation {remove_binding(device:\"POIUYTREWQQWERTYUIOP\")}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 响应示例（成功）
合约解绑响应（示例）
{
"data": {
"remove_binding": "remove contract finish."
}
}
五、方案列表查询接口（get_contract_list）
用于查询当前用户的所有方案列表，支持传递设备UDID或事件ID作为筛选条件，也可空参数查询全部方案，支持GraphQL按需指定返回字段。
（一）请求说明
1. 请求URL
POST: https://vsaas-domain/vsaas/api/v1/be/
说明：仅支持POST方式，基于GraphQL协议提交请求
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 否 | GraphQL参数 QUERY | 设备端的UDID，用于筛选指定设备的方案 |
pk | String | 否 | GraphQL参数 QUERY | 事件的ID，用于筛选指定事件的方案 |
4. 请求体（POST 方式专用）
{
"query": "query {get_contract_list {pk,account,duration_type,state,created,updated,expires,nickname,description,devices{udid}}}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回方案列表数据 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、字段名拼写错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
2. 响应数据结构
{
"data": {
"get_contract_list": [方案对象数组]
}
}
3. 方案对象字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
pk | String | 事件ID |
account | String | 账户 |
duration_type | String | 时长类型 |
state | String | 合约状态 |
created | String | 创建时间 |
updated | String | 修改时间 |
expires | String | 到期时间 |
nickname | String | 方案名称 |
description | String | 方案描述 |
devices | Array | 设备列表（包含udid字段） |
（三）接口示例
1. 请求示例（curl）
POST方式请求（示例）
curl -XPOST -H 'Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODAyODgzNzksImlhdCI6MTU0ODc1MjM3OSwiaWQiOiI1YjFkZjY1ZGYwYjMyODRkMGRjNTU5YWYiLCJ0YWciOiIxMWUwMjI0MyJ9.JBFyr3XZUa_95uZHMZrx-tXyTCIfBlBQGY2GWvGQloQ' \
-H 'Content-Type: application/json' \
-d '{"query": "query {get_contract_list {pk,account,duration_type,state,created,updated,expires,nickname,description,devices{udid}}}"}' \
https://vsaas-domain/vsaas/api/v1/be/
2. 响应示例（成功）
查询方案列表响应（示例）
{
"data": {
"get_contract_list": [
{
"account": "5b1df65df0b3284d0dc559af",
"devices": [
{
"udid":"QWERTYUIOPPOIUYTREWW"
}
],
"created": "2019-02-21T10:15:13.055Z",
"description": "7 days general event plan",
"expires": "2019-03-02T00:00:00Z",
"nickname": "GeneralEvent7DaysPlan",
"media_type": "FREE_PLAN",
"pk": "5c6e7a311d41c87815d585ed",
"state": "Activated",
"duration_type": "Regular",
"updated": "2019-02-21T10:15:13.055Z"
}
]
}
}
六、方案转移接口（transferContract）
用于将方案从源设备转移到目标设备，需传递源设备UID和目标设备UID，两个参数均为必填项，为空或格式错误会返回400参数错误。
（一）请求说明
1. 请求URL
GET: /vsaas/api/v1/be?query=mutation+{transferContract(from:String!,to:String!) String!}
POST: /vsaas/api/v1/be/
说明：支持GET和POST两种请求方式，推荐使用POST方式
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
from | String | 是 | GraphQL参数 MUTATION | 源设备UID，不能为空或格式错误 |
to | String | 是 | GraphQL参数 MUTATION | 目标设备UID，不能为空或格式错误 |
4. 请求体（POST 方式专用）
{
"query": "mutation {transferContract(from:\"源设备UID\",to:\"目标设备UID\")}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回转移结果 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、设备UID为空/格式错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
2. 响应数据结构
{
"data": {
"transferContract": "转移结果（ok 或错误信息）"
}
}
（三）接口示例
1. 请求示例（curl）
POST方式请求（示例）
curl --location --request POST 'https://vsaas-domain/vsaas/api/v1/be/' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{"query": "mutation {transferContract(from:\"udid1\",to:\"udid2\")}"}'
2. 响应示例（成功）
方案转移响应（示例）
{
"data": {
"transferContract": "ok"
}
}
