把 哨卡云 的 /v1 接口接进你的程序

01接入准备

三样东西就够：接口基址、app_key、app_secret。后两个在控制台「软件管理」里，一个软件一对，app_secret 可以随时重置。

发卡、建账号、看调用流水都在 开发者控制台 里做；接口不需要你点头，客户端自己就能把卡激活。

02请求与公共参数

一律打到 https://api.dlam.cc/v1/…。写动作只认 POST；允许 GET 的只有下面这几条只读接口，其余用 GET 打过去就是 404。参数用表单或 JSON 都收，同名时请求体覆盖查询串——建议全放请求体，别把卡密和签名挂进 URL。

只开 GET 的：/v1/card/config　/v1/user/config　/v1/software/config　/v1/software/notice　/v1/software/latest_ver　/v1/af/remote_var　/v1/af/remote_data

每条请求都要带的公共参数（它们也全部参与签名）：

03签名算法

五个要素按顺序拼成一串，做一次 MD5，十六进制小写：

sign = md5( METHOD + host + path + k1=v1&k2=v2&…&kn=vn + app_secret )

三个必须照做的口径

• 排的是整条 k=v 字符串，不是参数名。差别在数字后缀上：app_key2=b 排在 app_key=a 前面（因为 2 的字节小于 =）。
• value 原样拼，不做 URL 编码。编码发生在 HTTP 层，签名算的是编码前那串。值里带 &、=、空格时尤其容易错。
• 数组与对象类型的参数不参与签名。要传结构化数据（比如远程函数的 params），先自己 JSON 化成字符串再传。

<?php
$HOST   = 'api.dlam.cc';          // 只写域名：不带 https://、不带端口。它参与签名
$SECRET = '你的 app_secret';       // 只参与计算，不打印、不写日志

function scx_sign($method, $path, array $p, $host, $secret)
{
    $kv = [];
    foreach ($p as $k => $v) {
        if (is_array($v)) continue;          // 数组不参与签名
        $kv[] = $k . '=' . $v;               // value 原样拼，不做 URL 编码
    }
    usort($kv, 'strcmp');                    // 排的是整条 k=v，不是参数名
    return md5(strtoupper($method) . $host . $path . implode('&', $kv) . $secret);
}

function scx_call($path, array $p, $method = 'POST')
{
    global $HOST, $SECRET;
    $p['app_key']   = '你的 app_key';
    $p['timestamp'] = time();
    $p['nonce']     = bin2hex(random_bytes(8));        // 每次都要新，≤36 位
    $p['sign']      = scx_sign($method, $path, $p, $HOST, $SECRET);

    $ch = curl_init('https://' . $HOST . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => http_build_query($p),
    ]);
    $raw = curl_exec($ch);
    if ($raw === false) {
        $err = curl_error($ch); curl_close($ch);
        return ['code' => -1, 'message' => '网络异常：' . $err];
    }
    curl_close($ch);
    $j = json_decode((string)$raw, true);
    return is_array($j) ? $j : ['code' => -2, 'message' => '返回不是合法 JSON'];
}

$r = scx_call('/v1/card/login', ['card' => '卡密', 'device_id' => '机器码']);
if (isset($r['code']) && (int)$r['code'] === 0) {
    $res = $r['result'];
    echo '可用到 ' . ($res['expires'] !== '' ? $res['expires'] : '不限时长')
       . '，每 ' . $res['hg'] . ' 秒发一次心跳' . PHP_EOL;
    // 之后：scx_call('/v1/card/heartbeat', ['card'=>'卡密','token'=>$res['token']]);
} else {
    echo $r['code'] . ' · ' . $r['message'] . PHP_EOL;   // 含义见「返回码对照」
}

import hashlib, hmac, json, time, uuid, requests

HOST   = "api.dlam.cc"            # 只写域名，它参与签名
SECRET = "你的 app_secret"
APP_KEY = "你的 app_key"

def sign(method, path, params):
    kv = [f"{k}={params[k]}" for k in params if k != "sign" and not isinstance(params[k], (list, dict))]
    kv.sort()                                   # 排的是整条 k=v，不是参数名
    raw = method.upper() + HOST + path + "&".join(kv) + SECRET
    return hashlib.md5(raw.encode()).hexdigest()

def call(path, params, method="POST"):
    p = dict(params)
    p.update(app_key=APP_KEY, timestamp=int(time.time()), nonce=uuid.uuid4().hex)
    p["sign"] = sign(method, path, p)
    r = requests.request(method, f"https://{HOST}{path}", data=p, timeout=10)
    return r.json()

res = call("/v1/card/login", {"card": "卡密", "device_id": "机器码"})
if res["code"] == 0:
    print("可用到", res["result"]["expires"], "心跳", res["result"]["hg"], "秒")
else:
    print(res["code"], res["message"])

04响应与双向签名

返回永远是这一个信封。成功是 code = 0，不是 200；HTTP 状态码一律 200，成败只看 code。

{
  "code": 0,
  "message": "ok",
  "result": {
    "card_type": "会员",
    "token": "k3f9dq2m1x7b5p0c",
    "expires": "2026-11-19 14:20:31",
    "expires_ts": 1795742431,
    "config": "",
    "server_time": 1792548031,
    "hg": 600
  },
  "nonce": "bqzp3k1k00a00",
  "sign": "0d4f6a9c2b1e5837a0c94d2f6b1e0735"
}

sign = md5( code + message + k1=v1&k2=v2&… + nonce + app_secret )

中间的 k=v 串取的是响应 result 里所有非数组字段，同样按整条 k=v 排序后连接；拼接处没有分隔符。result 为空时那一段是空字符串——不是 0，也不是 null。失败响应照样签名，SDK 里对 code≠0 不校验也不亏。

05接口清单（24 条）

按组排开，每条列请求参数、成功返回的字段、以及实践里真会撞上的失败码。参数名一字不差照抄——多带一个不认识的参数，签名就算不过。

01卡密组 · 8 条

登录

成功时 result 里带：

可能的失败：400 参数错误　10230 软件不存在，请检查 app_key　10218 卡密不可用　10212 卡密已被冻结　10210 卡密已过期　10215 只能在首次登录绑定的设备上使用　10213 卡密超过多开上限

首次登录那一刻就是激活：会员与单码的到期时间从这时起算，卖卡前提醒用户「装好再激活」。同一台设备重复登录会复用还没过期的那个令牌，不会多占一个多开名额；软件开了「顶号」时反过来——每次登录把其它在线会话撤掉。次数卡与积分卡在这一步扣一次，心跳不扣量。

心跳

成功时 result 里带：

可能的失败：400 参数错误　10214 登录状态已失效　10218 卡密不可用　10212 卡密已被冻结

心跳只续令牌，不续卡。超过 token 有效期没打心跳，令牌自己失效，下一次要回登录；卡在这期间到期或被冻结，心跳同样回失败，客户端要立刻锁功能，不能拿登录时的旧结果继续跑。

退出

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10214 登录状态已失效

已经失效的令牌再退一次也回 10214。这不是「退出失败」，本地配置清干净就行，别弹错误给用户看。

解绑

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10216 软件未开启解绑设备功能　10255 该卡密不可解绑设备　10257 卡密剩余时间已不足以解绑扣除　10214 登录状态已失效　10212 卡密已被冻结　10218 卡密不可用

解绑成功后这个令牌一并作废，客户端要重新走登录。软件设了「解绑扣时」的话，卡的到期时间会往前挪那个分钟数；剩余时间不足以扣时就直接拒（10257）。

设解绑密码

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10214 登录状态已失效　10218 卡密不可用

解绑密码存在卡上，是给人「忘带电脑」用的兜底，不要拿它当账号密码，也别用它替代 token。

密码解绑

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10216 软件未开启解绑设备功能　10254 解绑密码不正确　10255 该卡密不可解绑设备　10257 卡密剩余时间已不足以解绑扣除　10212 卡密已被冻结　10218 卡密不可用

这条是免登录换机的入口：在新机器上直接调，解完还要回 /v1/card/login 才能真正登录，它自己不签发令牌。

充值

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10240 卡密不存在或已被使用　10241 卡密已被使用　10244 不能对未使用的卡密进行充值　10256 卡密多开配置不相等，不能充值　10212 卡密已被冻结

供体卡的天数（含零头分钟）、次数、积分都并进目标卡，随后供体变成「已使用」。时长是从现在往后加，不追回目标卡已经过掉的那几天。成功只有 code=0，想知道续到了哪天，再调一次登录看 expires。

卡密配置

成功时 result 里带：

可能的失败：400 参数错误　10218 卡密不可用　10212 卡密已被冻结

这对接口只验软件签名，不认任何卡密凭证：拿着 app_secret 的人能读写任意一张卡的配置。别在这串里放密钥。另外 GET 成功不写用卡记录，POST 才写一行。

02用户组 · 8 条

用户注册

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10240 卡密不存在或已被使用　10241 卡密已被使用　10242 账号已存在　10210 卡密已过期　10212 卡密已被冻结

注册即激活，不需要先调 /v1/card/login：卡当场变成「已使用」并挂进账号名下，账号与这张主卡共用同一个到期点。注册成功后直接走用户登录拿令牌。

用户登录

成功时 result 里带：

可能的失败：400 参数错误　10243 用户登录密码错误　10250 用户已到期　10252 用户已被冻结　10218 卡密不可用　10253 用户超过多开上限　10215 只能在首次登录绑定的设备上使用

用户侧的扣量发生在登录：账号名下若有带次数或积分的卡，这次登录从其中一张扣一次；心跳只保活。名下卡池烧空时回 10218，这时该引导用户「用户充值」补一张进去。

用户心跳

成功时 result 里带：

可能的失败：400 参数错误　10214 登录状态已失效　10250 用户已到期　10252 用户已被冻结

心跳期间账号到期（10250）或被冻结（10252）都会在这里爆出来，和卡密侧一样要立刻锁功能。

用户退出

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10214 登录状态已失效

用户改密

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10243 用户登录密码错误

改密成功即下线：这个账号名下所有在线令牌全部作废，其它设备下一次心跳就是 10214，得重新登录。这是设计，不是 bug。

用户充值

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10240 卡密不存在或已被使用　10241 卡密已被使用　10244 不能对未使用的卡密进行充值　10252 用户已被冻结　10256 卡密多开配置不相等，不能充值

充进去的是账号名下那张主卡的额度：天数并进到期时间，次数与积分留在供体卡上、变成卡池里可烧的一张。账号侧的流水记在「以卡充卡记录」里，充值对象那一列写的是用户名。

用户解绑

成功只有 code=0，没有 result——别去取返回体里的字段。

可能的失败：400 参数错误　10216 软件未开启解绑设备功能　10255 该卡密不可解绑设备　10257 卡密剩余时间已不足以解绑扣除　10214 登录状态已失效

上限取账号上的多开数，超限回 10253（卡密侧同类情况回 10213）。解掉的是这台设备在账号侧与卡侧的全部绑定记录。

用户配置

成功时 result 里带：

可能的失败：400 参数错误　10243 用户登录密码错误　10252 用户已被冻结

和卡密配置同样的信任模型：只认签名不认用户凭证，别放敏感数据。GET 成功不写用卡记录。

03软件组 · 3 条

软件配置

除公共参数外不带业务参数。

成功时 result 里带：

可能的失败：400 参数错误　10230 软件不存在，请检查 app_key　10212 卡密已被冻结

软件公告

除公共参数外不带业务参数。

成功时 result 里带：

可能的失败：400 参数错误　10230 软件不存在，请检查 app_key　10212 卡密已被冻结

版本检查

成功时 result 里带：

可能的失败：400 参数错误　10304 已经是最新版本　10230 软件不存在，请检查 app_key　10212 卡密已被冻结

已是最新时回 10304，不是 code=0 加一个空结果——把 10304 当「没更新」处理，别弹错误窗口。当前版本取「配置软件 → 版本配置」里最新那条，历史版本只用来查说明与下载地址。成功不写用卡记录。

04试用组 · 2 条

试用登录

成功时 result 里带：

可能的失败：400 参数错误　10401 软件未开启试用　10402 试用中，请勿重复登录　10403 已试用过了　10407 本周期试用次数已用完

试用没有令牌：device_id 就是身份，心跳带同一个设备码。正在试用中重复登录回 10402，那是「你已经在试用里」，改用心跳即可；软件开了「一台设备只能试用一次」时用过就永久 10403，否则按周期次数计，用完 10407。

试用心跳

成功时 result 里带：

可能的失败：400 参数错误　10401 软件未开启试用　10405 试用已到期　10406 本周期试用已到期

试用心跳把到期时间整段往前推，所以「一直开着程序」能一直用到周期上限；到期后回 10405／10406，该引导付费了。

05高级功能组 · 3 条

远程变量

成功时 result 里带：

可能的失败：400 参数错误　10501 远程变量不存在　10214 登录状态已失效　10601 本月高级功能调用量已用完

参数名是 key。变量勾了「校验 token」时，card＋token 变成必传，读的人必须是正在用的卡。成功不写用卡记录（这是热路径），但照样进高级功能的月调用量。

远程数据

成功时 result 里带：

可能的失败：400 参数错误　10521 远程数据不存在　10522 远程数据 key 已存在　10601 本月高级功能调用量已用完

读写同一个 URL，靠 METHOD 区分：读用 GET＋key，增改删用 POST＋action。delete 不要带 value——带了会让签名多算一项、必报 10010（服务端虽然会抹掉空值，但你的签名是在抹掉之前算的）。写成功会留下一行用卡记录，写着 create · 键名。

远程函数

成功时 result 里带：

可能的失败：400 参数错误　10541 远程函数不存在　10542 参数(params)必须为 json 列表序列化后的 string　10543 远程函数调用错误　10601 本月高级功能调用量已用完

跑的是控制台里那条受限表达式，白名单解释器，不执行 PHP、读不到服务器文件。实参按声明的形参名按位置绑定。返回值是 JSON 字符串，要再解一次。撞 10543 时 message 里是具体原因（哪一步算错了）。

06五种卡与计时

客户端的调用方式对五种卡完全一样，差别只在服务端扣什么、expires 有没有值。类型在控制台生成卡密时选定。

时长按「天数＋零头分钟」两个字段给，所以能出 30 天的卡，也能出 45 分钟的卡。时长从激活那一刻起算，不是从卖出去那天。

07会话、心跳与多开

这一节是「为什么用户说他还开着程序，却突然不能用了」的答案。

08高级功能与配额

三条接口解决「不改客户端也能调整」的三件事：读一个服务端写的值、存一个小值、让服务端算一道题。

这一组按自然月计调用量，控制台给每个开发者设了每月上限，撞上限后整组回 10601。当前阶段只挡量、不收费。

09返回码对照（44 个）

message 已经是给人看的话，直接显示即可；下表这一列告诉你该让用户做什么。码出自服务端那张表，和 message 永远一致。

10客户端落地建议

启动:
  本地卡密 = 读配置()
  没有卡密 → 输入卡密 → 调 /v1/card/login(card, device_id)
  code != 0 → 按返回码分支：
      10218 / 10240 → 让用户核对卡号，不要自动重试
      10215 / 10213 → 走解绑或联系客服
      10212 / 10210 → 原样显示 message，给续费或客服入口
      10010 附近    → 这是接入代码的问题，写进本地日志，别弹给用户
  code == 0 → 存下 result.token / result.expires，用 result.server_time 校准本地时钟
             用 result.hg 起一个心跳定时器
运行中:
  每 hg 秒 → /v1/card/heartbeat(card, token)
      0       → 继续跑
      10214   → 令牌没了，回登录流程
      其它    → 立即锁功能并显示 message
  网络失败 → 最多重试 2 次；期间可用上次成功结果宽限，但宽限不超过 expires
退出/关机:
  /v1/card/logout(card, token) → 无论成败都清本地令牌

用户报「验证失败」时开发者怎么查

控制台 用卡记录 是排障第一现场：按卡密、账号、机器码或 IP 查那一次调用，写明返回码与人话原因。要区分的是——

• 成功的调用由接口按端点记账：写动作（登录、心跳、注册、充值、解绑、写配置、写远程数据）成功都留一行。
• 失败的不管哪条都留一行，包括签名没过、软件被停用。
• 成功时不写这张表的有七条纯读接口：软件配置、软件公告、版本检查、远程变量、远程函数，以及只认签名的 GET 卡密配置、GET 用户配置。它们的量只进概览的调用统计。