寬樂通信Web Service接口說明書V1.1-短信.doc

寬樂通信Web Service接口說明書V1.1（短信部分）中國電信股份有限公司廣州研究院寬樂通信 Web Service接口說明書（短信部分）摘要：本文檔主要描述寬樂通信對第三方服務(wù)器開放收發(fā)短信業(yè)務(wù)能力的Web Service接口，對接口格式和相應(yīng)的參數(shù)給出了詳細的描述。1 總述寬樂系統(tǒng)（UC）通過Web Service接口對外提供CTD(點擊撥號)、CTC（點擊會議）、SMS(收發(fā)短信)等業(yè)務(wù)能力。1.1 寬樂帳號說明寬樂系統(tǒng)分配給第三方服務(wù)器2種用戶號碼 ，Web注冊訪問用戶（可以用于注冊回調(diào)地址，可以發(fā)送短信等操作），Web訪問用戶（不可以注冊回調(diào)地址，對應(yīng)的注冊訪問用戶注冊后，可以發(fā)送短信等操作）。補充說明：Web訪問用戶在哪個應(yīng)用發(fā)送短信，就要在該應(yīng)用下接受短信。第三方服務(wù)器與寬樂Web Service服務(wù)器互相開放Web Service接口，互為服務(wù)器和客戶端，接口符合本文定義。注意無論第三方服務(wù)器在公網(wǎng)或者私網(wǎng)內(nèi)，都需要向?qū)挊稺eb Service服務(wù)器提供Web Service服務(wù)接口并能夠訪問寬樂的Web Service服務(wù)。1.2 接口總體說明寬樂提供的短信相關(guān)的Web Service接口：1） 注冊接口：RegisterURL: 46:8080/jboss-net/services/Register2） 發(fā)送短信：SendSMSURL:46:8080/jboss-net/services/SendSMS以上接口都需要客戶端API鑒權(quán)，訪問WebService時請?zhí)砑佑脩裘艽a(test/test)。第三方必須提供WebService回調(diào)接口：接口名：由第三方給出方法：NotifyStatus、RecvSMS、EchoOfSendSMSURL：由第三方給出下表列出寬樂系統(tǒng)定義的Web Service（短信相關(guān)）請求和事件報告所使用的接口方法：接口請求和事件方法（函數(shù)）方向注冊接口獲取隨機數(shù)請求getRandom3rd Server UC Portal注冊接口注冊回調(diào)地址請求setCallBackAddr3rd Server UC Portal回調(diào)地址更改報告NotifyStatusUC Portal 3rd Server收發(fā)短信發(fā)送短信請求sendSMS3rd Server UC Portal發(fā)送短信結(jié)果報告NotifyStatusUC Portal 3rd Server發(fā)送短信回執(zhí)EchoOfSendSMSUC Portal 3rd Server接收短信請求RecvSMSUC Portal 3rd Server1.3 收發(fā)短信流程1.3.1 注冊注意：第三方應(yīng)用啟動后，只需要調(diào)用一次該接口獲得連接id即可，后續(xù)所有要用到connID的地方都可以用該值，不需要每次發(fā)送短信都注冊。(1) 第三方服務(wù)器調(diào)用Web Service服務(wù)器的getRandom獲取校驗用的隨機數(shù)。(2) 第三方服務(wù)器用隨機數(shù)與登錄密碼加密后，向Web Service服務(wù)器發(fā)起注冊回調(diào)地址請求setCallBackAddr，該請求攜帶回調(diào)地址參數(shù)指明第三方服務(wù)器對UC開放的WebService接口的IP地址、URL和端口。UC對帳號密碼鑒權(quán)通過后注冊該帳號及對應(yīng)的回調(diào)服務(wù)信息，生成一個連接id返回給第三方服務(wù)器，該連接id在第三方服務(wù)器后續(xù)的請求中攜帶。一個帳號只能創(chuàng)建一個連接，最新的注冊將使以前注冊的回調(diào)地址信息失效。1.3.2 發(fā)送短信(1) 第三方服務(wù)器重新調(diào)用Web Service服務(wù)器的getRandom獲取校驗用的隨機數(shù)，并用該隨機數(shù)加密sendSMS接口調(diào)用的UC密碼。(2) 第三方服務(wù)器調(diào)用Web Service服務(wù)器的發(fā)送短信請求sendSMS接口。(3) Web Service服務(wù)器把短信請求提交給AS。(4) 如果鑒權(quán)成功，AS把短信提交到短信中心。(5) AS通知Web Service服務(wù)器發(fā)送成功。(6) Web Service服務(wù)器通過調(diào)用回調(diào)事件接口NotifyStatus向第三方服務(wù)器上報發(fā)送短信狀態(tài)。(7) 被叫接收到短信，Web Service服務(wù)器通知AS短信回執(zhí)。(8) AS計費，落話單。(9) AS通知Web Service服務(wù)器第三方收到回執(zhí)(10) Web Service服務(wù)器通過調(diào)用發(fā)送短信回執(zhí)EchoOfSendSMS接口向第三方服務(wù)器通知被叫接收短信狀態(tài)。短信發(fā)送流程如下：1.3.3 接收短信注意：寬樂帳號要能接收到短信，需要Web注冊訪問賬號已經(jīng)注冊過（提交了回調(diào)地址）。(1) 寬樂接收短信時，Web Service服務(wù)器通過調(diào)用接收短信接口RecvSMS向第三方服務(wù)器通知接收短信。2 接口定義以下可選項，可以填空字符串”。2.1 注冊接口2.1.1 獲取隨機數(shù) 接口說明：第三方服務(wù)器通過該接口獲取對后續(xù)請求加密的隨機數(shù)。每次調(diào)用其他函數(shù)，都需要先調(diào)用該函數(shù)獲取新的隨機數(shù)。 接口格式：String getRandom(); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明 返回參數(shù)說明：參數(shù)類型必選/可選說明randString必選成功返回大于0的隨機數(shù)失敗返回-12.1.2 注冊/更改回調(diào)地址 接口說明：該接口用于第三方服務(wù)器注冊它的回調(diào)WebService接口的地址，獲取連接id。 接口格式：String setCallBackAddr(String uc, String pw, String rand, String url); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明ucString必選UC系統(tǒng)分配給第三方服務(wù)器注冊WebService的用戶號碼pwString必選“getRandom獲取的rand參數(shù)+UC密碼+UC密碼” 經(jīng)過MD5加密后的字符串（以下加密方式相同）randString必選隨機數(shù)urlString必選回調(diào)服務(wù)器的url完整的WebService訪問地址，如：7:8080/jboss-net/services/CallBack 返回參數(shù)說明：參數(shù)類型必選/可選說明connIDString必選連接id，代表一個第三方服務(wù)器與UC Portal的連接。第三方服務(wù)器調(diào)用UC WebService接口時攜帶連接id，UC Portal根據(jù)連接id確定回調(diào)地址。返回值說明：0：為連接通道ID 0：為失敗碼，同通用失敗碼2.2 收發(fā)短信相關(guān)接口2.2.1 發(fā)送短信請求 接口說明：第三方服務(wù)器可以通過該接口使用UC號碼發(fā)送短信。 該接口同步返回請求結(jié)果，如果UC系統(tǒng)接受此請求則返回發(fā)送短信成功碼，如果失敗則返回錯誤碼（具體成功和錯誤碼請參見如下返回值說明）。發(fā)送短信的狀態(tài)將通過NotifyStatus調(diào)用異步返回給第三方服務(wù)器。 接口格式： String sendSMS(String uc, String pw, String rand, String callee, String isreturn, String cont, int msgid, String connID); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明ucString必選UC系統(tǒng)分配給第三方服務(wù)器發(fā)起WebService呼叫的用戶號碼。本次呼叫的使用的UC號碼，費用記在該UC號碼上。pwString必選“getRandom獲取的rand參數(shù)+UC密碼+UC密碼” 經(jīng)過MD5加密后的字符串randString必選隨機數(shù)calleeString必選被叫號碼（帶區(qū)號）可以帶多個被叫號碼，最多10個。isreturnString必選該短信是否需要回執(zhí)（0：不需要回執(zhí)；1：需要回執(zhí)。）contString可選短信內(nèi)容（第三方服務(wù)器需要對短信內(nèi)容進行BASE64編碼）msgidint必選由終端生成的短信的標識，終端級唯一，用于接收發(fā)送狀態(tài)、回執(zhí)時匹配connIDString必選連接通道ID說明：callee = callee1,callee2 返回參數(shù)說明：參數(shù)類型必選/可選說明resString必選返回值說明：=0：成功返回0：失敗碼如下失敗碼說明：-1：系統(tǒng)異常，發(fā)送短信失??；-4：用戶類型非法（該用戶沒有權(quán)限完成該操作）-5：隨字符串超時；-7：通道ID不存在；-12：系統(tǒng)超時；-25：傳入?yún)?shù)不合法；-45：隨機數(shù)字段長度不合法，或隨機字符串無法轉(zhuǎn)成Long型-47：用戶狀態(tài)不正確（非激活狀態(tài)）-71：發(fā)送短信UC號碼不存在；-72：發(fā)送短信UC號碼余額或限額不足；-73：發(fā)送短信UC號碼狀態(tài)未激活；-74：發(fā)送短信UC號碼未開通短信功能；-75：接收短信UC號碼不存在；-76：接收短信UC號碼狀態(tài)未激活；-77：接收短信UC號碼未開通短信功能；-78：短信發(fā)送失敗-79：不能發(fā)送短信到接收號碼-84：短信群發(fā)超過群發(fā)允許的上限-85：超過短信群發(fā)的日最大條數(shù)限制-86：超過短信群發(fā)的月最大條數(shù)限制2.2.2 發(fā)送短信回執(zhí) 接口說明：如果發(fā)送的短信被終端用戶收到，會為短信發(fā)送用戶提供短信回執(zhí)。第三方服務(wù)器需要提供發(fā)送短信回執(zhí)接口接收短信回執(zhí)。 接口格式： void EchoOfSendSMS(String ucNum, String cee, int msgid, int res, String recvt); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明ucNumString必選發(fā)送方號碼，用于第三方服務(wù)器定位發(fā)送客戶端ceeString必選接收方號碼msgidint必選短消息編號，用于客戶端匹配請求消息resint必選回執(zhí)的結(jié)果recvtString必選短消時間回執(zhí)的結(jié)果說明：1： 接收方成功接收短信-1： 系統(tǒng)異常；-12：系統(tǒng)超時；-92：被叫號碼不存在、對方短信中心異常、被叫號碼狀態(tài)異常等等2.2.3 接收短信請求 接口說明：第三方服務(wù)器需要提供接收短信WebService接口接收在其上登記的UC號碼的短信。該接口同步返回結(jié)果，如果第三方服務(wù)器成功接收短信，將結(jié)果立即返回。 接口格式： String RecvSMS(String caller, String time, String cont, String ucNum); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明callerString必選短信的發(fā)送者號碼timeString必選短信發(fā)送時間，以http接口傳過來的時間為準contString必選短信內(nèi)容（第三方服務(wù)器需要對短信內(nèi)容進行BASE64解碼）ucNumString必選短信接受者號碼（接收短信的UC號碼） 返回參數(shù)說明：參數(shù)類型必選/可選說明resString必選返回值說明：=0：成功返回0：失敗碼失敗碼說明：-1：接收失敗2.3 第三方服務(wù)器需要實現(xiàn)通用回調(diào)函數(shù) 接口說明：第三方服務(wù)器需要實現(xiàn)NotifyStatus函數(shù)用于接收相關(guān)參數(shù)并對相關(guān)參數(shù)進行處理。 接口格式：void NotifyStatus(int eventID, String sessionID,int res,String para1); 輸入?yún)?shù)說明：參數(shù)類型必選/可選說明eventIDint必選接口事件ID：區(qū)別相應(yīng)接口調(diào)用返回以及對其他事件的上報。sessionIDString必選呼叫標識/會議標識/短信標識/傳真標識： resint必選失敗碼/狀態(tài)碼。para1String可選參數(shù)1其中失敗碼值小于0，全局編碼；狀態(tài)碼與回調(diào)事件相關(guān)，值大于或等于0；para1參數(shù)的具體意義與回調(diào)事件相關(guān)。參見回調(diào)事件的具體說明。2.3.1 設(shè)置回調(diào)地址回調(diào)事件一、部分返回參數(shù)說明：eventIDint必選1para1String可選二、狀態(tài)碼說明：1：回調(diào)地址發(fā)生更改三、失敗碼說明：見回調(diào)事件通用失敗碼2.3.2 發(fā)送短信回調(diào)事件一、返回參數(shù)說明：eventIDint必選13para1String可選群發(fā)(兼容單發(fā))短信的失敗號碼列表,該列表中的所有號碼對應(yīng)同一個錯誤碼,號碼之間采用|隔開本事件中sessionID參數(shù)即為請求消息中終端帶過來的msgid參數(shù)，用于終端將該應(yīng)答與短信發(fā)送請求對應(yīng)。其中如果該事件是群發(fā)短信請求的應(yīng)答事件，para1參數(shù)中返回失敗的目的號碼，用“|”分割。二、狀態(tài)碼說明：1：短信發(fā)送成功（只代表本系統(tǒng)發(fā)送短信成功，還未得到短信回執(zhí)）三、失敗碼說明：-1：系統(tǒng)異常；-4：用戶類型非法（該用戶沒有權(quán)限完成該操作）-5：隨字符串超時；-7：通道ID不存在；-12：系統(tǒng)超時；-25：傳入?yún)?shù)不合法；-45：隨機數(shù)字段長度不合法，或隨機字符串無法轉(zhuǎn)成Long型-47：用戶狀態(tài)不正確（非激活狀態(tài)）-71：發(fā)送短信UC號碼不存在；-72：發(fā)送短信UC號碼余額或限額不足；-73：發(fā)送短信UC號碼狀態(tài)未激活；-74：發(fā)送短信UC號碼未開通短信功能；-75：接收短信UC號碼不存在；-76：接收短信UC號碼狀態(tài)未激活；-77：接收短信UC號碼未開通短信功能；-78：短信發(fā)送失敗-79：不能發(fā)送短信到接收號碼-84：短信群發(fā)超過群發(fā)允許的上限-85：超過短信群發(fā)的日最大條數(shù)限制-86：超過短信群發(fā)的月最大條數(shù)限制其它錯誤碼見回調(diào)事件通用失敗碼3 加密規(guī)則pwString“getRandom獲取的rand參數(shù)+UC密碼+UC密碼” 經(jīng)過MD5加密后的字符串4 通用失敗碼-1 系統(tǒng)異常-2 加密后的密碼驗證不通過-3請求中的UC號碼不存在-4 用戶類型非法（該用戶沒有權(quán)限完成該操作）-5 隨機串超時，被disable了-6 與會者號碼號碼列表為空-7 通道ID不存在-8 WebService發(fā)起