《能力开 放平台接口规范3.1版本@流量统付》由会员分享，可在线阅读，更多相关《能力开 放平台接口规范3.1版本@流量统付（22页珍藏版）》请在金锄头文库上搜索。
1、能力开放平台接口规范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
2、.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. 前言本文档主要用于定义第三方应用与能力开放平台之间通讯的接口规范，作为程序开发的依据。本规范主要包括以下几方面内容：接口通信机制、接口描述
3、和接口定义。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级
4、的安全进行保障，描述如下：1、对调用方的身份认证，每个接入开放平台的第三方系统都需要进行调用服务器地址的提前注册；2、为每个接入方分配一个非对称密钥，约定一种对应签名算法，接入方的请求中必须加上签名参数，用于请求方身份验证和请求的防篡改验证；2.3.1. 数字签名同3.7章节。3. 系统对接3.1. 接入说明凡是接入河南移动能力平台的第三方系统，一律按照本规范接入能力开放平台。第三方渠道在申请能力后首先需求调用沙箱接口进行测试，测试通过后再调用业务接口进行业务联调和使用。3.2. 接入方式 协议：http3.3. 接入地址沙箱测试地址：http:/211.138.30.208:9410/opp
5、f业务接口地址: http:/211.138.30.208:20110/oppf3.4. 调用参数调用API ，需传入系统参数和业务参数。系统参数拼接在URL上，业务参数放在POST体中。对于接口说明中的标记为必填项的字段，必须有相应的非空、合法性校验，并精确返回异常信息，如：MobileNo不合法。系统参数详细介绍如下；业务参数由于不同 API 各自不同。1、 系统参数默认采用json格式，参数列表如下序号参数命名 参数名称长度 类型是否必选备注 协议参数1method能力编码64StringY如“SO_BUSI_CHANGE_IMEI”2format业务参数格式20StringY填json
6、 或 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=5
7、01449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=1&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20140928165601&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5业务参数业务参数格式按照系统参数”form
8、at”所指定的格式来传递。1）如json格式示例:BillId:Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM2）xml格式示例：Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM注：如果系统参数需要放在POST体中，需要在URL中加入固定的参数及指定业务参数的key，URL示例如：http:/
9、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
10、=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5&cmcc_json_paras=8F9265B9DA900318B058594DD147DAD4C36F8A2E6CE008ABDB68CA16EBD0E29C7D3946D15D12284817BC2D6CA7B43C233.5. 参数加密对业务参数采用整体加密规则，使用AES256算法，调用sdk加密方法（sdk包见3.7生成数字签名）进行加密，加密示例如下：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为数据加密密钥，默认为应用密钥。3.6. 获取令牌依据应用信息里的授权类型不同，分以下
12、三种方式获取访问令牌：3.6.1. 授权码模式适用于有服务端的应用（如web应用），分两步获取最终访问令牌：1. 调用授权接口：http:/211.138.30.208:20200/aopoauth/oauth/authorize请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。response_typetrueString响应类型，此处必须为”code”响应参数：参数名必选类型说明codetrueString授权码，用于调用令牌接口获取最终的
13、访问令牌open_idtrueString用户唯一标识，根据app_id及移动手机用户标识生成。在不同的app_id下，同一个手机号生成的open_id也不一样调用范例：http:/211.138.30.208:20200/aopoauth/oauth/authorize?app_id=501280&redirect_uri=http:/&response_type=code成功应答：https:/ 调用令牌接口：http:/211.138.30.208:20200/aopoauth/oauth/token请求参数：参数名必选类型说明app_idtrueString应用在开放平台注册时分配的应用标识app_keytrueString应用密钥，应用注册时平台分配。grant_typetrueString此处必须为” authorization_code”codetrueString授权码，调用授权接口获取。redirect_uritrueString与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。响应参数：参数名必选类型说明access_tokentru
