寬樂(lè)通信Web Service接口說(shuō)明書(shū)V1.1-短信.doc

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