HTTP(S)短信接口開發文檔

第一章接入說明

1.1 API基路徑

接口統一訪問地址：{API基路徑}/service/httpService/httpInterface.do

API基路徑說明：

請求	API基路徑	說明
HTTP	http://:	接入時客服提供接口參數
HTTP+SSL	https://:	接入時客服提供接口參數

1.2 接口參數說明

聯系客服獲取短信帳號接入參數。

參數	名稱	說明
method	接口方法	一個接口對應一個固定方法名，詳情說明見各接口說明。 getAmount：獲取賬戶余額接口 sendMsg、sendUtf8Msg、sendGbkMsg：短信發送接口 queryReport：獲取短信狀態報告 queryMo：獲取上行短信
username	用戶賬號
password	用戶密碼
veryCode	通信key（通信認證密碼）

1.3 接口對接規范

請勿在瀏覽器直接測試，因為受瀏覽器編碼影響，建議采用代碼或postman工具調試。
采用HTTP POST方式，請求參數寫入HTTP請求體，不建議拼接在url后面。
Content-type:application/x-www-form-urlencoded
參考開發示例代碼進行修改調試。

第二章、賬號余額接口

獲取短信賬號的余額（短信條數=余額*10）。

2.1 請求地址

{API基路徑}/service/httpService/httpInterface.do

2.2 參數說明

參數	名稱	說明
method	接口方法	一個接口對應一個固定方法名，詳情說明見各接口說明。 getAmount：獲取賬戶余額接口 sendMsg、sendUtf8Msg、sendGbkMsg：短信發送接口 queryReport：獲取短信狀態報告 queryMo：獲取上行短信
username	用戶賬號
password	用戶密碼
veryCode	通信key（通信認證密碼）

返回值說明：

參數名稱	含義	說明
method	查詢余額	查詢余額，固定為getAmount
username	用戶賬號	用戶賬號
password	用戶密碼	用戶密碼
veryCode	通信認證密碼
rt	響應數據格式	xml、json 默認:xml

示例（實際對接請參考《1.3 接口對接規范》）：: http(s)://*:*/service/httpService/httpInterface.do?method=getAmount&username=JSM001&password=123&veryCode=456

2.3返回值

XML響應數據格式：

<?xml version="1.0" encoding="UTF-8" ?>

    
    0		--返回狀態值：成功返回0 失敗返回：失敗代碼
    5000	--當status為0時，會出現該屬性

JSON數據格式：

   {"status":"0","account":"735"}

JSON返回值說明：

名稱	說明
status	返回狀態值，具體參照狀態碼說明，0-成功，其他代碼-失敗
account	賬號余額，條數= acount * 10 請求成功才會有此節點

狀態碼說明：

返回碼	描述
0	查詢成功
100	查詢余額失敗
101	用戶賬號不存在或密碼錯誤
102	賬號已禁用
103	參數不正確
105	認證碼錯誤
117	未開通此接入方式

第三章短信發送接口

支持普通短信/模板短信/定時短信發送，賬號接口發送最大速率20條/s，根據客戶實際業務發送量可以申請提速。普通短信需人工審核。定時短信需人工審核，審核通過且到達定時發送間才發送，在未到達定時發送時間允許聯系客服撤銷。模板短信免審，短信模板需要事先登陸客戶端申請報備并審核通過，短信3-5秒收到，所有行業短信（業務通知\驗證碼）優先采用模板短信發送，以免影響短信時效性。

3.1 請求地址

{API基路徑}/service/httpService/httpInterface.do

method參數說明：{API基路徑}/service/httpService/httpInterface.do?method=sendMsg&code=utf-8

指定字符編碼提交地址，無需攜帶code參數

Utf8編碼：: {API基路徑}/service/httpService/httpInterface.do?method=sendUtf8Msg
GBK編碼: {API基路徑}/service/httpService/httpInterface.do?method=sendGbkMsg

2.2 參數說明

參數名稱	含義	說明
method	發送短信(必填)	取值范圍:sendMsg，sendUtf8Msg，sendGbkMsg
username	用戶賬號(必填)	用戶賬號
password	用戶密碼(必填)	用戶密碼
veryCode	通信認證密碼(必填)
mobile	手機號碼(必填)	手機號碼（群發短信時，最多100個，英文逗號,隔開）,發送前過濾錯號并去除重復號碼
content	短信內容(必填)	短信內容（最多300個漢字），含特殊字符請URL編碼，編碼后不影響計費；如果使用模板短信發送，此參數用來傳遞模板短信的變量和值，參數之間以逗號隔開
sendtime	定時時間（24小時制）	定時短信的定時時間，格式為: (yyyyMMddHHmmss),例如:20140504111010 代表2014年5月4日 11時10分10秒，短信會在指定的時間發送出去 sendTime值為空時，為即時發送短信 sendTime值不為空時，為定時發送短信，值為空時表示即時發送短信
msgtype	短信類型(必填)	短信類型。1-普通短信，2-模板短信。
tempid	模板短信編號	模板編號，（msgtype=2時參數必填）
code	編碼格式	編碼方式（utf-8,gbk）,默認:gbk；指定字符編碼提交地址時無需賦值
rt	響應數據格式	xml、json 默認:xml

說明：: 1） IP：如果用戶開賬戶時指定IP，則接口只接收來自該IP的請求。; 2）模板變量值不允許包含英文逗號（，）和等號（=）; 3）短信內容或變量值包含url特殊字符請進行轉義，部分http框架會自動對參數值進行轉義; 4）發送短信建議采用post方式，請求參數放入http請求體中，不建議拼接在URL后面

例如：以下請求示例僅供參考，實際對接請參考《1.3 接口對接規范》

1 發送普通短信示例（需要人工審核）：

http://*:*/service/httpService/httpInterface.do?method=sendMsg&username=JSM001&password=123&veryCode=456&mobile=15951977097&content=您好！您本次驗證碼為：174687，請勿告知他人&msgtype=1&code=gbk

2 發送定時短信示例：

3 發送模板短信示例：

登錄綜合信息管理系統客戶端后,菜單：短信中/短信模版，詳細操作流程請查看《綜合信息管理系統_使用手冊(客戶端).docx》，如客戶定義的編號為JSM4001-0001模板短信為：

尊敬的@1@您好,您在江蘇美圣網站（wap.zugouzhijia.com），注冊的手機驗證碼為@2@，請在驗證頁面及時輸入。

http://*:*/service/httpService/httpInterface.do?method=sendMsg&username=JSM001&password=123&veryCode=456&mobile=15951977097&tempid=JSM4001-000&content=@1@=李先生,@2@=928371&msgtype=2&code=gbk

發送短信內容：【江蘇美圣】尊敬的李先生你好,您在江蘇美圣網站（wap.zugouzhijia.com），注冊的手機驗證碼為928371，請在驗證頁面及時輸入。

Content變量為模版中各變量對應的變量值，多個變量以英文逗號隔開：content=@1@=李先生,@3@=928371。

測試注意事項：: 1、正式賬號發送模板短信都為免審，直接轉發至運營商下發。; 2、測試賬號發送模板短信，若模板變量值不包含中文則免審；若模板變量值中包含中文則上審核平臺；; 3、發送常用語短信模板（無變量的模板），content傳遞空值，即“content=”后面不賦值，直接連接下一個參數。如：&content=&msgtype=2&tempid=模板編號

3.3返回值

XML響應數據格式：

<?xml version="1.0" encoding="UTF-8" ?>
<sms>
    <mt>
        <status>0</status>
        <msgid>816f333305664fb9bdd8c1bc96ae12b8</msgid>
    </mt>
</sms>

JSON數據格式：

{
	"status": "0",
	"msgid": "d7cd217727894a2ab6a818d75180959a,91a63c911d114f19bc25d8649d869fdb"
}

返回值說明：

名稱	說明
status	返回狀態碼，請參照狀態碼說明
msgid	群發短信時返回多個msgid，英文逗號隔開，且以發送號碼順序對應。

群發時返回示例：

<?xml version="1.0" encoding="UTF-8" ?>

    
    0
        
    816f33336ae12b1,830c96ae12b2, 816f3338c6ae12b3

狀態碼說明：

返回碼	描述
0	提交成功
100	獲取上行短信失敗
101	用戶賬號不存在或密碼錯誤
102	賬號已禁用
103	參數不正確若是發送模板短信，可能模板變量值中包含英文逗號(,)如：@1@=訂單號DD01,DD02
104	暫無上行短信
105	短信內容超過300字或為空、或內容編碼格式不正確
106	手機號碼超過100個或有錯誤號碼
108	余額不足
109	ip錯誤
110	短信內容存在系統保留關鍵詞，可以登錄客戶端，查找具體的敏感詞。
114	模板短信序號不存在
115	短信簽名標簽序號不存在
116	認證碼不正確
117	未開通此接入方式

四、狀態報告接口

獲取短信狀態報告接口，只能獲取當天短信的狀態報告，每次調用只查詢未被獲取的狀態報告。訪問頻率：建議控制在1-3分鐘調用一次

4.1 請求地址

{API基路徑}/service/httpService/httpInterface.do

4.2參數說明

參數名稱	含義	說明
method	獲取狀態報告(必填)	固定為queryReport
username	用戶賬號(必填)	用戶賬號
password	用戶密碼(必填)	用戶密碼
veryCode	通信認證密碼(必填)
rt	響應數據格式	xml、json 默認:xml

示例（實際對接請參考《1.3 接口對接規范》）：

http://*:*/service/httpService/httpInterface.do?method=queryReport&username=JSM40001&password=123456&veryCode=123456

4.3返回值

XML響應數據格式：

        <?xml version="1.0" encoding="UTF-8" ?>
        <sms>
            <rpt>
                <mobile>1595****097</mobile>        <!--手機號碼-->
                <msgid>7506751276725633025</msgid>	<!--消息ID ,對應發送的消息id-->
                <status>MA:0006</status>		    <!--狀態報告，DELIVRD-成功，其他-失敗-->
                <time>2015-06-08 11:21:46</time>	<!--報告時間-->
                <extno></extno>						<!--擴展碼-->
            </rpt>
            <rpt>
                <mobile>1595****097</mobile>
                <msgid>7506751276725633026</msgid>
                <status>MA:0006</status>
                <time>2015-06-08 11:21:46</time>
                <extno></extno>
            </rpt>
            <rpt>
                <mobile>1595****097</mobile>
                <msgid>7507418680283693057</msgid>
                <status>DELIVRD</status>
                <time>2015-06-08 11:59:37</time>
                <extno></extno>
            </rpt>
        </sms>

JSON數據格式：

        var a= {
            "status": "0",
            "rpts": [
                {
                    "mobile": "18120130706",
                    "msgid": "d239bbe3bba24163b27066caef635829",
                    "status": "DELIVRD",
                    "time": "2021-04-12 13:44:20",
                    "extno": ""
                },
                {
                    "mobile": "18120130706",
                    "msgid": "d7cd217727894a2ab6a818d75180959a",
                    "status": "DELIVRD",
                    "time": "2021-04-12 15:15:57",
                    "extno": ""
                }
            ]
        }

返回值說明：

名稱	說明
mobile	手機號碼
msgid	消息id，和發送接口內msgid匹配的
status	狀態碼，DELIVRD-成功，其他-失敗，見《附表一：常用狀態報告碼》
time	狀態報告時間
extno	擴展碼

4.4 錯誤返回值

XML響應數據格式：

    <?xml version="1.0" encoding="utf-8" ?>
        <sms>
        <mt>
            <status>104</status>
        </mt>
    </sms>

JSON數據格式：

{
	"status": "104",
}

返回值說明：

返回碼	描述
status	返回狀態碼，具體參照狀態碼說明

狀態碼說明：

返回碼	描述
100	獲取狀態報告失敗
101	用戶賬號不存在或密碼錯誤
102	賬號已禁用
103	參數不正確
104	暫無短信狀態報告，表示當前無未被獲取的狀態報告
105	認證碼錯誤
117	未開通此接入方式
118	未開通此接口，聯系客服申請開通“獲取狀態報告接口”權限

五、上行回復接口

獲取短信狀態報告接口，只能獲取當天上行回復短信，每次調用只查詢未被獲取的上行回復短信告。訪問頻率：建議控制在1-3分鐘調用一次，具體根據客戶實際業務設置。

5.1 請求地址

{API基路徑}/service/httpService/httpInterface.do

5.2參數說明

參數名稱	含義	說明
method	獲取上行短信(必填)	固定為queryMo
username	用戶賬號(必填)	用戶賬號
password	用戶密碼(必填)	用戶密碼
veryCode	通信認證密碼(必填)
rt	響應數據格式	xml、json 默認:xml

示例（實際對接請參考《1.3 接口對接規范》）：

http://*:*/service/httpService/httpInterface.do?method=queryMo&username=test&password=123&veryCode=456

5.3返回值

XML響應數據格式：

<?xml version="1.0" encoding="utf-8" ?>
<sms>
    <mo>
    <mobile>15951****97</mobile>				<!--手機號碼-->
        <recvcode>106905994140001</recvcode>		<!--接受號碼-->
        <content>江蘇美圣信息技術有限公司</content><!--回復內容-->
        <time>2015-04-02 22:12:11</time>			 <!--接收時間-->
    </mo>
    <mo>
        <mobile>15951****97</mobile>				<!--對應的手機號碼-->
        <recvcode>106905994140001</recvcode>		<!--接受號碼-->
        <content>4006000699</content>				<!--回復內容-->
        <time>2014-04-03 08:12:11</time>			<!--接收時間-->
    </mo>
</sms>

JSON數據格式：

{
	"status": "0",
	"mos": [
		{
			"mobile": "1812***706",
			"recvcode": "106905994540001",
			"content": "收到",
			"time": "2021-04-12 15:49:19"
		}
	]
}

返回值說明：

名稱	說明
mobile	對應的手機號碼
recvcode	接受號碼
content	回復內容
time	接收時間

4.4錯誤返回值

<?xml version="1.0" encoding="utf-8" ?>
<sms>
    <mt>
        <status></status>
    </mt>
</sms>

返回值說明：

名稱	說明
status	返回狀態碼，請參照狀態碼說明

狀態碼說明：

返回碼	描述
100	獲取上行短信失敗
101	用戶賬號不存在或密碼錯誤
102	賬號已禁用
103	參數不正確
104	暫無上行短信，表示當前無未被獲取的上行回復短信
105	認證碼錯誤
117	未開通此接入方式
118	未開通此接口，聯系客服申請開通“獲取上行接口”權限

五、常用狀態報告碼

查看常用狀態

查看HTTP(S)接入文檔

查看webservice接入文檔

CMPP接入文檔

常用狀態報告碼

HTTP(S)短信接口開發文檔

第一章接入說明

1.1 API基路徑

1.2 接口參數說明

1.3 接口對接規范

第二章、賬號余額接口

2.1 請求地址

2.2 參數說明

2.3返回值

第三章短信發送接口

3.1 請求地址

2.2 參數說明

3.3返回值

四、狀態報告接口

4.1 請求地址

4.2參數說明

示例（實際對接請參考《1.3 接口對接規范》）：

4.3返回值

4.4 錯誤返回值

五、上行回復接口

5.1 請求地址

5.2參數說明

示例（實際對接請參考《1.3 接口對接規范》）：

5.3返回值

4.4錯誤返回值

五、常用狀態報告碼

查看HTTP(S)接入文檔

查看webservice接入文檔

CMPP接入文檔

常用狀態報告碼

HTTP(S)短信接口開發文檔

第一章 接入說明

1.1 API基路徑

1.2 接口參數說明

1.3 接口對接規范

第二章、賬號余額接口

2.1 請求地址

2.2 參數說明

2.3返回值

第三章 短信發送接口

3.1 請求地址

2.2 參數說明

3.3返回值

四、狀態報告接口

4.1 請求地址

4.2參數說明

示例（實際對接請參考《1.3 接口對接規范》）：

4.3返回值

4.4 錯誤返回值

五、上行回復接口

5.1 請求地址

5.2參數說明

示例（實際對接請參考《1.3 接口對接規范》）：

5.3返回值

4.4錯誤返回值

五、常用狀態報告碼

第一章接入說明

第二章、賬號余額接口

第三章短信發送接口

四、狀態報告接口

五、上行回復接口

五、常用狀態報告碼