后端接入

二次校验接口

用户提交表单(post-form)到产品应用后台,会携带一个验证码相关的参数,参数名为 NECaptchaValidate。产品应用需要将该参数传给易盾验证码后台做二次校验,以确保该次验证是有效并且是最近完成的。

接口地址: http://c.dun.163yun.com/api/v2/verify

请求方式

HTTP POST, 接口仅支持POST请求, 且仅接受 application/x-www-form-urlencoded 编码的参数

请求参数

参数类型必填最大长度备注
captchaIdstringY32验证码id
validatestringY不限制长度,建议1024提交二次校验的验证数据,即NECaptchaValidate值
userstringY32用户信息,值可为空
secretIdstringY32密钥对id
versionstringY4版本信息,固定值v2
timestampstringY13当前时间戳的毫秒值,例1480395193000
noncestringY32随机字符串
signaturestringY32签名信息,见签名计算

签名计算

签名生成方法如下:

  • 对所有请求参数(包括公有参数和私有参数,但不包括 signature 参数),按照参数名ASCII码表升序顺序排序。如:foo=1, bar=2, foo_bar=3, baz=4 排序后的顺序是 bar=2, baz=4, foo=1, foobar=3 。
  • 将排序好的参数名和参数值构造成字符串,格式为:key1+value1+key2+value2… 。根据上面的示例得到的构造结果为:bar2baz4foo1foobar3 。
  • 选择与 secretId 配对的 secretKey ,加到上一步构造好的参数字符串之后,如 secretKey=6308afb129ea00301bd7c79621d07591 ,则最后的参数字符串为 bar2baz4foo1foobar36308afb129ea00301bd7c79621d07591 。
  • 把c步骤拼装好的字符串采用 utf-8 编码,使用 MD5 算法对字符串进行摘要,计算得到 signature 参数值,将其加入到接口请求参数中即可。MD5 是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32位十六进制字符。

签名生成示例代码:

/**
 * 生成签名信息
 * @param secretKey 产品私钥
 * @param params 接口请求参数名和参数值map,不包括signature参数名
 * @return
 */
public static String genSignature(String secretKey, Map<String, String> params){
    // 1. 参数名按照ASCII码表升序排序
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);

    // 2. 按照排序拼接参数名与参数值
    StringBuilder sb = new StringBuilder();
    for (String key : keys) {
        sb.append(key).append(params.get(key));
    }
    // 3. 将secretKey拼接到最后
    sb.append(secretKey);

    // 4. MD5是128位长度的摘要算法,转换为十六进制之后长度为32字符
    return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
}
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""生成签名信息
Args:
    secretKey 产品私钥
    params 接口请求参数,不包括signature参数
"""
def gen_signature(secretKey, params=None):
        params_str = ""
        for k in sorted(params.keys()):
            params_str += str(k)+ str(params[k])
        params_str += secretKey
        return hashlib.md5(params_str).hexdigest()
/**
 * 生成签名信息
 * $secretKey 产品私钥
 * $params 接口请求参数,不包括signature参数
 */
function gen_signature($secretKey,$params){
    ksort($params);
    $buff="";
    foreach($params as $key=>$value){
        $buff .=$key;
        $buff .=$value;
    }
    $buff .= $secretKey;
    return md5(mb_convert_encoding($buff, "utf8", "auto"));
}
// 根据secretKey和parameters生成签名
public static String genSignature(String secretKey, Dictionary<String, String> parameters)
{
    parameters = parameters.OrderBy(o => o.Key).ToDictionary(o => o.Key, p => p.Value);
    StringBuilder builder = new StringBuilder();
    foreach (KeyValuePair<String, String> kv in parameters)
    {
        builder.Append(kv.Key).Append(kv.Value);
    }
    builder.Append(secretKey);
    String tmp = builder.ToString();
    MD5 md5 = new MD5CryptoServiceProvider();
    byte[] result = md5.ComputeHash(Encoding.UTF8.GetBytes(tmp));
    builder.Clear();
    foreach (byte b in result)
    {
        builder.Append(b.ToString("x2").ToLower());
    }
    return builder.ToString();
}
var genSignature=function(secretKey,paramsJson){
    var sorter=function(paramsJson){
        var sortedJson={};
        var sortedKeys=Object.keys(paramsJson).sort();
        for(var i=0;i<sortedKeys.length;i++){
            sortedJson[sortedKeys[i]] = paramsJson[sortedKeys[i]]
        }
        return sortedJson;
    }
    var sortedParam=sorter(paramsJson);
    var needSignatureStr="";
    for(var key in sortedParam){
        var value=sortedParam[key];
        needSignatureStr=needSignatureStr+key+value;
    }
    needSignatureStr+=secretKey;
    var md5er = crypto.createHash('md5');//MD5加密工具
    md5er.update(needSignatureStr,"UTF-8");
    return md5er.digest('hex');
};
//根据secretKey和parameters生成签名

func genSignature(secretKey string, params map[string]string) string {
	var keys []string
	for key, _ := range params {
		keys = append(keys, key)
	}
	sort.Strings(keys)
	buf := bytes.NewBufferString("")
	for _, key := range keys {
		buf.WriteString(key + params[key])
	}
	buf.WriteString(secretKey)
	has := md5.Sum(buf.Bytes())
	return fmt.Sprintf("%x", has)
}

响应参数

参数类型必填备注
resultbooleanY二次校验结果 true:校验通过 false:校验失败
errorintY异常代号
msgstringY错误描述信息
extraDatastringN返回业务方在初始化时传入的extraData内容,详见web接入参数配置

异常代号说明

error说明
0无异常
415签名校验错误
419参数校验错误,例如参数类型错误、参数值错误、必填项为空等
Online Chat Tel:95163223