Server Side Integration

2021.11.18 15:41:11

    1. Secondary verification interface

    The user submits the form (post-form) to the product application back-end, which carries a parameter in relation to the verification, named "NECaptchaValidate". The product application is required to send the parameter to the back-end of YiDun CAPTCHA for secondary verification, so as to ensure that the verification is valid and completed recently.

    Interface address: https://c.dun.163.com/api/v2/verify

    2.Letter of agreement

    HTTP/HTTPS

    3. Request method

    HTTP POST, the interface only supports POST requests, and only accepts application/x-www-form-urlencoded encoded parameters

    4. Request parameter

    Parameter Type Not null Max length Remark
    captchaId string Y 32 CAPTCHA ID
    validate string Y No limit on length, 1024 is recommended Submit the verification data of secondary verification, i.e. NECaptchaValidate value
    user string Y 32 User information, the value can be empty
    secretId string Y 32 Secret ID
    version string Y 4 Version information, fixed value v2
    timestamp string Y 13 Millisecond value of the current timestamp, e.g. 1480395193000
    nonce string Y 32 Random positive integer, combined with the timestamp, is used to prevent replay attack
    signature string Y 32 Signature information, see signature calculation

    5. Signature calculation

    Signature generation method is as follows:

    • Sort all request parameters(including all public and private parameters, excluding signature parameters) in ascending order. For example: foo=1, bar=2, foobar=3, baz=4, after sorted: bar=2, baz=4, foo=1, foobar=3.
    • Construct a string from the sorted parameter names and values in the form of: key1+value1+key2+value2... The construction result for the above example is bar2baz4foo1foobar3.
    • Append secretKey to the constructed string in the previous step, e.g. secretKey=6308afb129ea00301bd7c79621d07591, then the final parameter string is bar2baz4foo1foobar36308afb129ea00301bd7c79621d07591.
    • Use MD5 algorithm to digest the character string to calculate out the signature parameter value, and simply add it to the interface request parameter. MD5 is a digest algorithm of 128-digit, expressed by the hex system, and a character of the hex system indicates 4 digits, and so the character string length after signature is fixed to 32 digits under the hex system.

    Signature generation code example:

    /**
    * Signature information generation 
    * @param secretKey product private key 
    * @param params interface request parameter name and parameter value map, excluding the signature parameter name 
     * @return 
     */
    public static String genSignature(String secretKey, Map<String, String> params){
        // 1. Parameter names are sequenced in ascending order according to the ASCII code table 
        String[] keys = params.keySet().toArray(new String[0]);
        Arrays.sort(keys);
    
        // 2. Splice the parameter name and the parameter value according to the ranking sequence 
        StringBuilder sb = new StringBuilder();
        for (String key : keys) {
            sb.append(key).append(params.get(key));
        }
        // 3. Splice the secretKey to the last 
        sb.append(secretKey);
    
        // 4. MD5 is a digest algorithm of 128-digit, which becomes 32-digit characters after conversion to the hex system. 
        return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
    }
    
    #!/usr/bin/env python
    # -*- coding: utf-8 -*-
    """Generate signature information
    Args:
        secretKey Product key
        params Interface request parameters, excluding `signature` parameters
    """
    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()
    
    /**
     * Generate signature information
     * $secretKey Product key
     * $params Interface request parameters, excluding `signature` parameters
     */
    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"));
    }
    
    // Generate signatures based on secretKey and 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 encryption tool
        md5er.update(needSignatureStr,"UTF-8");
        return md5er.digest('hex');
    };
    
    //Generate signatures based on secretKey and 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)
    }
    

    6. Response parameter

    Parameter Type Required Remark
    result boolean Y Secondary verification result true: Verification pass false: Verification failure
    error int Y Abnormal code
    msg string Y Error description information
    phone string N Only limited to the type of SMS uplink verification code, return the user's mobile phone number after successfully sending the uplink SMS
    extraData string N Return the extraData content passed in by the business party during initialization. See web access parameter configuration for details

    7. Error code explanation

    error Description
    0 No abnormality
    415 Signature verification error
    419 Parameter verification error
    在线咨询 电话咨询:95163223 免费试用