能力开放平台接口规范3.1版本@流量统付.doc
22页
能力开放平台接口规范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. 对外开放能力API 134.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. 接入地址沙箱测试地址：http://211.138.30.208:9410/oppf业务接口地址: http://211.138.30.208: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/f2QXRA2jLNuM"}2）xml格式示例：
3.6. 获取令牌依据应用信息里的授权类型不同，分以下三种方式获取访问令牌：3.6.1. 授权码模式适用于有服务端的应用（如web应用），分两步获取最终访问令牌：1. 调用授权接口：http://211.138.30.208:20200/aopoauth/oauth/authorize请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用response_typetrueString响应类型，此处必须为”code”响应参数：参数名必选类型说明codetrueString授权码，用于调用令牌接口获取最终的访问令牌open_idtrueString用户唯一标识，根据app_id及移动用户标识生成在不同的app_id下，同一个号生成的open_id也不一样调用范例：http://211.138.30.208:20200/aopoauth/oauth/authorize?app_id=501280&redirect_uri=&response_type=code成功应答： 调用令牌接口：http://211.138.30.208:20200/aopoauth/oauth/token请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识app_keytrueString应用密钥，应用注册时平台分配。
grant_typetrueString此处必须为” authorization_code”codetrueString授权码，调用授权接口获取redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用响应参数：参数名必选类型说明access_tokentru。
