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 |