第三方项目接入

Kami 提供「应用 → 产品 → 套餐 → 卡密」的网络验证。第三方只需要拿到 app_id 和 app_key，调用三个接口：激活、心跳、刷新。

1. 拿到应用凭据

在管理后台「应用」里新建应用，会显示一次 app_key（ak_...）。app_id 在列表里可见。Key 只存哈希，丢了只能换 Key。

2. 激活

curl -s -X POST https://your-host/api/v1/activate \
  -H 'content-type: application/json' \
  -d '{
    "code": "XXXXXX-XXXXXX-XXXXXX-XXXXXX",
    "hwid": "64位设备指纹哈希",
    "platform": "windows",
    "app_version": "1.0.0",
    "app_id": "应用ID",
    "app_key": "ak_..."
  }'

返回：access_token、refresh_token、device_secret、lease、features。其中 device_secret 只返回一次，客户端要安全保存（Windows DPAPI / Android Keystore / 文件 0600）。

3. 心跳

ts=$(date +%s)
nonce=$(openssl rand -hex 16)
sig=$(printf "%s.%s.%s" "$ts" "$nonce" "$DEVICE_ID" | openssl dgst -sha256 -hmac "$DEVICE_SECRET" -hex | awk '{print $2}')

curl -s -X POST https://your-host/api/v1/heartbeat \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d "{\"ts\":$ts,\"nonce\":\"$nonce\",\"sig\":\"$sig\",\"metrics\":{}}"

心跳返回新的 lease、next_in、功能位；临近过期时会返回新的 access_token。

4. 刷新

curl -s -X POST https://your-host/api/v1/refresh \
  -H 'content-type: application/json' \
  -d '{"refresh_token":"R1...","device_id":"64位设备ID"}'

刷新令牌一次性轮换；旧 token 再使用会撤销整个会话。

5. 错误码

• CARD_INVALID / CARD_BANNED / CARD_EXPIRED：卡密问题
• DEVICE_LIMIT / CONCURRENCY_LIMIT：设备/并发上限
• APP_AUTH：app_id/app_key 不对
• TOKEN_EXPIRED / TOKEN_STALE：去 refresh
• REPLAY / CLOCK_SKEW：nonce 重放/时间偏差

6. 用户侧

最终用户在 用户中心 注册、每日签到领额度、用额度兑换卡密，然后把卡密填进你的客户端。