API 集成文档

微客云验证系统 RESTful API 接口文档

基础信息

API地址: https://your-domain.com/api/

请求方式: 全部 POST，JSON 格式

返回格式: JSON（Content-Type: application/json）

密钥说明

集成前请先在【管理后台 → 产品管理 → 编辑】中获取以下密钥：

product_key（产品ID）

在【产品管理】列表中查看，是一个数字（如: 1, 2, 3）

示例: "1"

secret_key（产品密钥）

在【产品管理 → 编辑】中查看，48位字符串

用于 API 请求签名验证，不要泄露给客户端

encrypt_key（加密密钥）

在【产品管理 → 编辑】中查看，32位字符串

用于加密本地缓存数据，防止用户篡改授权信息

timestamp + sign（签名）

每次请求必须包含当前时间戳和签名

签名算法见下方详细说明

签名算法（重要）

所有 API 请求都需要签名验证，步骤如下：

构建请求参数（JSON对象），包含 product_key、timestamp 和业务参数

过滤空值参数（排除 sign 字段），按 key 字典序升序排列

拼接为 key=value&key=value 格式的字符串

使用 HMAC-SHA256(secret_key, signStr) 生成签名，添加到 sign 字段

签名示例（以登录验证为例）：

PHP 签名函数:

<?php
function generateSign($params, $secretKey) {
    // 1. 过滤空值和sign字段
    $filtered = [];
    foreach ($params as $k => $v) {
        if ($k === 'sign') continue;
        if ($v !== null && $v !== '' && $v !== 'undefined') {
            $filtered[$k] = (string)$v;
        }
    }
    // 2. 按key字典序排列
    ksort($filtered);
    // 3. 拼接字符串
    $signStr = '';
    foreach ($filtered as $k => $v) {
        if ($signStr !== '') $signStr .= '&';
        $signStr .= $k . '=' . $v;
    }
    // 4. HMAC-SHA256签名
    return hash_hmac('sha256', $signStr, $secretKey);
}

// 使用示例
$secretKey = 'your_secret_key_48chars';
$params = [
    'product_key' => 1,
    'timestamp' => time(),
    'username' => 'test_user',
    'password' => '123456',
    'device_id' => 'ABC123',
];
$params['sign'] = generateSign($params, $secretKey);

JavaScript 签名函数:

async function generateSign(params, secretKey) {
    // 1. 过滤空值和sign字段
    const filtered = {};
    for (const [k, v] of Object.entries(params)) {
        if (k === 'sign') continue;
        if (v !== null && v !== '' && v !== 'undefined') {
            filtered[k] = String(v);
        }
    }
    // 2. 按key字典序排列
    const sortedKeys = Object.keys(filtered).sort();
    // 3. 拼接字符串
    const signStr = sortedKeys
        .map(k => `${k}=${filtered[k]}`)
        .join('&');
    // 4. HMAC-SHA256签名
    const encoder = new TextEncoder();
    const key = await crypto.subtle.importKey(
        'raw', encoder.encode(secretKey),
        { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
    );
    const sig = await crypto.subtle.sign(
        'HMAC', key, encoder.encode(signStr)
    );
    return Array.from(new Uint8Array(sig))
        .map(b => b.toString(16).padStart(2, '0'))
        .join('');
}

// 使用示例
const params = {
    product_key: 1,
    timestamp: Math.floor(Date.now()/1000),
    username: 'test_user',
    password: '123456',
    device_id: 'ABC123',
};
params.sign = await generateSign(params, SECRET_KEY);

注意: 时间戳误差不能超过5分钟，否则请求会被拒绝。所有接口统一使用 POST + JSON 格式。

1. 登录验证

POST /api/verify.php

用户登录验证 + 设备绑定，验证通过后自动绑定设备（首次）或更新心跳（已有设备）。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名
password	string	必填	密码（明文，服务端MD5校验）
device_id	string	必填	设备唯一标识（如CPU+主板哈希）
device_name	string	选填	设备名称（如"张三的电脑"）

成功返回:

{
  "success": true,
  "code": 0,
  "message": "验证成功",
  "data": {
    "user_id": 1,
    "username": "test_user",
    "product_id": 1,
    "status": "active",
    "expire_time": 1735689600,
    "max_devices": 3,
    "device_count": 1,
    "is_expired": false,
    "encrypt_key": "abcdef1234567890abcdef1234567890"
  }
}

失败返回:

{
  "success": false,
  "code": 403,
  "message": "设备数量已达上限(3台)，请先解绑其他设备",
  "data": {
    "devices": [
      { "device_id": "AAA", "device_name": "电脑1", "ip": "1.2.3.4", "last_active": 1735600000, "bind_time": 1735500000 }
    ],
    "max_devices": 3
  }
}

2. 用户注册（卡密注册）

POST /api/register.php

使用卡密注册新用户，同时自动激活授权。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名（2-20字符，字母数字下划线）
password	string	必填	密码（4-64位）
card_key	string	必填	卡密

成功返回:

{
  "success": true,
  "code": 0,
  "message": "注册成功",
  "data": {
    "user_id": 2,
    "username": "new_user",
    "expire_time": 1738281600,
    "max_devices": 3,
    "card_type": "month",
    "encrypt_key": "abcdef1234567890abcdef1234567890"
  }
}

3. 卡密激活（已有用户续期）

POST /api/activate.php

为已有用户续期。如用户不存在，将自动创建新用户。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名
card_key	string	必填	卡密
password	string	选填	密码（新用户自动创建时使用，4-64位）

成功返回:

{
  "success": true,
  "code": 0,
  "message": "激活成功",
  "data": {
    "user_id": 1,
    "username": "test_user",
    "expire_time": 1740960000,
    "max_devices": 3,
    "card_type": "year",
    "is_new_user": false,
    "encrypt_key": "abcdef1234567890abcdef1234567890"
  }
}

4. 心跳保活

POST /api/heartbeat.php

定时上报心跳，建议每5分钟调用一次。服务端会更新设备在线状态。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名
device_id	string	必填	设备唯一标识

成功返回:

{
  "success": true,
  "code": 0,
  "message": "心跳成功",
  "data": {
    "user_id": 1,
    "expire_time": 1735689600,
    "status": "active"
  }
}

5. 查询卡密状态

POST /api/check-card.php

查询卡密状态，不会消耗卡密。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
card_key	string	必填	卡密

卡密有效返回:

{
  "success": true,
  "code": 0,
  "message": "卡密有效",
  "data": {
    "valid": true,
    "card_type": "month",
    "duration": 30,
    "max_devices": 3,
    "product_id": 1,
    "status": "unused"
  }
}

卡密已使用返回:

{
  "success": true,
  "code": 0,
  "message": "卡密已被使用",
  "data": {
    "valid": false,
    "card_type": "month",
    "duration": 30,
    "max_devices": 3,
    "product_id": 1,
    "status": "used",
    "used_by": 1,
    "used_time": 1735600000
  }
}

6. 查询用户信息

POST /api/user-info.php

查询用户信息和授权状态。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名

成功返回:

{
  "success": true,
  "code": 0,
  "message": "查询成功",
  "data": {
    "user_id": 1,
    "username": "test_user",
    "product_id": 1,
    "status": "active",
    "expire_time": 1735689600,
    "max_devices": 3,
    "device_count": 2,
    "createtime": 1735500000,
    "is_expired": false
  }
}

7. 查询设备列表

POST /api/device-info.php

查询用户已绑定的所有设备信息。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名

成功返回:

{
  "success": true,
  "code": 0,
  "message": "获取成功",
  "data": {
    "username": "test_user",
    "max_devices": 3,
    "device_count": 2,
    "online_count": 1,
    "devices": [
      {
        "id": 1,
        "device_id": "ABC123DEF456...",
        "device_id_short": "ABC123DE",
        "device_name": "张三的电脑",
        "ip_address": "192.168.1.100",
        "status": "online",
        "is_online": true,
        "last_active": 1735600000,
        "last_active_text": "5分钟前",
        "bind_time": 1735500000
      }
    ]
  }
}

8. 解绑设备

POST /api/unbind-device.php

解绑指定设备或所有设备（需密码验证）。解绑后可重新绑定新设备。

请求参数:

参数	类型	必填	说明
product_key	int	必填	产品ID
timestamp	int	必填	当前Unix时间戳（秒）
sign	string	必填	HMAC-SHA256签名
username	string	必填	用户名
password	string	必填	用户密码（明文，用于安全验证）
device_id	string	选填	要解绑的设备ID（为空则解绑所有设备）

成功返回:

{
  "success": true,
  "code": 0,
  "message": "设备解绑成功",
  "data": {
    "deleted": 1
  }
}

错误码说明

错误码	说明
400	参数错误 / 缺少必要参数 / 签名缺失 / 请求过期
401	密码错误
403	签名验证失败 / 产品已停用 / 卡密不匹配 / 设备已达上限 / 授权已过期
404	用户不存在 / 卡密不存在 / 产品不存在 / 设备未绑定
405	仅允许POST请求
409	用户名已存在
500	服务器内部错误

完整调用示例

PHP 完整示例（登录验证）:

<?php
$apiUrl = 'https://your-domain.com/api/verify.php';
$secretKey = 'your_secret_key_48chars';
$productId = 1;

// 1. 构建参数
$params = [
    'product_key' => $productId,
    'timestamp'   => time(),
    'username'    => 'test_user',
    'password'    => '123456',
    'device_id'   => 'ABC123DEF456',
];

// 2. 生成签名
function generateSign($params, $secretKey) {
    $filtered = [];
    foreach ($params as $k => $v) {
        if ($k === 'sign') continue;
        if ($v !== null && $v !== '' && $v !== 'undefined') {
            $filtered[$k] = (string)$v;
        }
    }
    ksort($filtered);
    $signStr = implode('&', array_map(
        fn($k, $v) => "$k=$v",
        array_keys($filtered), $filtered
    ));
    return hash_hmac('sha256', $signStr, $secretKey);
}

$params['sign'] = generateSign($params, $secretKey);

// 3. 发送请求
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    $data = $result['data'];
    $daysLeft = ceil(($data['expire_time'] - time()) / 86400);
    echo "验证成功，剩余 {$daysLeft} 天";
    // 保存 encrypt_key 用于本地缓存加密
    file_put_contents('cache.dat', encrypt(
        json_encode($data),
        $data['encrypt_key']
    ));
} else {
    echo "验证失败: " . $result['message'];
}

推荐：使用 SDK 快速集成

我们提供了多语言 SDK，已内置签名算法、缓存加密、设备指纹等功能，开箱即用：

Python

C#/.NET

Java

Node.js

易语言

PHP

SDK 下载请访问管理后台的【开发文档】页面，或查看 help.html。