短信網(wǎng)關(guān)socket數(shù)據(jù)接口通訊協(xié)議(V0.1)

1、短信網(wǎng)關(guān)數(shù)據(jù)接口通訊協(xié)議(V0.1)文件狀態(tài)： 草稿 正式發(fā)布 正在修改文件標(biāo)識(shí)：當(dāng)前版本：Version 0.1作者：彭凡聯(lián)系方式完成日期：1 定義1.1 協(xié)議短信客戶端與服務(wù)器端通過接口方式傳輸數(shù)據(jù)，傳輸協(xié)議為TCP短連接，每次由客戶端發(fā)起請(qǐng)求，服務(wù)器端接收完請(qǐng)求并處理后，返回響應(yīng)數(shù)據(jù)，并主動(dòng)關(guān)閉socket連接。服務(wù)器端接口程序采用java開發(fā)，客戶端由客戶自行選擇熟悉的方式。1.2 大小寫說(shuō)明如無(wú)特殊說(shuō)明，則表示是大小寫敏感的。A和a代表不同的含義。1.3 編碼編碼統(tǒng)一采用UTF-8。2 數(shù)據(jù)類型2.1 基本數(shù)據(jù)類型Integer整數(shù)，占4個(gè)字節(jié)String字符串，當(dāng)未注明位數(shù)時(shí)，表示

2、是可變長(zhǎng)度；在明確注明長(zhǎng)度并位數(shù)不足的情況下，應(yīng)左補(bǔ)齊。比如：String(6)表示占6個(gè)字節(jié)的字符串，當(dāng)數(shù)據(jù)為1234時(shí)，應(yīng)進(jìn)行左補(bǔ)齊，補(bǔ)齊結(jié)果為：001234JsonJSON結(jié)構(gòu)體，例如name: ”zs” , password:”123”2.2 消息結(jié)構(gòu)2.2.1 請(qǐng)求消息結(jié)構(gòu)（MessageRequest）：字段字節(jié)數(shù)數(shù)據(jù)類型說(shuō)明Total_length4Unsigned Integer緊跟隨的request_body的長(zhǎng)度。request_body是json格式。長(zhǎng)度不足6為左補(bǔ)零。假設(shè)request_body長(zhǎng)度為1234，則左補(bǔ)零為001234。服務(wù)器端讀取到001234后，首先

3、會(huì)去掉00，得到1234，然后再?gòu)膕ocket中讀取1234個(gè)字節(jié)，并轉(zhuǎn)成字符串。該字符串是個(gè)json格式。Command_Id4String 每個(gè)接口唯一標(biāo)識(shí),例如：A001表示登錄接口。詳見每個(gè)接口appid15Stringappsecret15Stringrequest_bodyJson具體的請(qǐng)求參數(shù)，為json格式。該json的字節(jié)為data_length。每個(gè)接口的request_body都不一樣。具體參數(shù)會(huì)在每個(gè)接口中詳述。2.2.2 響應(yīng)消息結(jié)構(gòu)（MessageResponse）：字段字節(jié)數(shù)數(shù)據(jù)類型說(shuō)明Total_length4Unsigned Integer緊跟隨的reques

4、t_body的長(zhǎng)度。request_body是json格式。長(zhǎng)度不足6為左補(bǔ)零。假設(shè)request_body長(zhǎng)度為1234，則左補(bǔ)零為001234。服務(wù)器端讀取到001234后，首先會(huì)去掉00，得到1234，然后再?gòu)膕ocket中讀取1234個(gè)字節(jié)，并轉(zhuǎn)成字符串。該字符串是個(gè)json格式。Command_Id4String(4)每個(gè)接口唯一標(biāo)識(shí),例如：A001表示登錄接口。詳見每個(gè)接口response_bodyJson具體的響應(yīng)消息參數(shù)，為json格式。詳見下表。3 業(yè)務(wù)接口3.1 短信發(fā)送接口3.1.1 接口說(shuō)明網(wǎng)關(guān)平臺(tái)此時(shí)作為socket server。商戶系統(tǒng)向SP請(qǐng)求發(fā)送短信。用戶可以

5、一次發(fā)送多條數(shù)據(jù)。Msgtype的類型區(qū)別：1、 通知短信。網(wǎng)關(guān)發(fā)送失敗后，通知短信會(huì)重新嘗試發(fā)送。發(fā)送失敗次數(shù)超過3次后，停止發(fā)送操作。2、 驗(yàn)證碼短信。網(wǎng)關(guān)發(fā)送失敗后，不會(huì)重新進(jìn)行發(fā)送。3.1.2 request_body（command_id:A001） phonemessagesendtimemsgid msgtype字段數(shù)據(jù)類型說(shuō)明phoneStringmessageString短信內(nèi)容sendtimeString發(fā)送時(shí)間。時(shí)間的毫秒數(shù)：1399176571278;msgidString商戶系統(tǒng)可以唯一短信的字段msgtypeString類型。1、通知短信；2、驗(yàn)證碼短信。3.1.3

6、 response_body（command_id:B001）status字段數(shù)據(jù)類型說(shuō)明statusString3.2 短信回執(zhí)推送接口3.2.1 接口說(shuō)明網(wǎng)關(guān)平臺(tái)發(fā)送短信成功后，獲取運(yùn)營(yíng)返回的回執(zhí)信息，主動(dòng)將回執(zhí)信息推送到商戶系統(tǒng)。網(wǎng)關(guān)平臺(tái)此時(shí)作為socketserver。超過60秒后，server沒有收到response_body，系統(tǒng)將會(huì)重新發(fā)送回執(zhí)信息。發(fā)送三次后，系統(tǒng)認(rèn)為信息發(fā)送完成，不在進(jìn)行發(fā)送。3.2.2 request_body(command_id:A002)msgidphonestatussendtimestat字段數(shù)據(jù)類型說(shuō)明msgidStringphoneString

7、statusString是否成功。1、成功；2、失敗sendtimeLongstatString運(yùn)營(yíng)商返回的描述信息3.2.3 response_body(command_id:B002)：3.3 短信狀態(tài)報(bào)告推送接口3.3.1 接口說(shuō)明網(wǎng)關(guān)平臺(tái)發(fā)送短信成功后，獲取運(yùn)營(yíng)返回的短信狀態(tài)報(bào)告信息，主動(dòng)將信狀態(tài)報(bào)告信息推送到商戶系統(tǒng)。網(wǎng)關(guān)平臺(tái)此時(shí)作為socketserver。超過60秒后，server沒有收到response_body，系統(tǒng)將會(huì)重新發(fā)送回執(zhí)信息。發(fā)送三次后，系統(tǒng)認(rèn)為信息發(fā)送完成，不在進(jìn)行發(fā)送。3.3.2 request_body(command_id:A003)msgidphones

8、tatusstatreceivetime submittimedonetime字段數(shù)據(jù)類型說(shuō)明msgidStringphoneStringstatusString狀態(tài)報(bào)告狀態(tài)；1、成功；2、失敗statStringreceivetimeLong運(yùn)營(yíng)商接受到短信時(shí)間submittimeString網(wǎng)關(guān)提交時(shí)間 yyMMddHHmmssdonetimeString運(yùn)營(yíng)商處理完成時(shí)間 yyMMddHHmmss3.3.3 response_body(command_id:B003)：3.4 短信回執(zhí)接口3.4.1 接口說(shuō)明商戶系統(tǒng)主動(dòng)請(qǐng)求SP系統(tǒng)接口，獲取Sp在發(fā)送短信成功后，網(wǎng)關(guān)的回執(zhí)信息。網(wǎng)關(guān)平臺(tái)

9、此時(shí)作為socket client。3.4.2 request_body(command_id:A004)msgid：字段數(shù)據(jù)類型說(shuō)明msgidString多個(gè)逗號(hào)隔開3.4.3 response_body(command_id:B004)：status：data：msgidphonestatussendtimestat字段數(shù)據(jù)類型說(shuō)明msgidStringphoneStringstatusString是否成功。1、成功；2、失敗sendtimeLongstatString運(yùn)營(yíng)商返回的描述信息3.5 狀態(tài)報(bào)告回執(zhí)接口3.5.1 接口說(shuō)明商戶系統(tǒng)主動(dòng)請(qǐng)求sp系統(tǒng)接口，獲取網(wǎng)關(guān)返回的狀態(tài)報(bào)告。網(wǎng)關(guān)

10、平臺(tái)此時(shí)作為socket client。3.5.2 request_body(command_id:A005)msgid：字段數(shù)據(jù)類型說(shuō)明msgidString3.5.3 response_body(command_id:B005)status：data：msgidphonestatusstatreceivetime submittimedonetime字段數(shù)據(jù)類型說(shuō)明msgidStringphoneStringstatusString狀態(tài)報(bào)告狀態(tài)；1、成功；2、失敗statStringreceivetimeString運(yùn)營(yíng)商接受到短信時(shí)間submittimeString網(wǎng)關(guān)提交時(shí)間donet

11、imeString運(yùn)營(yíng)商處理完成時(shí)間3.6 上行短信接口3.6.1 接口說(shuō)明：網(wǎng)關(guān)平臺(tái)此時(shí)作為socket client，將系統(tǒng)接收到的上行短信定時(shí)發(fā)送給商戶系統(tǒng)，功商戶系統(tǒng)處理業(yè)務(wù)3.6.2 request_body(command_id:A006) receiveidphonemsgsendtimedestid字段數(shù)據(jù)類型說(shuō)明receiveidString網(wǎng)關(guān)唯一標(biāo)示phoneStringmsgString短信內(nèi)容sendtimeLong系統(tǒng)接受時(shí)間destidString3.6.3 response_body(command_id:B006)3.7 上行短信查詢接口3.7.1 接口說(shuō)明：

12、商戶系統(tǒng)主動(dòng)請(qǐng)求SP系統(tǒng)接口，獲取上行短信。網(wǎng)關(guān)平臺(tái)此時(shí)作為socket client。3.7.2 request_body(command_id:A007) nextId3.7.3 response_body(command_id:B007)status：nextId:data： receiveidphonemsgsendtimedestid字段數(shù)據(jù)類型說(shuō)明nextIdString下一次查詢主鍵大于該id的數(shù)據(jù)（如果沒有符合條件數(shù)據(jù)直接返回請(qǐng)求的nextId）receiveidString網(wǎng)關(guān)唯一標(biāo)示phoneStringmsgString短信內(nèi)容sendtimeLong系統(tǒng)接受時(shí)間destidString3.8 心跳3.8.1 接口說(shuō)明商戶系統(tǒng)主動(dòng)請(qǐng)求sp，返回心跳信息。3.8.2 request_body(comm