API 对接文档

概述

本服务是一套独立的卡密生成与验证系统。使用流程：

• 在管理后台「项目管理」新建一个项目，获得该项目专属的 API Key。
• 在「批量生成」中生成卡密，发放给你的用户。
• 你的客户端 / 服务端调用 /api/verify 完成验证。

卡密分两种：

鉴权方式

每个项目有两种 Key，用途和安全级别不同：

验证类接口带验证 Key：

X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxx

请求体统一使用 JSON，需带 Content-Type: application/json。任一 Key 泄漏后都可在后台单独重置，旧 Key 立即失效、且互不影响。

验证 / 激活卡密

POST/api/verify

核心接口。时长卡首次调用即激活并绑定设备；一次性卡首次调用即兑换。

请求参数

请求示例

{ "code": "VIP30-K3MF-8XQZ-P2R7-D9TN", "device_id": "a1b2c3d4" }

返回示例

// 时长卡：首次激活成功（activated = true）
{ "ok": true, "valid": true, "card_type": "time", "activated": true, "duration_days": 30, "expires_at": 1786411763468 }

// 时长卡：后续正常验证（activated = false）
{ "ok": true, "valid": true, "card_type": "time", "activated": false, "expires_at": 1786411763468 }

// 一次性兑换卡：兑换成功（仅此一次）
{ "ok": true, "valid": true, "card_type": "once", "redeemed": true }

// 验证失败：按 reason 提示用户
{ "ok": true, "valid": false, "reason": "device_mismatch", "message": "卡密已绑定其他设备" }

字段说明

查询状态（不激活）

POST/api/query

只读接口，用于查询卡密当前状态而不触发激活 / 兑换，例如客户端展示剩余天数。

// 请求
{ "code": "VIP30-K3MF-8XQZ-P2R7-D9TN" }

// 返回
{ "ok": true, "found": true, "type": "time", "status": "active", "expires_at": 1786411763468, "expired": false }

失败原因表

当 valid 为 false 时，reason 会说明原因：

管理 API服务端专用

适用场景：用户付款后由你的后台自动发卡、退款时自动封禁等。管理 Key 在后台「项目管理」中查看与重置。

生成卡密

POST/api/manage/cards/generate

// 请求
{ "count": 1, "card_type": "time", "duration_days": 30, "prefix": "VIP" }

// 返回
{ "ok": true, "batch_id": "B20260712-XXXX", "count": 1, "codes": ["VIP-K3MF-8XQZ-P2R7-D9TN"] }

封禁 / 解封卡密

POST/api/manage/cards/ban   POST/api/manage/cards/unban

// 请求
{ "code": "VIP-K3MF-8XQZ-P2R7-D9TN" }

// 返回
{ "ok": true, "banned": true }

查询与列表

GET/api/manage/cards/:code   查单张卡状态

GET/api/manage/cards   列表，支持 status / batch_id / search / page / page_size 查询参数

GET/api/manage/stats   本项目卡密数量统计

示例

curl -X POST https://license.paymesh.cn/api/manage/cards/generate \
  -H "Content-Type: application/json" \
  -H "X-Mgmt-Key: mk_xxx" \
  -d '{"count":1,"card_type":"time","duration_days":30}'

对接示例

JavaScript（Node.js / 浏览器）

const res = await fetch('https://license.paymesh.cn/api/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk_xxx',
  },
  body: JSON.stringify({ code: userInput, device_id: getDeviceId() }),
});
const data = await res.json();
if (data.valid) {
  // 放行，data.expires_at 为到期时间
} else {
  alert(data.message);
}

Python

import requests

r = requests.post(
    'https://license.paymesh.cn/api/verify',
    headers={'X-API-Key': 'sk_xxx'},
    json={'code': user_input, 'device_id': get_device_id()},
).json()

if r['valid']:
    # 放行
    pass
else:
    print(r['message'])

cURL

curl -X POST https://license.paymesh.cn/api/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_xxx" \
  -d '{"code":"VIP30-K3MF-8XQZ-P2R7-D9TN","device_id":"a1b2c3d4"}'

常见问题

device_id 应该用什么？

任何能唯一标识设备且保持稳定的字符串都可以，例如主板序列号、磁盘序列号、MAC 地址等的哈希值。同一台设备每次生成的值必须一致，否则时长卡会判定为「设备不匹配」。

API Key 会暴露在客户端里安全吗？

如果是纯客户端软件直接调用，API Key 确实会暴露，但它只有验证权限，无法生成或修改卡密。若要更严格，可由你自己的服务端持有 Key 并转发验证请求。

卡密会被猜到吗？

卡密由密码学安全随机数生成（约 80 bit 熵），且所有信息存于服务端，无法离线破解或伪造，暴力枚举在现实中不可行。