能力开放平台接口规范.版本最新版.doc

.能力开放平台接口规范V3.0编 写赵树伟编写 时间2015-8-21审 批审批者姓名（及其职务）审批 时间修订说明1. 成员添加/变更/删除接口能力编码业务参数：VALID_MONTH修改备注说明王洪奎2015-09-22修订说明2. 成员添加/变更/删除接口能力编码业务参数新增：SMS_TEMPLATE王洪奎2015-10-10版本V3.0能力开放平台接口规范(v3.0)2015-10-10目录1.前言41.1.术语41.2.缩略语42.接口概况52.1.接口简介52.2.通信机制52.3.接口安全52.3.1.数字签名63.系统对接73.1.接入说明73.2.接入方式73.3.接入地址73.4.调用参数73.5.参数加密83.6.获取令牌93.6.1.授权码模式93.6.2.简化模式103.6.3.客户端信任模式113.7.生成数据签名113.8.能力参数返回124.对外开放能力API134.1.集团类业务134.1.1.成员添加/变更/删除134.1.2.集团成员已订购流量查询154.1.3.成员处理情况查询164.1.4集团帐户实时余额查询新增接口185.回调第三方接口(规范)205.1.成员添加/变更/删除结果通知206.附录221. 前言本文档主要用于定义第三方应用与能力开放平台之间通讯的接口规范，作为程序开发的依据。本规范主要包括以下几方面内容：接口通信机制、接口描述和接口定义。1.1. 术语本规范涉及的术语描述如下：表1-1术语术语/定义解释1.2. 缩略语表1-2缩略语缩略语英文全称中文含义DEVApplication Developer应用开发者APPApplication应用EAEnabler能力2. 接口概况2.1. 接口简介能力开放平台将运营商内部能力开放给互联网的第三方系统，包含合约套餐办理类、流量类、业务查询类能力等。本协议规范描述的接口如图1-1中所示。图1-1 协议接口位置2.2. 通信机制 能力开放平台开放接口采用REST风格，使用HTTP+JSON/HTTP+XML报文方式承载交易信息。2.3. 接口安全本开放平台的接口安全通过2级的安全进行保障，描述如下：1、对调用方的身份认证，每个接入开放平台的第三方系统都需要进行调用服务器地址的提前注册；2、为每个接入方分配一个非对称密钥，约定一种对应签名算法，接入方的请求中必须加上签名参数，用于请求方身份验证和请求的防篡改验证；2.3.1. 数字签名同3.7章节。3. 系统对接3.1. 接入说明凡是接入河南移动能力平台的第三方系统，一律按照本规范接入能力开放平台。第三方渠道在申请能力后首先需求调用沙箱接口进行测试，测试通过后再调用业务接口进行业务联调和使用。3.2. 接入方式 协议：http3.3. 接入地址沙箱测试地址：08:9410/oppf业务接口地址: 08:20110/oppf3.4. 调用参数调用API ，需传入系统参数和业务参数。系统参数拼接在URL上，业务参数放在POST体中。对于接口说明中的标记为必填项的字段，必须有相应的非空、合法性校验，并精确返回异常信息，如：MobileNo不合法。系统参数详细介绍如下；业务参数由于不同 API 各自不同。1、 系统参数默认采用json格式，参数列表如下序号参数命名 参数名称长度 类型是否必选备注 协议参数1method能力编码64StringY如“SO_BUSI_CHANGE_IMEI”2format业务参数格式20StringY填json 或 xml,指定业务参数格式3appId应用编码12InterY5012204version版本20StringN1.05accessTokenoauh授权令牌100StringY如5ea6f06f-796b-48a2-a825-35a1909adffa6sign数字签名100StringY有传输防篡改需求时必填，参见下面2.数字签名生成7timestamp时间20StringY调用时间格式：yyyyMMddHH24mmss8busiSerial业务流水10StringY京东默认传1系统参数格式示例：method=SO_BUSI_CHANGE_IMEI&format=json&appId=501449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=1&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20140928165601&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5业务参数业务参数格式按照系统参数”format”所指定的格式来传递。1）如json格式示例:BillId:Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM2）xml格式示例：Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM注：如果系统参数需要放在POST体中，需要在URL中加入固定的参数及指定业务参数的key，URL示例如：http:/ip:port/oppf?postSysParam=true&busiKey=cmcc_json_parasPost体内容示例如：method=SO_BUSI_CHANGE_IMEI&format=json&appId=501449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=120003993902&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20140928165601&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5&cmcc_json_paras=8F9265B9DA900318B058594DD147DAD4C36F8A2E6CE008ABDB68CA16EBD0E29C7D3946D15D12284817BC2D6CA7B43C233.5. 参数加密对业务参数采用整体加密规则，使用AES256算法，调用sdk加密方法（sdk包见3.7生成数字签名）进行加密，加密示例如下：String busiParam = 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为数据加密密钥，默认为应用密钥。3.6. 获取令牌依据应用信息里的授权类型不同，分以下三种方式获取访问令牌：3.6.1. 授权码模式适用于有服务端的应用（如web应用），分两步获取最终访问令牌：1. 调用授权接口：08:20200/aopoauth/oauth/authorize请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。response_typetrueString响应类型，此处必须为”code”响应参数：参数名必选类型说明codetrueString授权码，用于调用令牌接口获取最终的访问令牌open_idtrueString用户唯一标识，根据app_id及移动手机用户标识生成。在不同的app_id下，同一个手机号生成的open_id也不一样调用范例：08:20200/aopoauth/oauth/authorize?app_id=501280&redirect_uri=&response_type=code成功应答：/?code=3Pv8kS&open_id=8911f179-bc87-4412-9712-24b4921f2c312. 调用令牌接口：08:20200/aopoauth/oauth/token请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识app_keytrueString应用密钥，应用注册时平台分配。grant_typetrueString此处必须为” authorization_code”codetrueString授权码，调用授权接口获取。redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。响应参数：参数名必选类型说明access_tokentrueString获取到的访问令牌expires_intrueString令牌有效期（以秒为单位）refresh_tokenfalseString刷新令牌，如果授权类型支持令牌刷新调用范例：08:20200/aopoauth/oauth/token?app_id=501280&app_key=f575e386e80d4cb634c2e9ae0b7b541a&grant_type=authorization_code&code=3Pv8kS&redirect_uri=成功应答：access_token:a9ae4ae1-f062-4ff6-b0b8-fd73d96e558b,token_type:bearer,refresh_token:0b00920b-74c8-4ebb-8081-6c8191df4d4b,expires_in:2993.6.2. 简化模式适用于没有服务端的应用（如手机/桌面客户端程序），通过调用开放平台授权接口，一步获得最终的访问令牌，获取方式如下：调用授权接口：08:20200/aopoauth/oauth/authorize请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识app_keytrueString应用注册时分配的应用密钥。redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。response_typetrueString响应类型，此处必须为”token”响应参数：参数名必选类型说明access_tokentrueString获取到的访问令牌expires_intrueString令牌有效期（以秒为单位）open_idtrueString用户唯一标识，根据app_id及移动手机用户标识生成。在不同的app_id下，同一个手机号生成的open_id也不一样调用示例：2:38081/aopoauth/oauth/authorize?app_id=501280&app_key=3ff70d60514774d0b3e9d13264c57813&redirect_uri=&response_type=token成功应答：/#access_token=5851a2f3-cdc8-4a73-9c9b-8c83b4b5db9d&token_type=bearer&open_id=8911f179-bc87-4412-9712-24b4921f2c31&expires_in=2993.6.3. 客户端信任模式适用于无需用户登录授权的合作应用场合，应用凭自身的应用ID和应用密钥，通过调用令牌接口，直接获得无需用户授权的访问令牌。调用令牌接口：08:20200/aopoauth/oauth/token请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识app_keytrueString应用注册时分配的应用密钥。grant_typetrueString响应类型，此处必须为”client_credentials”响应参数：参数名必选类型说明access_tokentrueString获取到的访问令牌expires_intrueString令牌有效期（以秒为单位）调用示例：08:20200/aopoauth/oauth/token?app_id=501295&app_key=3888bd16498334490f5eaf4355be982f&grant_type=client_credentials成功应答：access_token:fbf3315c-2715-49f5-8c0a-31b99dbf796e,token_type:bearer,expires_in:863993.7. 生成数据签名sign字段为报文数字签名，具体的做法是将系统参数包装成一个map，将业务报文转换成相应格式（json或xml）的字符串，然后调用sdk数字签名接口生成签名，调用示例如下: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-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. 能力参数返回序号参数命名 参数名称长度 类型是否必选备注 返回参数1respCode返回码10StringY00000 代表成功，其他代表异常编码2respDesc返回描述1000StringY3result返回值200StringY业务中心返回的内容JSON返回报文参考： respCode :00000,respDesc:调用成功.”result”：“BillId”..”ResDes”.”号码正确”XML返回报文参考：返回报文：00000张国中国十四行事实上郑州1999-05-0800:00:00.0郑州市金水区英协路null0李斯调用成功!4. 对外开放能力API4.1. 集团类业务4.1.1. 成员添加/变更/删除 . 接口描述主要完成集团成员的添加、变更和删除。. 能力编码SO_MEMBER_DEAL_OPER. 请求方式采用HTTP POST方式。. 接口类型异步接口，回调接口规范见.5. 业务参数参数说明是否必选参数类型加密字段备注GBILL_ID集团计费号是String是集团计费号FLAG操作标识是String是1：添加；2：修改；3：删除4：叠加包订购BILL_ID成员号码是String是有效河南移动手机号码VALID_MONTH赠送流量有效期否String是添加和修改操作时候，此字段为必填项且必须为数字,填1代表1个月有效期，2代表2个月有效期，3代表3个月有效期。【包含订购当月】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订单流水是外围系统请求过来的唯一流水SMS_TEMPLATE短信模板否String0：集团公司模板1：个性化模板一默认值为0(叠加包还是默认的模板，不用选择。）范例：GBILL_ID: FLAG: ,BILL_ID: ,VALID_MONTH: ,MEM_SRVPKG: ,CUST_ORDER_ID: ,“SMS_TEMPLATE”:”0”. 响应参数参数说明是否必选参数类型备注respCode返回结果代码是String默认输出 00000respDesc返回结果描述是String默认输出 success返回结果正常应答报文如下：respCode:00000,respDesc:success4.1.2. 集团成员已订购流量查询. 接口描述查询成员已订购的流量。. 能力编码SO_MEMBER_DEAL_QUERY. 请求方式采用HTTP POST方式。. 接口类型同步接口. 请求参数业务参数属性：名称参数名类型长度是否必须示例值默认值取值说明手机号码BILL_IDStringV11是河南移动有效手机号码范例： BILL_ID: . 响应参数参数说明是否必选参数类型备注respCode结果代码必选String接口调用的返回码00000：成功，其他：失败respDesc结果说明必选String接口调用的返回消息描述。result返回结果必选MAPResult 对象属性参数说明是否必选参数类型备注SO_MEMBER_DEAL结果集必选LISTSO_MEMBER_DEAL对象中各节点的属性名称参数名类型长度是否必须示例值默认值取值说明集团名称GROUP_NAMEString50是集团名称操作名称MEM_SRVPKG_DESCString50是成员资费包描述生效日期VALID_DATEString25是生效日期失效日期EXPIRE_DATEString25是失效日期折扣DISCOUNTString50是折扣返回结果正常应答报文如下：respCode:00000,respDesc:调用成功!,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-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. 成员处理情况查询 . 接口描述根据外围渠道订单流水查询运营商订单处理情况。. 能力编码SO_MEMBER_RETURN_QUERY . 请求方式采用HTTP POST方式。. 接口类型同步接口. 请求参数参数说明长度是否必选参数类型加密字段备注CUST_ORDER_ID流水25是String是外围渠道给CRM侧流水范例：“CUST_ORDER_ID”:”. 响应参数参数说明是否必选参数类型备注respCode结果代码必选String接口调用的返回码00000：成功，其他：失败respDesc结果说明必选String接口调用的返回消息描述。result返回结果必选ListResult属性参数说明是否必选参数类型备注BILL_ID手机号码是String手机号码MEM_SRVPKG_DESC订购资费是String成员资费包描述VALID_DATE生效日期是String生效日期STATE处理结果是StringW正在受理M全网业务集团公司受理中Y处理成功N处理失败E反馈异常DEAL_RESULT处理结果是StringCRM侧处理结果范例：返回json格式：result:“BILL_ID”:”,“MEM_SRVPKG_DESC”:”,VALID_DATE : , STATE : , DEAL_RESULT : ,respC