能力開放平臺接口規(guī)范31版本@流量統(tǒng)付

1、能力開放平臺接口規(guī)范V3.0編 寫趙樹偉編寫 時間2015-8-21審 批審批者姓名（及其職務(wù)）審批 時間修訂說明1. 成員添加/變更/刪除接口能力編碼業(yè)務(wù)參數(shù)：VALID_MONTH修改備注說明王洪奎2015-09-22修訂說明2. 成員添加/變更/刪除接口能力編碼業(yè)務(wù)參數(shù)新增：SMS_TEMPLATE王洪奎2015-10-10版本V3.0能力開放平臺接口規(guī)范(v3.0)2015-10-10目錄1.前言41.1.術(shù)語41.2.縮略語42.接口概況52.1.接口簡介52.2.通信機(jī)制52.3.接口安全52.3.1.數(shù)字簽名63.系統(tǒng)對接73.1.接入說明73.2.接入方式73.3.接入地址73

2、.4.調(diào)用參數(shù)73.5.參數(shù)加密83.6.獲取令牌93.6.1.授權(quán)碼模式93.6.2.簡化模式103.6.3.客戶端信任模式113.7.生成數(shù)據(jù)簽名113.8.能力參數(shù)返回124.對外開放能力API134.1.集團(tuán)類業(yè)務(wù)134.1.1.成員添加/變更/刪除134.1.2.集團(tuán)成員已訂購流量查詢154.1.3.成員處理情況查詢164.1.4集團(tuán)帳戶實時余額查詢新增接口185.回調(diào)第三方接口(規(guī)范)205.1.成員添加/變更/刪除結(jié)果通知206.附錄221. 前言本文檔主要用于定義第三方應(yīng)用與能力開放平臺之間通訊的接口規(guī)范，作為程序開發(fā)的依據(jù)。本規(guī)范主要包括以下幾方面內(nèi)容：接口通信機(jī)制、接口描述

3、和接口定義。1.1. 術(shù)語本規(guī)范涉及的術(shù)語描述如下：表1-1術(shù)語術(shù)語/定義解釋1.2. 縮略語表1-2縮略語縮略語英文全稱中文含義DEVApplication Developer應(yīng)用開發(fā)者APPApplication應(yīng)用EAEnabler能力2. 接口概況2.1. 接口簡介能力開放平臺將運營商內(nèi)部能力開放給互聯(lián)網(wǎng)的第三方系統(tǒng)，包含合約套餐辦理類、流量類、業(yè)務(wù)查詢類能力等。本協(xié)議規(guī)范描述的接口如圖1-1中所示。圖1-1 協(xié)議接口位置2.2. 通信機(jī)制 能力開放平臺開放接口采用REST風(fēng)格，使用HTTP+JSON/HTTP+XML報文方式承載交易信息。2.3. 接口安全本開放平臺的接口安全通過2級

4、的安全進(jìn)行保障，描述如下：1、對調(diào)用方的身份認(rèn)證，每個接入開放平臺的第三方系統(tǒng)都需要進(jìn)行調(diào)用服務(wù)器地址的提前注冊；2、為每個接入方分配一個非對稱密鑰，約定一種對應(yīng)簽名算法，接入方的請求中必須加上簽名參數(shù)，用于請求方身份驗證和請求的防篡改驗證；2.3.1. 數(shù)字簽名同3.7章節(jié)。3. 系統(tǒng)對接3.1. 接入說明凡是接入河南移動能力平臺的第三方系統(tǒng)，一律按照本規(guī)范接入能力開放平臺。第三方渠道在申請能力后首先需求調(diào)用沙箱接口進(jìn)行測試，測試通過后再調(diào)用業(yè)務(wù)接口進(jìn)行業(yè)務(wù)聯(lián)調(diào)和使用。3.2. 接入方式 協(xié)議：http3.3. 接入地址沙箱測試地址：08:9410/opp

5、f業(yè)務(wù)接口地址: 08:20110/oppf3.4. 調(diào)用參數(shù)調(diào)用API ，需傳入系統(tǒng)參數(shù)和業(yè)務(wù)參數(shù)。系統(tǒng)參數(shù)拼接在URL上，業(yè)務(wù)參數(shù)放在POST體中。對于接口說明中的標(biāo)記為必填項的字段，必須有相應(yīng)的非空、合法性校驗，并精確返回異常信息，如：MobileNo不合法。系統(tǒng)參數(shù)詳細(xì)介紹如下；業(yè)務(wù)參數(shù)由于不同 API 各自不同。1、 系統(tǒng)參數(shù)默認(rèn)采用json格式，參數(shù)列表如下序號參數(shù)命名 參數(shù)名稱長度 類型是否必選備注 協(xié)議參數(shù)1method能力編碼64StringY如“SO_BUSI_CHANGE_IMEI”2format業(yè)務(wù)參數(shù)格式20StringY填json

6、 或 xml,指定業(yè)務(wù)參數(shù)格式3appId應(yīng)用編碼12InterY5012204version版本20StringN1.05accessTokenoauh授權(quán)令牌100StringY如5ea6f06f-796b-48a2-a825-35a1909adffa6sign數(shù)字簽名100StringY有傳輸防篡改需求時必填，參見下面2.數(shù)字簽名生成7timestamp時間20StringY調(diào)用時間格式：yyyyMMddHH24mmss8busiSerial業(yè)務(wù)流水10StringY京東默認(rèn)傳1系統(tǒng)參數(shù)格式示例：method=SO_BUSI_CHANGE_IMEI&format=json&appId=5

7、01449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=1&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20140928165601&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5業(yè)務(wù)參數(shù)業(yè)務(wù)參數(shù)格式按照系統(tǒng)參數(shù)”form

8、at”所指定的格式來傳遞。1）如json格式示例:BillId:Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM2）xml格式示例：Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM注：如果系統(tǒng)參數(shù)需要放在POST體中，需要在URL中加入固定的參數(shù)及指定業(yè)務(wù)參數(shù)的key，URL示例如：http:/

9、ip:port/oppf?postSysParam=true&busiKey=cmcc_json_parasPost體內(nèi)容示例如：method=SO_BUSI_CHANGE_IMEI&format=json&appId=501449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=120003993902&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20140928165601&sign

10、=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5&cmcc_json_paras=8F9265B9DA900318B058594DD147DAD4C36F8A2E6CE008ABDB68CA16EBD0E29C7D3946D15D12284817BC2D6CA7B43C233.5. 參數(shù)加密對業(yè)務(wù)參數(shù)采用整體加密規(guī)則，使用AES256算法，調(diào)用sdk加密方法（sdk包見3.7生成數(shù)字簽名）進(jìn)行加密，加密示例如下：String busiPara

11、m = REGION_ID:A,CERT_TYPE:2,CERT_NO:1234567;String dataSecret = 501e3f2e8bd3c8b0bad3e16b795dd85b;String encyptBusiParam = SecurityUtils.encodeAES256HexUpper(busiParam, SecurityUtils.decodeHexUpper(dataSecret);System.out.println(encyptBusiParam);注：dataSecret為數(shù)據(jù)加密密鑰，默認(rèn)為應(yīng)用密鑰。3.6. 獲取令牌依據(jù)應(yīng)用信息里的授權(quán)類型不同，分以下

12、三種方式獲取訪問令牌：3.6.1. 授權(quán)碼模式適用于有服務(wù)端的應(yīng)用（如web應(yīng)用），分兩步獲取最終訪問令牌：1. 調(diào)用授權(quán)接口：08:20200/aopoauth/oauth/authorize請求參數(shù)：參數(shù)名必選類型說明app_idtrueString應(yīng)用在開放平臺注冊時分配的應(yīng)用標(biāo)識redirect_uritrueString與應(yīng)用信息中的回調(diào)地址保持一致，用戶授權(quán)后回調(diào)信息給應(yīng)用時使用。response_typetrueString響應(yīng)類型，此處必須為”code”響應(yīng)參數(shù)：參數(shù)名必選類型說明codetrueString授權(quán)碼，用于調(diào)用令牌接口獲取最終的

13、訪問令牌open_idtrueString用戶唯一標(biāo)識，根據(jù)app_id及移動手機(jī)用戶標(biāo)識生成。在不同的app_id下，同一個手機(jī)號生成的open_id也不一樣調(diào)用范例：08:20200/aopoauth/oauth/authorize?app_id=501280&redirect_uri=&response_type=code成功應(yīng)答：2. 調(diào)用令牌接口：08:20200/aopoauth/oauth/token請求參數(shù)：參數(shù)名必選類型說明app_idtrueString應(yīng)用在開放平臺注冊時分配的應(yīng)用標(biāo)識app_keyt

14、rueString應(yīng)用密鑰，應(yīng)用注冊時平臺分配。grant_typetrueString此處必須為” authorization_code”codetrueString授權(quán)碼，調(diào)用授權(quán)接口獲取。redirect_uritrueString與應(yīng)用信息中的回調(diào)地址保持一致，用戶授權(quán)后回調(diào)信息給應(yīng)用時使用。響應(yīng)參數(shù)：參數(shù)名必選類型說明access_tokentrueString獲取到的訪問令牌expires_intrueString令牌有效期（以秒為單位）refresh_tokenfalseString刷新令牌，如果授權(quán)類型支持令牌刷新調(diào)用范例：08:20200/

15、aopoauth/oauth/token?app_id=501280&app_key=f575e386e80d4cb634c2e9ae0b7b541a&grant_type=authorization_code&code=3Pv8kS&redirect_uri=成功應(yīng)答：access_token:a9ae4ae1-f062-4ff6-b0b8-fd73d96e558b,token_type:bearer,refresh_token:0b00920b-74c8-4ebb-8081-6c8191df4d4b,expires_in:2993.6.2. 簡化模式適用于沒有服務(wù)端的應(yīng)用（如手機(jī)/桌面客戶

16、端程序），通過調(diào)用開放平臺授權(quán)接口，一步獲得最終的訪問令牌，獲取方式如下：調(diào)用授權(quán)接口：08:20200/aopoauth/oauth/authorize請求參數(shù)：參數(shù)名必選類型說明app_idtrueString應(yīng)用在開放平臺注冊時分配的應(yīng)用標(biāo)識app_keytrueString應(yīng)用注冊時分配的應(yīng)用密鑰。redirect_uritrueString與應(yīng)用信息中的回調(diào)地址保持一致，用戶授權(quán)后回調(diào)信息給應(yīng)用時使用。response_typetrueString響應(yīng)類型，此處必須為”token”響應(yīng)參數(shù)：參數(shù)名必選類型說明access_tokentrueStri

17、ng獲取到的訪問令牌expires_intrueString令牌有效期（以秒為單位）open_idtrueString用戶唯一標(biāo)識，根據(jù)app_id及移動手機(jī)用戶標(biāo)識生成。在不同的app_id下，同一個手機(jī)號生成的open_id也不一樣調(diào)用示例：2:38081/aopoauth/oauth/authorize?app_id=501280&app_key=3ff70d60514774d0b3e9d13264c57813&redirect_uri=&response_type=token成功應(yīng)答：3.6.3. 客戶端信任模式適用于無需用戶登錄授權(quán)的合作應(yīng)用場合，應(yīng)用

18、憑自身的應(yīng)用ID和應(yīng)用密鑰，通過調(diào)用令牌接口，直接獲得無需用戶授權(quán)的訪問令牌。調(diào)用令牌接口：08:20200/aopoauth/oauth/token請求參數(shù)：參數(shù)名必選類型說明app_idtrueString應(yīng)用在開放平臺注冊時分配的應(yīng)用標(biāo)識app_keytrueString應(yīng)用注冊時分配的應(yīng)用密鑰。grant_typetrueString響應(yīng)類型，此處必須為”client_credentials”響應(yīng)參數(shù)：參數(shù)名必選類型說明access_tokentrueString獲取到的訪問令牌expires_intrueString令牌有效期（以秒為單位）調(diào)用示例

19、：08:20200/aopoauth/oauth/token?app_id=501295&app_key=3888bd16498334490f5eaf4355be982f&grant_type=client_credentials成功應(yīng)答：access_token:fbf3315c-2715-49f5-8c0a-31b99dbf796e,token_type:bearer,expires_in:863993.7. 生成數(shù)據(jù)簽名sign字段為報文數(shù)字簽名，具體的做法是將系統(tǒng)參數(shù)包裝成一個map，將業(yè)務(wù)報文轉(zhuǎn)換成相應(yīng)格式（json或xml）的字符串，然后調(diào)用sd

20、k數(shù)字簽名接口生成簽名，調(diào)用示例如下:Map sysParam = new HashMap();sysParam.put(method, CUST_QRY_CUST_INFO);sysParam.put(format, json);sysParam.put(timestamp, 20150702164343);sysParam.put(appId, 501300);sysParam.put(appKey, f575e386e80d4cb634c2e9ae0b7b541a);sysParam.put(version, 1.0);sysParam.put(accessToken, 5801b0d7

21、-013f-400e-bee8-59f7ac074880);String busiParam =REGION_ID:A,CERT_TYPE:2,CERT_NO:1234567;String key = edf3def8681986d00cf19e654e2f9150;String sign = SignUtil.sign(sysParam, busiParam, HmacSHA256, key);System.out.println(sign);Sdk文件列表:3.8. 能力參數(shù)返回序號參數(shù)命名 參數(shù)名稱長度 類型是否必選備注 返回參數(shù)1respCode返回碼10StringY00000 代表

22、成功，其他代表異常編碼2respDesc返回描述1000StringY3result返回值200StringY業(yè)務(wù)中心返回的內(nèi)容JSON返回報文參考： respCode :00000,respDesc:調(diào)用成功.”result”：“BillId”..”ResDes”.”號碼正確”XML返回報文參考：返回報文：00000張國中國十四行事實上鄭州1999-05-0800:00:00.0鄭州市金水區(qū)英協(xié)路null0李斯調(diào)用成功!4. 對外開放能力API4.1. 集團(tuán)類業(yè)務(wù)4.1.1. 成員添加/變更/刪除 . 接口描述主要完成集團(tuán)成員

23、的添加、變更和刪除。. 能力編碼SO_MEMBER_DEAL_OPER. 請求方式采用HTTP POST方式。. 接口類型異步接口，回調(diào)接口規(guī)范見.5. 業(yè)務(wù)參數(shù)參數(shù)說明是否必選參數(shù)類型加密字段備注GBILL_ID集團(tuán)計費號是String是集團(tuán)計費號FLAG操作標(biāo)識是String是1：添加；2：修改；3：刪除4：疊加包訂購BILL_ID成員號碼是String是有效河南移動手機(jī)號碼VALID_MONTH贈送流量有效期否String是添加和修改操作時候，此字段為必填項且必須為數(shù)字,填1代表1個月有效期，2代表2個月有效期，3代表3個月有效期

24、?！景嗁彯?dāng)月】MEM_SRVPKG成員資費包否String是A：個人30元500MB：個人50元1024MC：個人70元2048MD：個人100元3072ME：個人130元4096MF：個人180元6144MG：個人280元11264MH：個人3元10MI：個人5元30MJ：個人10元70MK：個人20元150MCUST_ORDER_ID訂單流水是外圍系統(tǒng)請求過來的唯一流水SMS_TEMPLATE短信模板否String0：集團(tuán)公司模板1：個性化模板一默認(rèn)值為0(疊加包還是默認(rèn)的模板，不用選擇。）范例：GBILL_ID: FLAG: ,BILL_ID: ,VALID_MONTH: ,MEM_

25、SRVPKG: ,CUST_ORDER_ID: ,“SMS_TEMPLATE”:”0”. 響應(yīng)參數(shù)參數(shù)說明是否必選參數(shù)類型備注respCode返回結(jié)果代碼是String默認(rèn)輸出 00000respDesc返回結(jié)果描述是String默認(rèn)輸出 success返回結(jié)果正常應(yīng)答報文如下：respCode:00000,respDesc:success4.1.2. 集團(tuán)成員已訂購流量查詢. 接口描述查詢成員已訂購的流量。. 能力編碼SO_MEMBER_DEAL_QUERY. 請求方式采用HTTP POST方式。. 接口類型同步接口4.1

26、.2.5. 請求參數(shù)業(yè)務(wù)參數(shù)屬性：名稱參數(shù)名類型長度是否必須示例值默認(rèn)值取值說明手機(jī)號碼BILL_IDStringV11是河南移動有效手機(jī)號碼范例： BILL_ID: . 響應(yīng)參數(shù)參數(shù)說明是否必選參數(shù)類型備注respCode結(jié)果代碼必選String接口調(diào)用的返回碼00000：成功，其他：失敗respDesc結(jié)果說明必選String接口調(diào)用的返回消息描述。result返回結(jié)果必選MAPResult 對象屬性參數(shù)說明是否必選參數(shù)類型備注SO_MEMBER_DEAL結(jié)果集必選LISTSO_MEMBER_DEAL對象中各節(jié)點的屬性名稱參數(shù)名類型長度是否必須示例值默認(rèn)值取值說明集團(tuán)名稱GR

27、OUP_NAMEString50是集團(tuán)名稱操作名稱MEM_SRVPKG_DESCString50是成員資費包描述生效日期VALID_DATEString25是生效日期失效日期EXPIRE_DATEString25是失效日期折扣DISCOUNTString50是折扣返回結(jié)果正常應(yīng)答報文如下：respCode:00000,respDesc:調(diào)用成功!,result:SO_MEMBER_DEAL:DISCOUNT:70,EXPIRE_DATE:2015-09-30 23:59:59.0,GROUP_NAME:aaaaaa,MEM_SRVPKG_DESC:個人5元30M,VALID_DATE:2015

28、-09-06 18:15:02.0,DISCOUNT:70,EXPIRE_DATE:2015-09-30 23:59:59.0,GROUP_NAME:bbbbb,MEM_SRVPKG_DESC:個人3元10M,VALID_DATE:2015-09-06 16:40:04.04.1.3. 成員處理情況查詢 . 接口描述根據(jù)外圍渠道訂單流水查詢運營商訂單處理情況。. 能力編碼SO_MEMBER_RETURN_QUERY . 請求方式采用HTTP POST方式。. 接口類型同步接口. 請求參數(shù)參數(shù)說明長度是否必選參數(shù)類型加密字段備

29、注CUST_ORDER_ID流水25是String是外圍渠道給CRM側(cè)流水范例：“CUST_ORDER_ID”:”. 響應(yīng)參數(shù)參數(shù)說明是否必選參數(shù)類型備注respCode結(jié)果代碼必選String接口調(diào)用的返回碼00000：成功，其他：失敗respDesc結(jié)果說明必選String接口調(diào)用的返回消息描述。result返回結(jié)果必選ListResult屬性參數(shù)說明是否必選參數(shù)類型備注BILL_ID手機(jī)號碼是String手機(jī)號碼MEM_SRVPKG_DESC訂購資費是String成員資費包描述VALID_DATE生效日期是String生效日期STATE處理結(jié)果是StringW正在受理M全網(wǎng)業(yè)務(wù)集團(tuán)公司受理中Y處理成功N處理失敗E反饋異常DEAL_RESULT處理結(jié)果是StringCRM側(cè)處理結(jié)果范例：返回json格式：result:“BILL_ID”:”,“MEM_SRVPKG_DESC”:”,VALID_DATE : , STATE : , DEAL_RESULT : ,respCode:00000,respDesc:s