[Work] Delivery Service API Documentation

[4th edition, Wenyi Feng, December 14, 2017]

[TOCM]

1. Documentation

Transfer Protocol	adopt HTTPtransmission
How to submit	Submit by POSTmethod
Data Format	Both submit and return data are in the JSONformat
Character Encoding	Unified UTF-8character encoding

API

interface name

投递服务

interface address (example)

http://127.0.0.1:9090/lvma/msg/send

request parameters

name	variable name	Types of	Required	describe
ID number	oauthCode	String(16)	Yes	Authentication code
identity key	oauthKey	String(32)	Yes	Authentication Key
Phone number	phone	String(11)	Yes	The mobile phone number of the delivery (currently supports mobile)
Template ID	templateId	int	Yes	Template ID (can be viewed in the management system)
parameter array	params	String[]	Yes	Template parameters, replace the variables (##*#) in the template with parameters and put them into the array in turn
notification address	notifyUrl	String(256)	Yes	Asynchronously receives the delivery result callback address, the notification url must be a url accessible from the external network

An example is as follows:

{
    "oauthKey":"Your oauthKey",
    "phone":"13500000000",
    "params":[
        "小明",
        "123456"
    ],
    "oauthCode":"Your oauthCode",
    "notifyUrl":"http://localhost:1234/rs_response",
    "templateId":100
}

Worth to talk about:

a. When the parameter length is 0, it can be an empty array []
b. The notification address can be an empty string "", not null

return parameter

name	variable name	Types of	illustrate
return code	code	int	Send result code (see 返回码section )
returned messages	msg	String	Send result description
delivery data	data	String	0Returns when code is

The following results are returned when code is 0:

name	variable name	Types of	illustrate
message ID	ssId	int	Posted message ID
Phone number	phone	String	Delivery phone number
content	content	String	Posted content

An example is as follows:

Successful delivery

{
    "code":0,
    "msg":"Success",
    "data":{
        "phone":"135****5918",
        "ssId":109997,
        "content":"【**科技】验证码为：123456（3分钟内有效）。"
    }
}

delivery failed

{
    "code":1005,
    "msg":"(Error)服务器繁忙"
}

3. Notification of delivery result

request parameters

name	variable name	Types of	Required	illustrate
result code	code	String	Yes	delivery resultSuccess/Fail
information	msg	String	Yes	Delivery result description (delivery success/delivery failure)
Phone number	phone	String	Yes	delivery number
content	content	String	Yes	Delivery content
message ID	ssId	int	Yes	message ID

return parameter

name	name	Types of	Required	illustrate
result code	code	String	Yes	delivery resultSuccess/Fail
information	msg	String	Yes	Delivery result description ( Ok/[failure reason])
message ID	ssId	int	Yes	message ID

4. Return code

return code	illustrate
0	Success
1101	(Error) The server is busy
1102	(Error) The sending function is not enabled yet
1201	(Error)数据不合法
1202	(Error)JSON数据格式不正确
1203	(Error)请求数据不能为空
1204	(Error)JSON数据key不正确
1301	(Error)账户无法识别
1302	(Error)身份验证失败
1303	(Error)用户身份识别出错
1304	(Error)用户身份不正确
1401	(Error)余额不足
1501	(Error)IP没有被认证
1601	(Error)参数与模板不对应
1602	(Error)模板不存在或无法识别
1603	(Error)参数过长
1604	(Error)模板待审核
1605	(Error)模板未通过审核
1701	(Error)数据初始化失败
10003	(Error)未知错误
10004	(Error)程序出错

五、示例代码

假定模板

模板ID	内容
100	#*#，你好！你的验证码为#*#（3分钟内有效）。

JAVA 示例

1、投递接口：

    @Test
    public void test() {
        // 请求接口
        String url = "";
        // 你的CODE和KEY
        String oauthCode = "Your oauthCode";
        String oauthKey = "Your oauthKey";
        // 待发手机号
        String phone = "13500000000";
        // 模板ID
        int templateId = 100;
        // 通知地址
        String notifyUrl = "http://localhost:1234/rs_response";
        // 参数
        String [] args = {"小明", "123456"};

        Map<String, Object> map = new HashMap<>();
        map.put("oauthCode", oauthCode);
        map.put("oauthKey", oauthKey);
        map.put("phone", phone);
        map.put("templateId", templateId);
        map.put("param", args);
        map.put("notifyUrl", notifyUrl);

        String params = new Gson().toJson(map);

        try {
            String result = doPostByUrl(url, params);
            System.out.println(result);
        } catch (IOException e) {
            e.printStackTrace();

        }
    }

返回：

    {
        "code":1000,
        "message":"(Error)数据不合法",
        "explain":"请仔细检查参数"
    }

2、通知地址写法：

    @PostMapping("/rs_response")
    public String rsResponse(HttpServletRequest request) {

        Map<String, Object> map = new HashMap<>();

        try {
            String jsonStr = getPostData(request);
            System.out.println("rsData: " + jsonStr);

            JsonObject jsonObject = new JsonParser().parse(jsonStr).getAsJsonObject();

            int code = jsonObject.get("code").getAsInt();
            String msg = jsonObject.get("msg").getAsString();
            String phone = jsonObject.get("phone").getAsString();
            String content = jsonObject.get("content").getAsString();
            int ssId = jsonObject.get("ssId").getAsInt();

            String parseData = "code = " + code +
                                ", msg = " + msg +
                                ", phone = " + phone +
                                ", content = " + content +
                                ", ssId = " + ssId;
            System.out.println("parseData: [" + parseData + "]");

            map.put("code", "Success");
            map.put("msg", "Ok");
            map.put("ssId", ssId);

        } catch (IOException e) {
            e.printStackTrace();
        }

        return new Gson().toJson(map);
    }

3、温馨提示:

JSON数据我们采用Gson库处理，因此在使用上面示例代码时，我们默认你已引入Gson

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.8.1</version>
    </dependency>

4、工具类代码：

    /**
     * 请求网络数据
     */
    public static String doPostByUrl(String url, String param) throws IOException {
        URL urlObject = new URL(url);
        HttpURLConnection httpUrlConn = (HttpURLConnection)urlObject.openConnection();
        httpUrlConn.setConnectTimeout(5000);
        httpUrlConn.setReadTimeout(5000);
        httpUrlConn.setUseCaches(false);
        httpUrlConn.setDoInput(true);
        httpUrlConn.setDoOutput(true);
        httpUrlConn.setRequestMethod("POST");
        httpUrlConn.setRequestProperty("Accept", "application/json");
        httpUrlConn.setRequestProperty("Content-Type", "application/json");
        httpUrlConn.connect();

        PrintWriter pw = new PrintWriter(httpUrlConn.getOutputStream());
        pw.print(param);
        pw.flush();

        BufferedReader br = new BufferedReader(new InputStreamReader(httpUrlConn.getInputStream()));
        StringBuilder sb = new StringBuilder();

        String line;
        while((line = br.readLine()) != null) {
            sb.append(line);
        }

        httpUrlConn.disconnect();
        return sb.toString();
    }

    /**
     * 获取POST提交的数据
     */
    public static String getPostData(HttpServletRequest request) throws IOException {
        BufferedReader br = new BufferedReader(new InputStreamReader(request.getInputStream()));
        String line;
        StringBuilder sb = new StringBuilder();
        while ((line = br.readLine()) != null) {
            sb.append(line);
        }
        return sb.toString();
    }

PHP 示例

    // 测试投递接口
    $oauthCode     = 'Your oauthCode';
    $oauthKey  = 'Your oauthKey';
    $phone         = '13500000000';
    $templateId = 100;
    $notifyUrl     = 'http://localhost:1234/rs_response';
    $params    = array(
        '小明',
        '123456'
    );

    class SData {
        public $oauthCode, $oauthKey, $phone, $templateId, $params, $notifyUrl;
    }

    $obj = new SData();

    $obj -> oauthCode 	= $oauthCode;
    $obj -> oauthKey 	= $oauthKey;
    $obj -> phone 		= $phone;
    $obj -> templateId 	= $templateId;
    $obj -> params 		= $params;
    $obj -> notifyUrl 	= $notifyUrl;

    $param = json_encode($obj);

    $url = '';
    $rs = doPostByUrl($url, $param);

    echo '<pre>';
    print_r($rs);
    echo '</pre>';

    /**
     * 通过post方式提交数据（字符串）
     */
    function doPostByUrl($url, $str) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $str);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
            'Content-Type: application/json; charset=utf-8',
            'Content-Length: ' . strlen($str)));
        $response = curl_exec($ch);
        curl_close($ch);

        return $response;
    }

六、测试模板

如果你是新客户，尚未申请模板，那么你可以调用以下模板来调试接口

模板ID	内容	参数长度

七、版本说明

◆ 第 4 版【2017年12月14日】

优化多处细节
统一请求返回格式
修复投递数据出错的问题
提升投递提交速度
规范帮助文档