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

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