标准单码登录

标准单码登录包含 HTTP 与 SDK 两种客户端形式，两者共用 card_login 权限和配额。

先确认平台配置

选择项目后开通“标准 API 基础包”，并确认项目验证开关已开启。

打开接口中心

HTTP V3

POSThttps://gnyanzheng.cn/api/legacy/v3/cards/loginHMAC-SHA256

请求基址使用当前平台正式 HTTPS 域名。接口只接受 POST；如果响应为 HTML 或发生重定向，应先检查地址和 Nginx 路由，不要继续按 JSON 解析。

V3 固定使用 HTTPS + HMAC，并始终返回 JSON。项目安全页中的 RC4 / AES data 传输加密只供传统 HTTP V1 兼容客户端使用，不作用于此入口；V3 请求不要发送 data 密文。

http

POST /api/legacy/v3/cards/login
Content-Type: application/x-www-form-urlencoded
X-GN-Timestamp: 1720000000
X-GN-Nonce: UNIQUE_NONCE
X-GN-Signature: HMAC_SIGNATURE

app=YOUR_PROGRAM_ID&kami=YOUR_CARD&imei=DEVICE_ID

字段	必填	说明
`app`	是	用户中心显示的程序 ID
`kami`	是	卡密
`imei`	是	稳定设备码

程序 ID 就是请求体中的 app，只使用用户中心显示的公开程序 ID，无需任何内部项目 ID。

app 必须作为普通表单字段发送。缺少 app、把程序 ID 放入 data，或者发送数据库内部项目主键，都会在解密或业务处理前被拒绝。

签名规则见 V1 / V3 签名。

SDK

SDK 固定使用 /api/v1/cards/login，负责签名、会话令牌和心跳。不要手工把 HTTP V3 请求头传入 SDK 方法。

POSThttps://gnyanzheng.cn/api/v1/cards/login官方 SDK

成功响应

json

{
  "code": 0,
  "msg": "登录成功",
  "token": "...",
  "statecode": "...",
  "data": {
    "id": 1,
    "code": "YOUR_CARD",
    "machine_code": "DEVICE_ID",
    "expires_at": "2026-12-31 23:59:59"
  }
}

标准卡密登录成功时 code === 0（卡密登录固定使用 OK_LEGACY）。响应同时带 success 字段，建议按 success 判断或同时接受 code === 0 || code === 1，不要写死单一数字——同一平台其它接口族的成功码不同（解绑是 1）。request_id 可能通过响应体或 X-Request-Id 响应头提供；字段以线上接口实际返回为准，客户端应兼容新增字段。

HTTP V3 返回兼容登录 token，但不创建 SDK 会话。客户端需要在线守护时应使用官方 SDK，保存 SDK 返回的 session_token，再进入 SDK 心跳链路。

失败处理

卡密无效、过期、封禁：直接提示用户，不做系统重试。
签名失败：核对项目协议、原始 BODY、程序 ID 和签名密钥。
系统错误并带请求 ID：保留 ID 交给管理员或项目作者排查。

仍无法定位时，先到运行健康查看项目状态；若响应带请求 ID，再提交工单并附上脱敏信息。

标准单码登录 ​

HTTP V3 ​

SDK ​

成功响应 ​

失败处理 ​

标准单码登录

HTTP V3

SDK

成功响应

失败处理