使用说明

本文档提供了短信平台业务相关的API，提供接口的相关说明，以指导相关人员进行业务接入。

号外号短信平台我们简称SMP(Short Message Platform)平台，前端客户我们简称CP（Customer Platform）。

1.接口简介

1.1.协议说明

接口采用HTTP协议，发送响应的数据格式采用JSON格式。

1.2.通信模型

1.3.安全认证

采用数字签名模式进行报文传输

生成数字签名算法如下：

1. Ts参数使用utc标准时间, ISO8601格式.
2. 请求报文各字段以参数名首字母为序（a-z）排列，参数名参数值以等号=连接，不同参数以逗号,连接。
3. 使用分配的appsecret追加到上面字段的尾部
4. sign参数本身不参与签名
5. 使用SHA256算法生成签名
6. 使用base64算法转换签名

说明：

1. 全部使用utf8编码解码
2. Nonce为随机字符串，长度无限制

实例：

                            msg = { 
                                    'ms': '8613000110022', 
                                    'appkey': 'appkey', 
                                    'nonce': '?c3^4#5UT~s_HQ>eCzpU',
                                    'vp': '900',
                                    'ts': '2016-07-15T02:09:00.164515+00:00'
                                  }
                        

参与数字签名的字符串为, (appkey=appkey,appsecret=appid)：appkey=appkey,ms=8613000110022,nonce=?c3^4#5UT~s_HQeCzpU, ts=2016-07-15T02:09:00.164515+00:00,vp=900appid

生成包含签名的最终报文如下：

                            {
                                'sign': 'XFVI/aLjuWrFNxEENdPdoFeWipwgFBnz7TAu29yNEsA=',
                                'ms': '8613000110022', 
                                'appkey': 'appkey', 
                                'nonce': '?c3^4#5UT~s_HQ>eCzpU',
                                'vp': '900', 
                                'ts': '2016-07-15T02:09:00.164515+00:00'
                            }
                        

注：appkey 和appsecret 是由号外号短信平台统一分配的。

1.4.HTTP 状态码

POST 方法

• 200 OK：成功。
• 通用状态码:
• 500 SERVER ERROR：服务器内部错误。
• 471: 无此appkey
• 472: 缺少必要的键（字段）
• 473: 数字签名校验失败
• 474: 短信剩余条数不足
• 475: 校验码超出有效期
• 476: 校验码错误
• 477: 消息格式错误
• 478: 短信发送失败
• 479: 推送信息失败

2.获取短信验证码接口

2.1.接口功能

当CP平台用户发送验证请求时，SMSP后台会向CP平台请求指定的手机号发送一个短信验证码，同时返回给CP平台一个短信验证码的id。

2.2.请求方法

请设置成”POST”

2.3.Url

http://{serverroot}/gsms

2.4.请求消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示。

表1-1请求消息体参数说明

注意：ms手机号目前只支持86中国手机号码

请求消息示例如下：

                            {
                                "appkey":"jsyh",
                                "tid":"1073001", 
                                "ms":"8613000110022",
                                "ts":"20160713101356320",
                                "vp":"900",
                                "sign":"1D731A07A180EC56C66451706FBE4AFF"
                            }
                        

2.4.1.响应消息

表1-2响应消息参数说明

响应消息示例：

                            {
                                "vid": "1", 
                                "msg": "success"，
                                "msgid":"16080512365800001521667374"
                            }
                        

3. 校验短信验证码接口

3.1.功能

当CP平台用户发送验证请求时，SMSP后台会向CP平台请求指定的手机号发送一个短信验证码，同时返回给CP平台一个短信验证码的id。CP平台使用此id校验CP平台用户的校验码是否正确。

3.2. 请求方法

请设置成“POST”。

3.3. Url

http://{serverroot}/vsms

3.4. 请求消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示。

例子：

                            {
                                "appkey": "jsyh",
                                "vid": "91", 
                                "vcode": "123456", 
                                "ms": "8613000110022", 
                                "sign": "C614B63D1B85FBC7C2A235183FD1D4C0", 
                                "ts": "20160713101356320"
                            }
                        

3.4.1.响应消息

例子：

                            {
                            "msg": "success"
                            }
                        

4.普通短信

4.1.功能

CP平台通过SMSP平台给用户发送短信。

4.2.请求方法

请设置成“POST”。

4.3.Url

http://{serverroot}/csms

4.4.请求消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示

4.5.请求消息

例子：

                            {
                                "appkey": "jsyh", 
                                ”tid”:”1073001”,
                                "ct": "91", 
                                "ms": "8613000110022", 
                                "sign": "7F33603C22C6DE56BF671C925918DCE8",
                                "ts": "20160713101356320"
                            }
                        

4.6.响应消息

例子：

                            {
                            "msg": "success", 
                            "msgid": "16080512365800001521667374"
                            }
                        

5.查询余额接口

5.1.接口功能

CP平台用户查询余额，返回给CP平台一个剩余可用的短信条数。

5.2.请求方法

请设置成”GET”

5.3.Url

http://{serverroot}/qsms

5.4.请求消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示。

注意：ms手机号目前只支持86中国手机号码

请求消息示例如下：

                            {
                                "appkey":"jsyh",
                                "ts":"20160713101356320",
                                "nonce":"900",
                                "sign":"1D731A07A180EC56C66451706FBE4AFF"
                            }
                        

5.5.响应消息

响应消息示例：

                            {
                            "balance": 198989, 
                            "msg": "success"
                            }
                        

6. 短信状态report

6.1.接口功能

状态报告推送需要第三方客户提供一个HTTP的接收地址，短信平台为发送方，客户为接收方。

6.2.请求方法

请设置成”POST”

6.3.Url

第三方url:http://ip:port/接口名

6.4.推送消息

推送消息体中的参数（约定全部为小写字母）说明如下表所示。

6.5.推送响应

推送响应参数（约定全部为小写字母）说明如下表所示。

7.短信状态查询

7.1.接口功能

通过手机号码（ms）和消息ID（msgid），可以查询短信的发送结果（status）.

7.2. 请求方法

请设置成”get”.

7.3.Url

http ://{serverroot}/qsms

7.4.请求消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示。

请求消息示例：

                            {
                                'ms': '13810326774', 
                                'appkey': 'hwh', 
                                'nonce': 'Ck?VPQUA6S2OK*1B<>@(', 
                                'ts': '2016-08-09T07:14:16.325566+00:00', 
                                'msgid': '16080914251200001557305643', 
                                'sign': 'gxpbsBh0SoYIn/8ju9lm+3srO13iBg7Sodg6bg0/CbU='
                            }
                        

7.5.响应消息

响应消息示例：

                            {
                                "status":"1" 
                            }
                        

8.短信Deliver推送

8.1.接口功能

此接口用于向代理商通道号发送一条用户的上行请求。

8.2.请求方法

请设置成“post”

8.3.Url

http ://ip:port/deliver 需要代理商提供

8.4.推送deliver短信消息

请求消息体中的参数（约定全部为小写字母）说明如下表所示。

注意：ms手机号目前只支持86中国手机号码

推送息示例如下：

                            {
                                "ms":"8613194072190",
                                "spnum":"10073",
                                "ct":"测试测试"
                            }
                        

8.5.推送deliver响应

推送响应参数（约定全部为小写字母）说明如下表所示。

响应消息实例如下：

                            {
                            "msgid":"10006112161802260016888276",
                            "status":"0"
                            }
                        

9.附录

9.1.发送短信java示例

                        private String getPostData(String mobile, String content, String tid) {
                            StringBuffer sb = new StringBuffer();
                            sb.append("appkey").append("=").append(appkey).append(",");
                            sb.append("ct").append("=").append(content).append(",");// 短信内容
                            sb.append("ms").append("=").append(mobile).append(",");// 手机号,含国家码
                            sb.append("tid").append("=").append(tid);
                    //      sb.append("ts").append("=").append(System.currentTimeMillis()).append(",");
                            sb.append(appsecret);
                            byte[] byteArray = Base64.encodeBase64(DigestUtils.sha256(sb.toString()));
                            String sign = new String(byteArray, Charsets.UTF_8);
                            JSONObject jo = new JSONObject();
                            jo.put("appkey", appkey);
                            jo.put("ct", content);
                            jo.put("tid", tid);
                            jo.put("ms", mobile);
                            jo.put("sign", sign);
                            return jo.toJSONString();
                        }