单卡云验证系统 API 开发文档

接口认证

所有请求必须携带以下认证参数：

参数名	类型	必填	说明
`api_secret`	string	必填	API密钥，在个人中心页面获取
`timestamp`	int	必填	时间戳（秒），与服务器时间差不能超过300秒
`nonce`	string	必填	6-32位随机字符串，5分钟内不可重复使用
`sign`	string	必填	签名，MD5大写
`action`	string	必填	接口名称

签名算法

签名生成步骤：

将所有参数（不含 sign）按 key 升序排列
拼接格式：key1=value1&key2=value2&...
末尾拼接：&key=API_SECRET&username=USERNAME
MD5加密后转大写

示例：
参数: action=card_list, timestamp=1699000000, nonce=abc123
拼接: action=card_list&nonce=abc123×tamp=1699000000&key=your_secret&username=admin
签名: MD5(拼接字符串).toUpperCase()
结果: 8A1F3D7B9C2E5F8A1B3C5D7E9F2A4B6D

返回格式

所有接口统一返回 JSON 格式：

{
  "code": 0,
  "msg": "成功",
  "data": {}
}

字段	类型	说明
`code`	int	状态码，0表示成功，其他为错误码
`msg`	string	提示信息
`data`	object/array	返回数据（对象或数组）

{
  "code": -1,
  "msg": "参数错误",
  "data": null
}

请求示例

使用 curl 发送请求：

curl -X POST http://card.geticp.cn/api/user_api.php \
  -F "action=card_list" \
  -F "api_secret=your_api_secret_here" \
  -F "timestamp=1699000000" \
  -F "nonce=abc123def456" \
  -F "sign=8A1F3D7B9C2E5F8A1B3C5D7E9F2A4B6D"

使用 PHP 发送请求：

<?php
$url = 'http://card.geticp.cn/api/user_api.php';
$params = [
    'action' => 'card_list',
    'api_secret' => 'your_secret',
    'timestamp' => time(),
    'nonce' => substr(md5(rand()), 0, 16)
];
// 签名计算（按key升序）
ksort($params);
$sign_str = http_build_query($params) . '&key=' . $params['api_secret'] . '&username=admin';
$params['sign'] = strtoupper(md5($sign_str));

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($result, true));
?>

卡密管理

POST card_list - 查询卡密列表

获取用户的卡密列表，支持分页和筛选

参数名	类型	必填	说明
page	int	可选	页码，默认1
filter_type	int	可选	卡种ID筛选
filter_status	int	可选	状态：0未激活、1已激活、2已过期、3已封禁
filter_keyword	string	可选	关键词搜索

请求示例：

curl -X POST http://card.geticp.cn/api/user_api.php \
  -F "action=card_list" \
  -F "api_secret=xxx" \
  -F "timestamp=1699000000" \
  -F "nonce=abc123" \
  -F "sign=xxx" \
  -F "page=1"

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "card_key_raw": "ABCDEFGHIJKLMNOP",
        "type_id": "TYPE001",
        "type_name": "测试卡种",
        "card_type": 1,
        "time_value": 30,
        "time_unit": 3,
        "status": 1,
        "status_text": "已激活",
        "active_time": "2024-01-01 10:00:00",
        "expire_time": "2024-01-31 10:00:00",
        "bind_device": "DEVICE-001",
        "last_heartbeat": 1699000000,
        "total_days": 30,
        "remain_days": 15,
        "total_times": 0,
        "remain_times": 0
      }
    ],
    "total": 100,
    "page": 1,
    "totalPage": 10
  }
}

POST card_detail - 查询卡密详情

根据卡密ID查询详细信息

参数名	类型	必填	说明
id	int	必填	卡密ID

请求示例：

curl -X POST http://card.geticp.cn/api/user_api.php \
  -F "action=card_detail" \
  -F "api_secret=xxx" \
  -F "timestamp=1699000000" \
  -F "nonce=abc123" \
  -F "sign=xxx" \
  -F "id=1"

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 1,
    "card_key_raw": "ABCDEFGHIJKLMNOP",
    "type_id": "TYPE001",
    "type_name": "测试卡种",
    "card_type": 1,
    "time_value": 30,
    "time_unit": 3,
    "status": 1,
    "status_text": "已激活",
    "active_time": "2024-01-01 10:00:00",
    "expire_time": "2024-01-31 10:00:00",
    "bind_device": "DEVICE-001",
    "last_heartbeat": 1699000000
  }
}

POST card_generate - 批量生成卡密

批量生成指定数量的卡密

参数名	类型	必填	说明
type_id	int	必填	卡种ID
card_type	int	必填	类型：1时长卡、2次数卡
time_value	int	必填	时长值/次数
time_unit	int	必填	单位：1分钟、2小时、3天、4月、5年
num	int	必填	生成数量

请求示例：

curl -X POST http://card.geticp.cn/api/user_api.php \
  -F "action=card_generate" \
  -F "api_secret=xxx" \
  -F "timestamp=1699000000" \
  -F "nonce=abc123" \
  -F "sign=xxx" \
  -F "type_id=1" \
  -F "card_type=1" \
  -F "time_value=30" \
  -F "time_unit=3" \
  -F "num=10"

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "生成成功",
  "data": {
    "count": 10,
    "cards": [
      {"id": 101, "card_key": "ABC123"},
      {"id": 102, "card_key": "DEF456"},
      {"id": 103, "card_key": "GHI789"}
    ]
  }
}

POST card_add - 单条新增卡密

手动添加单条卡密

参数名	类型	必填	说明
type_id	int	必填	卡种ID
card_key	string	必填	卡密内容
card_type	int	必填	类型：1时长卡、2次数卡
time_value	int	必填	时长值/次数
time_unit	int	可选	单位（时长卡）

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "添加成功",
  "data": {"id": 101}
}

POST card_delete - 删除卡密

删除指定卡密

参数名	类型	必填	说明
id	int	必填	卡密ID

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "删除成功",
  "data": null
}

POST card_batch_delete - 批量删除卡密

批量删除多个卡密

参数名	类型	必填	说明
ids	string	必填	卡密ID列表，逗号分隔

请求示例：

curl -X POST ... -F "ids=1,2,3,4,5"

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "成功删除3条记录",
  "data": {"deleted": 3}
}

POST card_edit - 修改卡密信息

修改卡密的类型、时长或次数

参数名	类型	必填	说明
id	int	必填	卡密ID
card_type	int	必填	类型：1时长卡、2次数卡
time_value	int	必填	时长值/次数
time_unit	int	可选	单位（时长卡）
total_times	int	可选	总次数（次数卡）

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "修改成功",
  "data": {"diff_cost": 10.00}
}

POST card_ban / card_unban - 封禁/解封卡密

封禁或解封指定卡密

参数名	类型	必填	说明
id	int	必填	卡密ID

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "封禁成功",
  "data": null
}

卡种分类

POST type_list - 查询卡种列表

获取用户的卡种列表

返回示例（JSON对象，data为数组）：

{
  "code": 0,
  "msg": "成功",
  "data": [
    {"id": 1, "name": "测试卡种", "remark": "测试用", "status": 1},
    {"id": 2, "name": "正式卡种", "remark": "正式使用", "status": 1}
  ]
}

POST type_save - 保存卡种

新增或编辑卡种

参数名	类型	必填	说明
id	int	可选	卡种ID（编辑时必填）
name	string	必填	卡种名称
remark	string	可选	备注说明

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "保存成功",
  "data": {"id": 3}
}

POST type_delete - 删除卡种

删除指定卡种（该卡种下的所有卡密将一并删除）

参数名	类型	必填	说明
id	int	必填	卡种ID

在线监控

POST online_list - 查询在线列表

获取当前在线的卡密列表

返回示例（JSON对象，data为数组）：

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "id": 1,
      "card_key_raw": "ABC123",
      "device_code": "DEVICE-001",
      "active_time": "2024-01-01 10:00:00",
      "last_heartbeat": 1699000000,
      "expire_time": "2024-01-31 10:00:00"
    }
  ]
}

POST online_kick - 强制下线

强制指定卡密下线

参数名	类型	必填	说明
card_id	int	必填	卡密ID

系统设置

POST setting_get - 查询设置

获取系统设置

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "heartbeat_interval": 30,
    "bind_device": 1
  }
}

POST setting_save - 保存设置

保存系统设置

参数名	类型	必填	说明
heartbeat_interval	int	可选	心跳间隔（秒）
bind_device	int	可选	是否绑定设备：0否、1是

IP黑白名单

POST blacklist / whitelist - 查询黑白名单

查询IP黑名单或白名单列表

返回示例（JSON对象，data为数组）：

{
  "code": 0,
  "msg": "成功",
  "data": [
    {"id": 1, "ip": "192.168.1.100", "remark": "恶意IP", "create_time": "2024-01-01 10:00:00"}
  ]
}

POST blacklist_add / whitelist_add - 添加黑白名单

添加IP到黑名单或白名单

参数名	类型	必填	说明
ip	string	必填	IP地址
remark	string	可选	备注说明

公告管理

POST notice_list - 查询公告

获取公告列表

返回示例（JSON对象，data为数组）：

{
  "code": 0,
  "msg": "成功",
  "data": [
    {"id": 1, "title": "系统维护通知", "content": "系统将于今晚维护", "create_time": "2024-01-01 10:00:00"}
  ]
}

POST notice_add - 发布公告

发布新公告

参数名	类型	必填	说明
title	string	必填	公告标题
content	string	必填	公告内容

用户账号

POST user_info - 查询用户信息

获取当前用户信息

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 1,
    "username": "admin",
    "balance": 100.00,
    "is_vip": true,
    "vip_end_time": "2024-12-31 23:59:59",
    "create_time": "2024-01-01 10:00:00"
  }
}

客户端接口

以下接口面向终端用户客户端使用，签名方式与服务端接口相同

POST card_activate - 卡密激活

激活卡密并绑定设备

参数名	类型	必填	说明
card_key	string	必填	卡密内容
device_code	string	必填	设备标识码

请求示例：

curl -X POST http://card.geticp.cn/api/user_api.php \
  -F "action=card_activate" \
  -F "api_secret=xxx" \
  -F "timestamp=1699000000" \
  -F "nonce=abc123" \
  -F "sign=xxx" \
  -F "card_key=ABCDEFGHIJKLMN" \
  -F "device_code=DEVICE-001"

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "激活成功",
  "data": {
    "card_key": "ABCDEFGHIJKLMN",
    "expire_time": "2024-01-31 10:00:00",
    "remaining_days": 30
  }
}

//如果已经激活，返回如下信息

{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "card_key": "IYR3NHOFS07UI46V4KGV4KM7",
    "card_type": 1,
    "remain_days": 60,
    "remain_times": 0,
    "expire_time": "2024-08-03 11:18:16",
    "heartbeat_interval": 60
  }
}

POST heartbeat - 心跳保活

客户端定期发送心跳保持在线状态

参数名	类型	必填	说明
card_key	string	必填	卡密内容
device_code	string	必填	设备标识码

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "心跳正常",
  "data": {
    "card_key": "IYR3NHOFS07UI46V4KGV4KM7",
    "card_type": 1,
    "remain_days": 60,
    "remain_times": 0,
    "expire_time": "2024-08-03 11:18:16",
    "heartbeat_interval": 60
  }
}

POST card_query - 查询卡密

查询卡密状态和信息

参数名	类型	必填	说明
card_key	string	必填	卡密内容
device_code	string	必填	设备标识码

返回示例（JSON对象）：

{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "card_key": "IYR3NHOFS07UI46V4KGV4KM7",
    "status": 1,
    "status_text": "已激活",
    "card_type": 1,
    "card_type_text": "时长卡",
    "total_days": 60,
    "total_times": 0,
    "remain_days": 60,
    "remain_times": 0,
    "bind_device": "TEST-DEVICE-001...",
    "active_time": "2024-06-04 11:18:16",
    "expire_time": "2024-08-03 11:18:16",
    "heartbeat_interval": 60
  }
}

POST notice - 获取公告

获取系统公告列表

返回示例（JSON对象，data为数组）：

{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "notices": [
      {
        "title": "系统公告",
        "content": "欢迎使用",
        "create_time": "2024-06-04 12:05:57"
      }
    ]
  }
}