短信平台接口协议（V3.2）

1. 概述

1.1. 协议说明

本协议是商户和短信平台之间的接口协议，该协议采用主流的http协议，商户通过发送http请求实现短信的发送，状态报告、上行短信的获取等。

1.2. 适用范围

本协议适用于商户和短信平台的对接。

1.3. 约定

编码：若无特殊说明，则所有内容或字段一律以UTF-8编码，若某个字段有特殊说明，以特殊说明为准。
字节序：通信过程中的数据类型全部采用网络字节序。
命名风格：java命名风格，即常量采用全部大写，多个单词用下划线隔开。字段当只有一个单词后，采用全部小写形式，如果大于或等于2个单词，则第二个单词开始首字母小写形式，如userName。
大小写敏感：如无特殊说明，则所有内容均是大小写敏感的，比如username和userName表示不同的单词。

1.4. 数据类型

1.5. 参考资料

（无）

2. 通信流程

短信平台接入商户通过http协议的POST方式发送短信时，应设置http Header里的Content-Type 为application/x-www-form-urlencoded；charset=UTF-8, 所有的http响应均返回一个JSON格式的字符串。

3. HTTP的消息定义

3.1. 商户向短信平台提交短信

3.1.1. 请求地址和注意事项

请求地址: http://sms.whdrawing.com/api/v3/sendSms
appId、appSecret等参数信息请联系管理人员索取

3.1.2. 请求报文示例

用户获得的各项参数如下：
appId=BfxdjhBApaBQQsTP
appSecret=zigkDmERCfMqWvZqemAFpLAxICbDWE
phone=13080612932
templateCode=SMS_135485028
模板内容：您的验证码是${code}。如非本人操作，请忽略本短信

那么对应的请求报文如下：
POST /api/v3/sendSms HTTP/1.1
Content-Length: 222
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host:
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.4.1 (Java/1.7.0_75)
Accept-Encoding: gzip,deflate

nonce=2018071118461437&signName=test&phone=13080612932&appId=BfxdjhBApaBQQsTP&sign=A4A99F9F411E18EBBA36C7B3E1FF10A6&templateParam={“code”:”5895632”}&outId=20180702142850&templateCode=SMS_135485028&nonce=13080612932&sendTime=20180702142850&timestamp=20180702142850

3.1.3. 请求参数及解释

3.1.4. 响应参数

返回值是一个json对象，json对象的属性如下：

body中的元素属性为：

3.1.5. 响应报文举例

正确响应报文举例：
{“result”:0,”desc”:”“,”body”:{“bizId”:”BfxdjhBApaBQQsTP-180702101109-380253”,”phone”:”13080612932”,”outId”:”20180702101111”}}
失败响应报文举例：
{“result”:301,”desc”:”短信签名不能为空”,”body”:null}

3.2. 商户主动查询状态报告

3.2.1.请求地址和注意事项

请求地址: http://sms.whdrawing.com/api/v3/queryMsgReport
appId、appSecret等参数信息请联系管理人员索取

3.2.2.请求报文示例

用户获得的各项参数如下：
appId=BfxdjhBApaBQQsTP
appSecret=zigkDmERCfMqWvZqemAFpLAxICbDWE

那么请求示例报文如下：
POST /api/v3/queryMsgReport HTTP/1.1
Content-Length: 222
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: sms.whdrawing.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.4.1 (Java/1.7.0_75)
Accept-Encoding: gzip,deflate

nonce=2018071118461437&sign=F07BDECE091C662346872867FF2964C8&timestamp=20180702144201&appId=BfxdjhBApaBQQsTP

3.2.3.请求参数及解释

3.2.4.响应参数

返回值是一个json对象，json对象的属性如下：

body中元素的对象属性

3.2.5.响应报文举例

正确响应报文举例：

{
    "result": 0,
    "desc": "",
    "body": [{
        "phone": "13080612935",
        "outId": "20180627151335",
        "bizId": "BfxdjhBApaBQQsTP-180702090241-320987",
        "rptStatus": 9,
        "rptStat": "12"
    },
    {
        "phone": "13080612935",
        "outId": "20180627151335",
        "bizId": "BfxdjhBApaBQQsTP-180702090241-320988",
        "trtStatus": 9,
        "rptStat": "12"
    }]
}

失败响应报文举例：

{
    "result": 999,
    "desc": "服务器未知错误",
    "body": []
}

3.3. 商户主动查询上行短信

3.3.1.请求地址和注意事项

请求地址: http://sms.whdrawing.com/api/v3/queryMsgReceive
appId、appSecret等参数信息请联系管理人员索取

3.3.2.请求报文示例

用户获得的各项参数如下：
appId=BfxdjhBApaBQQsTP
appSecret=zigkDmERCfMqWvZqemAFpLAxICbDWE

那么请求示例报文如下：
POST /smtp/v1/queryMsgReceive HTTP/1.1
Content-Length: 222
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: sms.whdrawing.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.4.1 (Java/1.7.0_75)
Accept-Encoding: gzip,deflate

nonce=2018071118461437&sign=F07BDECE091C662346872867FF2964C8&timestamp=20180702144201&appId=BfxdjhBApaBQQsTP

3.3.3.请求参数及解释

3.3.4.响应参数

返回值是一个json对象，json对象的属性如下：

body中元素的对象属性

3.3.5.响应报文举例

正确响应报文举例：

{
    "result": 0,
    "desc": "",
    "body": [{
        "sp": 2,
        "phone": "13080612932",
        "spNumber": "999901",
        "buzId":"BfxdjhBApaBQQsTP-180702090241-321038",
        "msgContent": "短信上行测试vtb"
    },
    {
        "sp": 2,
        "phone": "13080612932",
        "spNumber": "999901",
        "buzId":"BfxdjhBApaBQQsTP-180702090241-321037",
        "msgContent": "短信上行测试bLy"
    }]
}

失败响应报文举例：

{
    "result": 999,
    "desc": "服务器未知错误",
    "body": []
}

4. 常量定义

4.1. 错误码定义

4.2. 状态报告错误码定义(rptStatus字段)

4.3. 状态报告错误字符串描述(rptStat字段)