接口说明

花验文档

接口统一走 /public/api.php，通过 action 和接口专属 api_code 路由。

协议入口

URL

/public/api.php

Method

GET / POST

Content

Form / JSON

api_code=当前接口专属码
action=login
data={...}
time2=1714656000000
sign=按当前接口签名规则计算

api_code：每个 action 使用自己的接口专属码。

data：业务参数 JSON；开启加密时为加密后的字符串。

sign：按当前接口签名规则计算。

成功时 msg 是对象。

失败时 msg 是字符串，可直接显示。

check 是返回校验值。

当前应用接口专属码

后端按 action + api_code 定位接口。登录码不能拿去调心跳或公告。

未选择应用

登录控制台并选择应用后，这里会显示真实接口专属码。

Sign / Check

通信加密

开启

算法

aes-256-gcm

签名规则

md5|[time][api_code][value]

Sign：默认规则是 md5|[time][api_code][value]。接口配置了 custom_check_rule 时，以接口配置为准。

Check：md5(code + "|" + time + "|" + api_code + "|" + json_encode(msg))。

API 接口

13 个接口

公共失败 msg

请求参数不完整接口专属码或接口不存在请求时间超出允许误差当前 IP 已被禁止访问系统维护中版本过低，请更新后使用当前应用要求绑定设备码禁止使用代理访问签名不能为空签名校验失败安全协议不匹配，请更新 SDK

loginPOST卡密登录

校验卡密，绑定设备，并返回 token、到期时间、剩余秒数、点数和建议心跳间隔。免费模式可以不传 card。

请求参数

card：卡密。兼容 kami/card_key/license

mac：设备码。兼容 markcode/hwid/device_id

ver：客户端版本号，可选

返回字段

msg.id：卡密 ID

msg.kmtype：卡密时长类型

msg.token：登录 token，心跳和同行接口需要提交

msg.note：卡密备注

msg.ktype：授权类型，code 或 single

msg.vip：到期时间戳

msg.expire：到期时间文本

msg.endtime：到期时间戳，和 vip 一致

msg.type：卡密类型

msg.status：卡密状态

msg.card：当前卡密

msg.remain_seconds：剩余秒数

msg.points：剩余点数

msg.heartbeat_interval：建议心跳间隔，单位秒

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

请输入授权卡密授权卡密不存在该卡密已被封禁授权已过期点数已耗尽已达到最大设备绑定上限数据库操作失败

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "login",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "card": "TEST-CARD-001",
        "mac": "DEVICE-001",
        "ver": "1.0.0"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "id": 1,
        "kmtype": "daily",
        "token": "abcdef123456",
        "note": "测试卡密",
        "ktype": "code",
        "vip": 1714742400,
        "expire": "2024-05-03 00:00:00",
        "endtime": 1714742400,
        "type": "daily",
        "status": "active",
        "card": "TEST-CARD-001",
        "remain_seconds": 86400,
        "points": 0,
        "heartbeat_interval": 120
    },
    "time": 1714656000,
    "check": "f5392ac599d5b8d305caa2be1cebb74b"
}

失败响应

{
    "code": 400,
    "msg": "请输入授权卡密",
    "time": 1714656000,
    "check": "4471c36f08e5a7915a710c4e0fa2298e"
}

heartbeatPOST在线心跳

提交 card 和 token，刷新在线时间。应用设置里可添加最多 5 个自定义上报字段，例如 playername。

请求参数

card：卡密。兼容 kami/card_key/license

token：登录接口返回的 token，必填

mac：设备码。兼容 markcode/hwid/device_id；开启设备验证时必填

data：业务参数 JSON；开启加密时为加密后的字符串

time2：当前毫秒时间戳；开启时间校验时提交

sign：开启签名时提交签名

自定义字段：后台配置后提交，例如 playername=张三

返回字段

msg.online：是否在线，成功为 true

msg.extra：本次收到的自定义上报字段

msg.command：后台下发的命令，没有命令时不存在

msg.id：卡密 ID

msg.kmtype：卡密时长类型

msg.token：登录 token，心跳和同行接口需要提交

msg.note：卡密备注

msg.ktype：授权类型，code 或 single

msg.vip：到期时间戳

msg.expire：到期时间文本

msg.endtime：到期时间戳，和 vip 一致

msg.type：卡密类型

msg.status：卡密状态

msg.card：当前卡密

msg.remain_seconds：剩余秒数

msg.points：剩余点数

msg.heartbeat_interval：建议心跳间隔，单位秒

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

请提交卡密 card请提交登录 token卡密不存在该卡密已被封禁授权已过期点数已耗尽会话已过期，请重新登录设备码与当前会话不匹配

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "heartbeat",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "card": "TEST-CARD-001",
        "token": "abcdef123456",
        "mac": "DEVICE-001",
        "playername": "张三"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "id": 1,
        "kmtype": "daily",
        "token": "abcdef123456",
        "note": "测试卡密",
        "ktype": "code",
        "vip": 1714742400,
        "expire": "2024-05-03 00:00:00",
        "endtime": 1714742400,
        "type": "daily",
        "status": "active",
        "card": "TEST-CARD-001",
        "remain_seconds": 86000,
        "points": 0,
        "heartbeat_interval": 120,
        "online": true,
        "extra": {
            "playername": "张三"
        }
    },
    "time": 1714656000,
    "check": "e00f4b57d175c93167c08f952c224c78"
}

失败响应

{
    "code": 400,
    "msg": "请提交卡密 card",
    "time": 1714656000,
    "check": "78a3d7d2be330d6a5c93a0cfec38287d"
}

get_online_countPOST在线人数

返回当前应用在线会话数量。统计规则和在线设备页面一致，按心跳有效期判断。

请求参数

无额外业务参数

返回字段

msg.app_id：应用 ID

msg.online_count：当前在线人数

msg.heartbeat_timeout：心跳有效期，单位秒

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

没有接口专属失败原因，失败时返回公共 msg。

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "get_online_count",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {}
}

成功响应

{
    "code": 200,
    "msg": {
        "app_id": 1,
        "online_count": 12,
        "heartbeat_timeout": 300
    },
    "time": 1714656000,
    "check": "e6b2a787bf0afa868081b49c8122c13b"
}

失败响应

{
    "code": 400,
    "msg": "请求参数不完整",
    "time": 1714656000,
    "check": "7155e0973ce7497912a2dadaac24dba1"
}

unbindPOST卡密解绑

解绑指定设备。传 all=1 时清空全部绑定设备。

请求参数

card：卡密。兼容 kami/card_key/license

mac：要解绑的设备码

all：传 1 时清空全部设备，可选

返回字段

msg.num：剩余绑定设备数

msg.left：剩余解绑次数

msg.card：卡密

msg.markcode：本次解绑设备码

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

卡密和设备码不能为空卡密不存在该卡密已被封禁该卡密未绑定任何设备当前设备未绑定该卡密

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "unbind",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "card": "TEST-CARD-001",
        "mac": "DEVICE-001"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "num": 0,
        "left": 4,
        "card": "TEST-CARD-001",
        "markcode": "DEVICE-001"
    },
    "time": 1714656000,
    "check": "38f1c736e196fc2ed7538ae6811f10ec"
}

失败响应

{
    "code": 400,
    "msg": "卡密和设备码不能为空",
    "time": 1714656000,
    "check": "47d8c4853a18cfbb6dd1ddf1ebe6e467"
}

disable_cardPOST禁用卡密

把当前应用内指定卡密状态改为 banned。必须使用 disable_card 自己的接口专属码。

请求参数

card：卡密。兼容 kami/card_key/license

返回字段

msg.text：禁用成功或卡密已是禁用状态

msg.card：卡密

msg.status：禁用后为 banned

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

卡密不能为空卡密不存在卡密已是禁用状态

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "disable_card",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "card": "TEST-CARD-001"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "text": "禁用成功",
        "card": "TEST-CARD-001",
        "status": "banned"
    },
    "time": 1714656000,
    "check": "e734c1967a0ef845a3e248205923650b"
}

失败响应

{
    "code": 400,
    "msg": "卡密不能为空",
    "time": 1714656000,
    "check": "ea932974d255510c507db0a6bea151bb"
}

peer_reportPOST同行上报

上传渠道、玩家数据和辅助名字。后台按渠道和玩家数据自动去重。

请求参数

token：登录返回的 token

mac：设备码；免费模式必填，兼容 markcode

channel：渠道标识，在同行识别页面创建

player_data：玩家数据，可传玩家名、UID 或组合数据

helper_name：辅助名字

返回字段

msg.id：记录 ID

msg.channel：渠道标识

msg.channel_name：渠道名称

msg.duplicate：本次是否命中旧记录

msg.player_data：玩家数据

msg.helper_name：本次上报的辅助名字

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

同行系统已关闭请提交登录 token请提交设备码 mac会话已过期，请重新登录请提交渠道 channel请提交玩家数据 player_data请提交辅助名字 helper_name渠道不存在或已关闭

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "peer_report",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "token": "abcdef123456",
        "mac": "DEVICE-001",
        "channel": "game_a",
        "player_data": "PLAYER_10001",
        "helper_name": "辅助A"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "id": 1,
        "channel": "game_a",
        "channel_name": "某游戏",
        "duplicate": false,
        "player_data": "PLAYER_10001",
        "helper_name": "辅助A"
    },
    "time": 1714656000,
    "check": "836126cbefaaf44d69a468663a325b73"
}

失败响应

{
    "code": 400,
    "msg": "同行系统已关闭",
    "time": 1714656000,
    "check": "96cf5bb388f25dd2cf49f3ad773155e8"
}

peer_queryPOST同行查询

按渠道返回同行记录。传 player_data 时查询单条，不传时返回最近记录，最多 50 条。

请求参数

token：登录返回的 token

mac：设备码；免费模式必填，兼容 markcode

channel：渠道标识

player_data：玩家数据，可选；传了只查这一条

limit：返回条数，可选，1-50

返回字段

msg.channel：渠道标识

msg.channel_name：渠道名称

msg.exists：传 player_data 时返回是否存在

msg.item：单条记录，不存在时为 null

msg.items：最近记录列表

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

同行系统已关闭请提交登录 token请提交设备码 mac会话已过期，请重新登录请提交渠道 channel渠道不存在或已关闭

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "peer_query",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "token": "abcdef123456",
        "mac": "DEVICE-001",
        "channel": "game_a",
        "player_data": "PLAYER_10001"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "channel": "game_a",
        "channel_name": "某游戏",
        "exists": true,
        "item": {
            "id": 1,
            "player_data": "PLAYER_10001",
            "helper_name": "辅助A"
        }
    },
    "time": 1714656000,
    "check": "e2bf5d386252797b1ea7c86f19ea6a50"
}

失败响应

{
    "code": 400,
    "msg": "同行系统已关闭",
    "time": 1714656000,
    "check": "96cf5bb388f25dd2cf49f3ad773155e8"
}

get_varPOST远程变量

读取后台变量。变量不存在或停用时 exists=false，msg 为空字符串。

请求参数

var_key：变量名，和 key 二选一

key：变量名，和 var_key 二选一

返回字段

msg.msg：变量内容，不存在或停用时为空字符串

msg.key：请求的变量名

msg.exists：变量是否存在且启用

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

变量名不能为空

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "get_var",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "var_key": "notice_text"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "msg": "远程变量内容",
        "key": "notice_text",
        "exists": true
    },
    "time": 1714656000,
    "check": "f4035c056673916669f42bbc362437fa"
}

失败响应

{
    "code": 400,
    "msg": "变量名不能为空",
    "time": 1714656000,
    "check": "098ada3240223bc46029bb4140bf004d"
}

get_noticePOST获取公告

返回应用公告内容、公告是否存在和服务器时间。

请求参数

无额外业务参数

返回字段

msg.app_gg：公告文本；没有公告时为“暂无公告”

msg.has_notice：后台是否配置了非空公告

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

没有接口专属失败原因，失败时返回公共 msg。

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "get_notice",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {}
}

成功响应

{
    "code": 200,
    "msg": {
        "app_gg": "欢迎使用 花验",
        "has_notice": true
    },
    "time": 1714656000,
    "check": "59dfdc5ac400feeaddfaaea6df1d8900"
}

失败响应

{
    "code": 400,
    "msg": "请求参数不完整",
    "time": 1714656000,
    "check": "7155e0973ce7497912a2dadaac24dba1"
}

check_updatePOST检查更新

按客户端版本号判断是否需要更新，返回最新版、下载地址、强制更新状态和更新说明。

请求参数

ver：客户端当前版本号，和 version 二选一

version：客户端当前版本号，和 ver 二选一

返回字段

msg.update：是否需要更新

msg.version：后台最新版本

msg.updateshow：更新说明

msg.updateurl：下载地址；不需要更新时为空

msg.updatemust：是否强制更新，y/n

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

版本过低，请更新后使用

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "check_update",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "ver": "1.0.0"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "update": true,
        "version": "1.1.0",
        "updateshow": "修复问题",
        "updateurl": "https://example.com/app.apk",
        "updatemust": "n"
    },
    "time": 1714656000,
    "check": "4c2e86fd86fc8c6da7a969c1cb085ba2"
}

失败响应

{
    "code": 400,
    "msg": "版本过低，请更新后使用",
    "time": 1714656000,
    "check": "4992deb2703a165da0bc40b79f7c5655"
}

card_user_loginPOST账号登录

账号密码模式登录，成功后返回和卡密登录一致的授权字段，并附带 username。

请求参数

username：用户名

password：密码

mac：设备码，可选

返回字段

msg.id：卡密 ID

msg.kmtype：卡密时长类型

msg.token：登录 token，心跳和同行接口需要提交

msg.note：卡密备注

msg.ktype：授权类型，code 或 single

msg.vip：到期时间戳

msg.expire：到期时间文本

msg.endtime：到期时间戳，和 vip 一致

msg.type：卡密类型

msg.status：卡密状态

msg.card：当前卡密

msg.remain_seconds：剩余秒数

msg.points：剩余点数

msg.heartbeat_interval：建议心跳间隔，单位秒

time：服务器 Unix 时间戳

check：返回校验值

msg.username：用户名

失败 msg

请输入账号和密码账号已被封禁账号授权已过期账号或密码错误

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "card_user_login",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "username": "demo_user",
        "password": "123456",
        "mac": "DEVICE-001"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "id": 1,
        "kmtype": "daily",
        "token": "abcdef123456",
        "note": "测试账号",
        "ktype": "code",
        "vip": 1714742400,
        "expire": "2024-05-03 00:00:00",
        "endtime": 1714742400,
        "type": "daily",
        "status": "active",
        "card": "TEST-CARD-001",
        "remain_seconds": 86400,
        "points": 0,
        "heartbeat_interval": 120,
        "username": "demo_user"
    },
    "time": 1714656000,
    "check": "69648af94ee05b03db124fca1defbbe5"
}

失败响应

{
    "code": 400,
    "msg": "请输入账号和密码",
    "time": 1714656000,
    "check": "4a2b56cad9498d45c30c1c771788b989"
}

card_user_regPOST账号注册绑定

把卡密绑定到账号密码，校验卡密状态、账号唯一性和密码长度。

请求参数

card：卡密

username：用户名，长度 3-32 位

password：密码，长度 6-72 位

返回字段

msg.text：账号注册并绑定成功

msg.username：用户名

msg.card：绑定卡密

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

卡密、账号或密码不能为空账号长度需要在 3-32 位之间密码长度需要在 6-72 位之间卡密不存在该卡密已被封禁该卡密已绑定过账号该账号已存在

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "card_user_reg",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "card": "TEST-CARD-001",
        "username": "demo_user",
        "password": "123456"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "text": "账号注册并绑定成功",
        "username": "demo_user",
        "card": "TEST-CARD-001"
    },
    "time": 1714656000,
    "check": "fc0ea930eeec6c61a2a56e1f4a45a0c5"
}

失败响应

{
    "code": 400,
    "msg": "卡密、账号或密码不能为空",
    "time": 1714656000,
    "check": "21a38729c279aefd064421e6c1e73757"
}

change_pwdPOST修改账号密码

账号模式下修改密码，校验旧密码和新密码长度。

请求参数

username：用户名

old_password：原密码

new_password：新密码，长度 6-72 位

返回字段

msg.text：密码修改成功

msg.username：用户名

time：服务器 Unix 时间戳

check：返回校验值

失败 msg

参数不完整新密码长度需要在 6-72 位之间原密码错误

请求示例

{
    "api_code": "该接口尚未配置专属码",
    "action": "change_pwd",
    "time2": 1714656000000,
    "sign": "按签名规则计算",
    "data": {
        "username": "demo_user",
        "old_password": "123456",
        "new_password": "654321"
    }
}

成功响应

{
    "code": 200,
    "msg": {
        "text": "密码修改成功",
        "username": "demo_user"
    },
    "time": 1714656000,
    "check": "5a5738fc873e7d55eebef0aa15a342eb"
}

失败响应

{
    "code": 400,
    "msg": "参数不完整",
    "time": 1714656000,
    "check": "a58be009f4f8175880679d219d31f5d4"
}

代码示例

推荐在后台“应用管理 -> 生成代码”复制。生成器会写入每个接口对应的专属码和签名规则。

sdk = HuaYanSDK()
res = sdk.login("CARD_KEY", "DEVICE_ID")

if res.get("code") == 200:
    token = res["msg"].get("token")
    beat = sdk.heartbeat("CARD_KEY", "DEVICE_ID", token)

状态码

code	说明
`200`	成功。接口设置了自定义成功码时，以该接口 success_code 为准
`400`	请求参数错误、业务参数缺失或未知接口
`401`	签名错误、登录会话失效、账号密码错误或设备码不匹配
`402`	授权已过期或点数已耗尽
`403`	IP 禁止、代理禁止、卡密封禁、协议不匹配或权限校验失败
`404`	接口专属码不存在、卡密不存在、会话不存在或设备未绑定
`409`	账号或卡密绑定冲突
`426`	客户端版本过低，需要更新
`500`	数据库操作失败或服务端异常
`503`	应用维护中

花验文档

协议入口

当前应用接口专属码

Sign / Check

API 接口

代码示例

状态码

卡密类型和用法

卡密类型

推荐接入

心跳下发

后台怎么用

客户端怎么处理

说明

只写已实现接口

必须使用接口专属码