一、对接前先确认三件事
排错之前,先确认你手上的三个值是对的——绝大多数「莫名其妙」的报错,都是这三件事没对上:
- 用户名:卡密通后台登录账号的用户名,接口地址
https://www.keyt.cn/kami/{用户名}/check.php里的那一段,注意区分大小写。 - 应用名:请求参数
app的值,必须与后台创建的应用名一致,否则系统不认这张卡。 - 签名密钥:后台「API 对接」里生成的密钥,用于计算
sign,泄露后任何人都能伪造验证结果,务必妥善保管。
标准请求格式如下(GET 请求,所有参数都要参与签名):
GET https://www.keyt.cn/kami/你的用户名/check.php?card=卡密&mac=机器码&app=应用名&heart=1&t=时间戳
正常返回:业务数据|sign=MD5(业务数据+签名密钥),其中业务数据形如 ok|valid|剩余天数|剩余分钟(终身卡为 ok|permanent);异常返回:error|错误码。
二、四个不返回错误码的常见坑
有些问题根本走不到错误码那一步,返回的是空白、超时或解析失败。这四个坑占了对接问题的一半:
| 现象 | 最常见原因 | 排查与修复 |
|---|---|---|
| 请求超时 / 404 | 接口地址拼错,或用户名带空格/特殊字符未编码 | 浏览器直接打开完整地址测试;用户名需 URL 编码 |
| 返回内容解析失败 | 没按最后一个竖线 | 拆出 sign | 用 rsplit('|', 1) 从右往左拆,不要用 find 找第一个竖线 |
| sign 校验不过 | MD5 拼接顺序错、密钥错、大小写错 | 打印「业务数据原文 + 密钥」肉眼核对,MD5 输出统一 32 位小写 |
| 提示时间戳无效 | 本机时间不准,或请求间隔超过防重放窗口 | 同步系统时间;t 用当前秒级时间戳,不要缓存复用 |
t 时间戳带防重放机制,同一个时间戳不能反复使用。每次请求都重新取当前时间,别把时间戳写死或缓存。三、8 个错误码逐一详解
下面是卡密通接口返回的全部错误码速查表,后续每个错误码都有触发原因、排查步骤和解决办法:
| 错误码 | 含义 | 常见触发场景 |
|---|---|---|
| missing_params | 缺少必要参数 | card / mac / app / t 有参数没传 |
| invalid_card | 卡密无效 | 卡密不存在、格式错、已被删除 |
| expired | 卡密已过期 | 天/周/月/年卡到期后继续使用 |
| banned | 卡密被封禁 | 违规使用被后台封禁 |
| device_mismatch | 设备不匹配 | 机器码与绑定时不一致(一机一码) |
| online_limit_reached | 在线数超限 | 同一卡密同时在线设备超过上限 |
| too_frequent | 请求过于频繁 | 短时间内请求次数过多 |
| system_locked | 系统锁定 | 验证开关被关闭或系统维护中 |
1. missing_params 缺少参数
触发原因:card、mac、app、t 四个参数至少有一个没传或值为空。
排查步骤:把实际发出的完整 URL 打印出来,逐个核对参数名和值。特别注意 mac 机器码:如果采集逻辑返回空字符串,请求就会带上空的 mac。
解决办法:给机器码采集加兜底——采集失败时生成一个固定的随机标识并持久化保存,保证每次请求 mac 都有值且稳定。
2. invalid_card 卡密无效
触发原因:卡密不存在、格式错误,或卡密不属于当前 app 应用。
排查步骤:先看卡密是否复制完整(注意别把前后空格复制进去,建议 trim 一下);再到后台该应用下查询这张卡是否存在。
解决办法:输入框统一做去空格处理;提示用户卡密是「当前应用专属」,去错应用后台查不到。
3. expired 卡密已过期
触发原因:天卡/周卡/月卡/年卡到期后再次验证,或服务器时间比用户本机时间快导致提前判定过期。
排查步骤:在后台查看该卡密的到期时间,对比当前时间;若后台显示未到期却报 expired,检查用户电脑系统时间是否被改慢。
解决办法:正常提示「卡密已过期,请续费」;若怀疑用户改时间,配合心跳(超过 55 秒不心跳即退出)可大幅减少这类钻空子行为。
4. banned 卡密被封禁
触发原因:卡密因违规(倒卖、共用、恶意刷接口等)被你在后台封禁。
排查步骤:后台卡密列表里查看该卡状态是否显示已封禁,封禁原因和时间。
解决办法:误封就解封;确属违规的可保持封禁,并在公告接口(act=get_notice)里发布说明,让客户端能展示给用户。
5. device_mismatch 设备不匹配
触发原因:卡密已绑定机器码(一机一码),当前请求的 mac 与绑定值不一致。常见于:换电脑、重装系统、硬件更换、或机器码采集逻辑不稳定(每次生成的值不一样)。
排查步骤:把两次请求的 mac 值分别打印出来对比;检查采集逻辑用的是 CPU 序列号还是硬盘序列号,是否稳定可复现。
解决办法:正常换机走后台「解绑」流程;采集不稳定则改用更稳定的标识(如 CPU 序列号 + 磁盘卷序列号组合)。一机一码原理详见《一机一码绑定》一文。
6. online_limit_reached 在线数超限
触发原因:同一张卡密同时在线设备数超过后台设置的上限(默认 1 台,多设备场景可上调)。
排查步骤:在后台查看该卡密的在线设备列表,确认是不是被多台设备同时使用;或上一台设备异常退出导致会话未及时释放(心跳超时清理有延迟)。
解决办法:正常场景等心跳超时自动释放;频繁误报就把设备上限调到实际需要值,并配合 55 秒心跳让在线状态更实时。
7. too_frequent 请求过于频繁
触发原因:短时间(如 1 秒内)连续多次调用验证接口,被频率限制拦截。
排查步骤:检查代码里是否在循环里重复调用验证、或验证成功后还在反复请求。
解决办法:验证结果做本地缓存,成功后按心跳节奏(≥50 秒,建议 55 秒)再请求;不要在启动循环、窗口重绘等高频位置直接调接口。
8. system_locked 系统锁定
触发原因:你在后台关闭了验证开关(CARD_OFF),或平台系统维护中(system_locked 状态)。
排查步骤:登录后台查看验证开关状态。
解决办法:正常运营时保持开关打开;需要临时停服(如发新版前)可先关开关,客户端应把 system_locked 显示为「系统维护中,请稍后再试」而不是「卡密无效」。
四、带调试日志的完整对接代码
下面是 Python 版本的对接代码,内置了完整日志输出:每次请求打印 URL、返回原文、解析结果、错误码分支。对接期开着日志跑一遍,任何问题都能定位到具体环节。其他语言(易语言、C#、Java、Go 等)逻辑完全一致,照搬结构即可。
import time
import hashlib
import requests
# ===== 配置区(改成你自己的) =====
USERNAME = "你的用户名" # 后台用户名
APP = "你的应用名" # 后台创建的应用名
SECRET = "你的签名密钥" # 后台 API 对接里的密钥
# ================================
def get_mac():
"""机器码采集:这里换成你项目的稳定机器码,如 CPU 序列号"""
return "机器码"
def sign(data: str) -> str:
"""签名:MD5(业务数据 + 签名密钥),32 位小写"""
return hashlib.md5((data + SECRET).encode("utf-8")).hexdigest()
def check(card: str, mac: str):
t = str(int(time.time()))
url = ("https://www.keyt.cn/kami/%s/check.php"
"?card=%s&mac=%s&app=%s&heart=1&t=%s"
% (USERNAME, card, mac, APP, t))
print("[DEBUG] 请求地址:", url)
resp = requests.get(url, timeout=10)
raw = resp.text
print("[DEBUG] 返回原文:", raw)
if raw.startswith("error|"):
code = raw.split("|")[1]
print("[DEBUG] 错误码:", code)
# 按错误码分支处理
if code == "invalid_card":
print("提示:卡密无效,请检查后重新输入")
elif code == "expired":
print("提示:卡密已过期,请续费")
elif code == "device_mismatch":
print("提示:设备不匹配,请联系客服解绑")
elif code == "online_limit_reached":
print("提示:在线设备数已达上限")
elif code == "system_locked":
print("提示:系统维护中,请稍后再试")
else:
print("提示:验证失败(%s)" % code)
return False
# 正常返回:业务数据|sign=xxx
biz, _, sign_str = raw.rpartition("|")
expect = "sign=" + sign(biz)
print("[DEBUG] 本地签名:", expect)
if sign_str != expect:
print("[DEBUG] 签名不一致!检查密钥或业务数据拼接")
return False
print("[DEBUG] 业务数据:", biz)
return True
if __name__ == "__main__":
# 验证成功后按 55 秒心跳循环保活
ok = check("你的卡密", get_mac())
while ok:
time.sleep(55)
ok = check("你的卡密", get_mac())
print("[DEBUG] ...") 全保留;上线前可以去掉或改成写日志文件。代码里所有占位符(用户名/应用名/签名密钥/卡密)都要替换成真实值。五、分步排查流程(对号入座)
- 浏览器直接打开拼接好的完整 URL——能返回正常数据,说明参数和地址没问题,问题在代码;返回错误码,进第 3 步。
- 代码里把返回原文完整打印,确认是否走到
error|分支,还是解析/签名环节就挂了。 - 有错误码:对照第三节速查表定位,90% 是卡密状态或设备绑定问题。
- 没有错误码:回到第二节四个坑,重点查签名拼接和时间戳。
- 还不行:把「请求 URL + 返回原文 + 本地签名」三段日志发给卡密通客服(QQ:345205377),一分钟内就能定位。