必读说明,几分钟让你掌握所有接口对接方法(常见问题这里都有说明)
开发必读接口说明
应用区分接口说明
接口请求方法与入参说明
接口统一响应结构说明(默认响应JSON格式)
{
"code":1,
"message":"获取成功",
"timestamp":1673806650,
"nonceStr":"0f172f4ac2d8eafa5a0175a541cb1f81",
"data":"{\"info\":{\"name\":\"无加密算法测试-单码\",\"avatar\":\"http:\\/\\/yanzheng.giao.cc\\/index\\/system\\/get_custom_image\\/name\\/dXBsb2Fkcy9pbWFnZXMvc3lzdGVtX2ltYWdlLzIwMjIwNzAxLzkzZjQxOTVjMmQxZGFhNjM0YjQ4ZmY1NWUzNTEzMDA1LkpQRw==\",\"type\":0,\"addtime\":1664864027,\"param_extend_config\":{}},\"user_safe_config\":{\"token_verify_open\":false,\"token_unlimited\":true,\"machine_code_binding_top_limit\":\"2\",\"online_machine_upper_limit\":\"2\",\"online_machine_upper_limit_login_scheme\":1,\"token_invalid_duration\":\"1\",\"machine_code_verify\":true,\"online_time_difference\":\"60\",\"token_update_mechanism\":0,\"self_service_unbinding\":{\"open\":false,\"verify_user_token\":false,\"interval\":0,\"frequency_limit_type\":0,\"frequency_limit_value\":0,\"deduction_time\":0,\"verify_original_machine\":false}},\"moreOtherData\":{\"api_extra_data\":\"\",\"request_safe_code\":\"\"}}",
"signature":"56e0afb0ec3055b561e53582fbebd7ca"
}
参数名 | 类型 | 说明 | 必填 |
---|---|---|---|
code | integer | 业务码(1为成功,其他为失败-支持后台自定义更改) | 是 |
message | string | 返回业务信息-支持后台自定义更改 | 是 |
data | string | 数据信息(通常为接口的业务数据,是一个转JSON字符串的object,若开启响应返回值加密则是加密后的密文) | 是 |
timestamp | integer | 当前时间戳(10位) | 是 |
nonceStr | string | 随机字串 | 是 |
signature | string | 本次响应签名 | 是 |
统一响应结构data字段内的moreOtherData对象字段说明
参数名 | 类型 | 说明 | 必填 |
---|---|---|---|
api_extra_data | string | 接口设置的自定义额外返回数据 | 是 |
request_safe_code | string | 请求防劫持安全验证码 | 是 |
全局公共请求参数说明
注意,公共参数在不同应用功能场景下有的参数是非必填的
参数名 | 类型 | 说明 |
---|---|---|
appid | string | 应用ID,如果请求的接口路由地址是默认的那么就必须传入此参数 |
timestamp | integer | 客户端当前时间戳(10位),如果设置启用了接口传输签名验证则需要传递此参数 |
signature | string | 参数签名,如果设置启用了接口传输签名验证则需要传递此参数,签名计算规则详见请求签名计算说明 |
request_safe_code | string | 本次请求防劫持安全验证码,非必填,若有防劫持验证判断的需求可传入此参数,参数值自定,服务器会原样响应返回给客户端进行验证判断 |
integer | 指定分页页数(非必填,默认值1,针对一些需要列表分页接口) | |
integer | 每页数据数量(非必填,默认值10,针对一些需要列表分页接口) | |
string | 用户机器码-此参数在需要验证用户身份情况下且开启机器设备验证时传入 | |
string | 用户的token(登录后可取得),此参数在需要验证用户身份情况下且开启token验证时传入 | |
string | 用户卡密-此参数在单码应用且需要验证用户身份情况下传入 | |
integer | 用户ID-此参数在会员应用且需要验证用户身份情况下传入 | |
string | 用户授权信息(自定义值用户唯一标识码)-此参数在授权应用且需要验证用户身份情况下传入 |
接口响应码与响应信息说明
自栓Q验证系统V6.3版本后,新增了接口响应码管理,在这里可以查看所有接口的响应码和响应信息,也可以按每个应用进行更改,默认全局的接口业务成功响应码为1,系统异常响应码为-2,业务处理失败响应码为-1或其他值
接口请求签名计算说明
开启传输验签方式功能后请求所有接口都需要额外传递参数timestamp=10位时间戳、signature=参数签名值,计算签名值的方法:所有参数按照字典排序拼接参数字符串结尾加上应用密钥再加密即可,签名示例: 假设你设置的传输验签方式是MD5,应用密钥是abc888,请求某个接口传递的参数是a=1&e=2&c=3×tamp=1666688004&k=4,那么字典排序就是a=1&c=3&e=2&k=4×tamp=1666688004,字典排序后将应用密钥拼在结尾,最终待加密的签名字串是a=1&c=3&e=2&k=4×tamp=1666688004abc888,最后再取md5即可
C++签名示例
//获取计算参数签名字符串方法
std::string getParamsSignString(std::map<std::string, std::string> params) {
//开始计算签名值(遍历所有参数key value进行字符串拼接,除了appid和空value外)
std::string signStr = "";
for (std::map<std::string, std::string>::iterator it = params.begin(); it != params.end(); ++it) {
if (it->first != "" && it->second != "" && it->first != "appid" && it->first != "signature") {
if (signStr != "") {
signStr.append("&");
}
signStr.append(it->first + "=" + it->second);
}
}
return signStr;
}
void main()
{
std::string ShuanQ_AppKey="这里是你的应用密钥";
std::map<std::string, std::string> params;
params["shuanq"]="shuanq.cn";
params["qq"]="775294852";
std::string signatureStr=getParamsSignString(params)+ShuanQ_AppKey;
std::cout << "签名字符串-未md5/sha1:" << signatureStr << std::endl;
}
PHP签名示例
//获取计算参数签名字符串方法
function getParamsSignString($paramArr): string
{
if(empty($paramArr)) return '';
ksort($paramArr);
$str = '';
foreach ($paramArr as $k => $v){
if(!empty($v) && $k!='signature' && $k!='appid'){
$str .= $k.'='.$v.'&';
}
}
$signStr=rtrim($str,'&');
return $signStr;
}
$params=[
"shuanq"=>"shuanq.cn",
"qq"=>"775294852"
];
$ShuanQ_AppKey="这里是你的应用密钥";
$signatureStr=getParamsSignString($params) . ShuanQ_AppKey;
echo "签名字符串-未md5/sha1:" . signatureStr;
Java签名示例
//获取计算参数签名字符串方法
public static String getParamsSignString(Map<String, String> map) {
String result = "";
try {
List<Map.Entry<String, String>> infoIds = new ArrayList<Map.Entry<String, String>>(map.entrySet());
// 对所有传入参数按照字段名的 ASCII 码从小到大排序(字典序)
Collections.sort(infoIds, new Comparator<Map.Entry<String, String>>() {
public int compare(Map.Entry<String, String> o1, Map.Entry<String, String> o2) {
return (o1.getKey()).toString().compareTo(o2.getKey());
}
});
// 构造签名键值对的格式
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> item : infoIds) {
if (item.getKey() != null || item.getKey() != "") {
String key = item.getKey();
String val = item.getValue();
if (!val.equals("") && val != null && !key.equals("signature") && !key.equals("appid")) {
sb.append(key + "=" + val + "&");
}
}
}
result = sb.toString();
result = trimFirstAndLastChar(result, '&');
} catch (Exception e) {
return null;
}
return result;
}
public static void main(String[] args)
{
HashMap<String, String> params = new HashMap<>();
params.put("shuanq","shuanq.cn");
params.put("qq","775294852");
String ShuanQ_AppKey="这里是你的应用密钥";
String signatureStr=getParamsSignString(params)+ShuanQ_AppKey;
System.out.println("签名字符串-未md5/sha1:" + signatureStr);
}
...更多语言案例可在群文件或网盘下载对应对接案例查看
接口响应签名计算说明
接口响应签名验证可提升数据安全性,每次请求接口服务器都会进行响应签名,客户端可接收签名参数进行验签,也可以不进行验签,这个取决于自己并非强制,验签字串计算规则目前有多种方式,每一种方式组成的签名字串都是不一样的,并且验签字串加密方法也是自选的,具体看后台是如何设置的