通信协议

HTTPS 协议。

请求方法

网易易盾提供的所有接口，均支持 POST/GET 方法。当参数名与参数值拼装起来的 URL 长度小于 1024 个字符时，可以用GET发起请求；当参数类型含 byte[ ] 类型或拼装好的请求URL过长时，必须用 POST 发起请求。建议所有API调用都使用 POST 方法请求。

当前仅支持post请求的Content-Type: application/x-www-form-urlencoded格式，不支持application/json。

字符编码

所有接口的请求和响应数据编码皆为 utf-8。

API请求结构

公共参数

公共参数是用于标识产品和接口鉴权目的的参数，如非必要，在每个接口单独的接口文档中不再对这些参数进行说明，每次请求均需要携带这些参数。

请求公共参数

响应通用字段

所有接口响应值采用 json 格式， 如无特殊说明，每次请求的返回值中，都包含下面字段：

响应返回码

响应返回码（code）网易易盾服务 API 调用和执行的概要结果。当返回码不为 200 时， 表示请求未正常执行，返回码描述 (msg) 对该结果进行了细化补充，用户可根据返回码判断 API 的执行情况。

所有接口调用返回值均包含 code 和 msg 字段， code 为返回码值，msg 为返回码描述信息，返回码表如下：

接口鉴权

网易易盾的所有服务使用签名方法对接口进行鉴权，所有接口每一次请求都需要包含签名信息（signature 参数），以验证用户身份，防止信息被恶意篡改。

申请安全凭证

在第一次使用 API 之前，需申请安全凭证，安全凭证包括 SecretId 和 SecretKey ，SecretId 是用于标识 API 调用者的身份，SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。SecretKey 必须严格保管，避免泄露。

签名生成算法

签名生成方法如下：

• 对所有请求参数（包括公有参数和私有参数，但不包括 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');
};

短信发送接口

接口地址

https://sms.dun.163yun.com/v2/sendsms

接口描述

该接口主要功能

• 发送短信到用户

请求参数

公共参数已省略，详细见 公共参数，其他参数如下：

响应结果

响应字段如下，响应通用字段已省略，详细见响应通用字段：

data 数据结构

响应结果码

响应返回码（result）。当返回码不为 200 时， 表示请求未正常执行。

所有接口调用返回值均包含 result 字段， 返回码表如下：

请求示例

    /** 产品密钥ID，产品标识 */
    private final static String SECRETID = "your_secret_id";
    /** 产品私有密钥，服务端生成签名信息使用，请严格保管，避免泄露 */
    private final static String SECRETKEY = "your_secret_key";
    /** 业务ID，易盾根据产品业务特点分配 */
    private final static String BUSINESSID = "your_business_id";
    /** 本机认证服务身份证实人认证在线检测接口地址 */
    private final static String API_URL = "https://sms.dun.163yun.com/v2/sendsms";
    /** 实例化HttpClient，发送http请求使用，可根据需要自行调参 */
    private static HttpClient httpClient = HttpClient4Utils.createHttpClient(100, 100, 2000, 2000, 2000);

    /**
     *
     * @param args
     * @throws Exception
     */
    public static void main(String[] args) throws Exception {
        Map<String, String> params = new HashMap<String, String>();
        // 1.设置公共参数
        params.put("secretId", SECRETID);
        params.put("businessId", BUSINESSID);
        params.put("version", "v2");
        params.put("timestamp", String.valueOf(System.currentTimeMillis()));
        //32随机字符串
        //params.put("nonce", getRandomStr(32));
        params.put("nonce", "dh2u81hdah129zjk2hlla118snebd2q1");
        // 2.设置私有参数d
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("code", "123");
        jsonObject.put("time", "20180816");
        params.put("mobile", "18883110011");
        //使用JSON格式填充模板
        params.put("paramType", "json");
        params.put("params", jsonObject.toJSONString());
        params.put("templateId", "10000");
        //需要上行的时候,这里需要设置为true
        params.put("needUp", "true");

        // 3.生成签名信息
        String signature = SignatureUtils.genSignature(SECRETKEY, params);
        params.put("signature", signature);
        // 4.发送HTTP请求，这里使用的是HttpClient工具包，产品可自行选择自己熟悉的工具包发送请求
        String response = HttpClient4Utils.sendPost(httpClient, API_URL, params);
        //5.解析报文返回
        ApiResponse apiResponse = gson.fromJson(response, ApiResponse.class);
        //6.返回结果
        String requestId = apiResponse.getData().getRequestId();
    }
       

响应示例

当请求成功时，输出示例如下：

{
	"code": 200,
	"msg": "ok",
	"data": 
  	{
  	  "result" : 200,
  	  "requestId" : "7bgsdg2sdhfwi34hkhui"
	}
}