能力开放平台接口规范能力开放平台接口规范2015-10-10目录1. 前言................................................................... 错误!未定义书签。
. 术语 ................................................................ 错误!未定义书签。
. 缩略语 .............................................................. 错误!未定义书签。
2. 接口概况............................................................... 错误!未定义书签。
. 接口简介 ............................................................ 错误!未定义书签。
. 通信机制 ............................................................ 错误!未定义书签。
. 接口安全 ............................................................ 错误!未定义书签。
数字签名........................................................ 错误!未定义书签。
3. 系统对接............................................................... 错误!未定义书签。
. 接入说明 ............................................................ 错误!未定义书签。
. 接入方式 ............................................................ 错误!未定义书签。
. 接入地址 ............................................................ 错误!未定义书签。
. 沙箱测试地址：业务接口地址:调用参数................................. 错误!未定义书签。
. 参数加密 ............................................................ 错误!未定义书签。
. 获取令牌 ............................................................ 错误!未定义书签。
授权码模式...................................................... 错误!未定义书签。
简化模式........................................................ 错误!未定义书签。
客户端信任模式.................................................. 错误!未定义书签。
. 生成数据签名 ........................................................ 错误!未定义书签。
. 能力参数返回 ........................................................ 错误!未定义书签。
4. 对外开放能力API ........................................................ 错误!未定义书签。
. 集团类业务 .......................................................... 错误!未定义书签。
成员添加/变更/删除.............................................. 错误!未定义书签。
集团成员已订购流量查询.......................................... 错误!未定义书签。
成员处理情况查询................................................ 错误!未定义书签。
集团帐户实时余额查询—新增接口............................................. 错误!未定义书签。
5. 回调第三方接口(规范) ................................................... 错误!未定义书签。
. 成员添加/变更/删除结果通知 .......................................... 错误!未定义书签。
6. 附录................................................................... 错误!未定义书签。
1.前言本文档主要用于定义第三方应用与能力开放平台之间通讯的接口规范，作为程序开发的依据。
本规范主要包括以下几方面内容：接口通信机制、接口描述和接口定义。
1.1.术语本规范涉及的术语描述如下：表1-1术语1.2.缩略语表1-2缩略语➢2.接口概况2.1.接口简介能力开放平台将运营商内部能力开放给互联网的第三方系统，包含合约套餐办理类、流量类、业务查询类能力等。
本协议规范描述的接口如图1-1中所示。
接入系统图1-1 协议接口位置2.2.通信机制能力开放平台开放接口采用REST风格，使用HTTP+JSON/HTTP+XML报文方式承载交易信息。
2.3.接口安全本开放平台的接口安全通过2级的安全进行保障，描述如下：1、对调用方的身份认证，每个接入开放平台的第三方系统都需要进行调用服务器地址的提前注册；2、为每个接入方分配一个非对称密钥，约定一种对应签名算法，接入方的请求中必须加上签名参数，用于请求方身份验证和请求的防篡改验证；2.3.1.数字签名同章节。
3.系统对接3.1.接入说明凡是接入河南移动能力平台的第三方系统，一律按照本规范接入能力开放平台。
第三方渠道在申请能力后首先需求调用沙箱接口进行测试，测试通过后再调用业务接口进行业务联调和使用。
3.2.接入方式协议：http3.3.接入地址3.4.沙箱测试地址：业务接口地址: 调用参数调用API ，需传入系统参数和业务参数。
系统参数拼接在URL上，业务参数放在POST体中。
对于接口说明中的标记为必填项的字段，必须有相应的非空、合法性校验，并精确返回异常信息，如：MobileNo不合法。
系统参数详细介绍如下；业务参数由于不同 API 各自不同。
1、系统参数默认采用json格式，参数列表如下序号参数命名参数名称长度类型是否必选备注协议参数1method能力编码64String Y如“SO_BUSI_CHANGE_IMEI”填json 或 xml,指定业务2format业务参数格式20String Y参数格式3appId应用编码12Inter Y5012204version版本20String N如5accessToken oauh授权令牌100String Y5ea6f06f-796b-48a2-a825-系统参数格式示例：method=SO_BUSI_CHANGE_IMEI&format=json&appId=501449&appKey=8ea63a3e403228eedf5dfd6a705c 685c&busiSerial=1&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48 a2-a825-35a1909adffa×tamp=20&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hC HG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5业务参数业务参数格式按照系统参数”format”所指定的格式来传递。
1）如json格式示例:{"BillId":"Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2y wCzTwZXlrzr/f2QXRA2jLNuM"}2）xml格式示例：<root><BillId>Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfc E2ywCzTwZXlrzr/f2QXRA2jLNuM</BillId></root>注：如果系统参数需要放在POST体中，需要在URL中加入固定的参数及指定业务参数的key，URL示例如：3.5.参数加密对业务参数采用整体加密规则，使用AES256算法，调用sdk加密方法（sdk包见生成数字签名）进行加密，加密示例如下：注：dataSecret为数据加密密钥，默认为应用密钥。
3.6.获取令牌依据应用信息里的授权类型不同，分以下三种方式获取访问令牌：3.6.1.授权码模式适用于有服务端的应用（如web应用），分两步获取最终访问令牌：调用授权接口：请求参数：响应参数：调用范例：&redirect_uri=&response_type=code成功应答：&open_id=8911f179-bc87-4412-9712-24b4921f2c31调用令牌接口：请求参数：响应参数：调用范例：&app_key=f575e386e80d4cb634c2e9ae0b7b541a&grant_type=authorization_code&code=3Pv8kS&red irect_uri=成功应答：{"access_token":"a9ae4ae1-f062-4ff6-b0b8-fd73d96e558b","token_type":"bearer","refresh_t oken":"0b00920b-74c8-4ebb-8081-6c8191df4d4b","expires_in":299}3.6.2.简化模式适用于没有服务端的应用（如手机/桌面客户端程序），通过调用开放平台授权接口，一步获得最终的访问令牌，获取方式如下：调用授权接口：请求参数：响应参数：调用示例：&app_key=3ff70dd0b3e9d13264c57813&redirect_uri=&response_type=token成功应答：&token_type=bearer&open_id=8911f179-bc87-4412-9712-24b4921f2c31&expires_in=2993.6.3.客户端信任模式适用于无需用户登录授权的合作应用场合，应用凭自身的应用ID和应用密钥，通过调用令牌接口，直接获得无需用户授权的访问令牌。