能力开放平台接口规范31版本流量统付Word文档下载推荐.docx
《能力开放平台接口规范31版本流量统付Word文档下载推荐.docx》由会员分享，可在线阅读，更多相关《能力开放平台接口规范31版本流量统付Word文档下载推荐.docx（24页珍藏版）》请在冰豆网上搜索。
图1-1协议接口位置
2.2.通信机制
能力开放平台开放接口采用REST风格，使用HTTP+JSON/HTTP+XML报文方式承载交易信息。
2.3.接口安全
本开放平台的接口安全通过2级的安全进行保障，描述如下：
1、对调用方的身份认证，每个接入开放平台的第三方系统都需要进行调用服务
器地址的提前注册；
2、为每个接入方分配一个非对称密钥，约定一种对应签名算法，接入方的请求
中必须加上签名参数，用于请求方身份验证和请求的防篡改验证；
2.3.1.数字签名
同3.7章节。
3.系统对接
3.1.接入说明
凡是接入河南移动能力平台的第三方系统，一律按照本规范接入能力开放平台。
第三方渠道在申请能力后首先需求调用沙箱接口进行测试，测试通过后再调用业务接口进行业务联调和使用。
3.2.接入方式
协议：
http
3.3.接入地址
沙箱测试地址：
http:
//211.138.30.208:
9410/oppf
业务接口地址:
http:
20110/oppf
3.4.调用参数
调用API，需传入系统参数和业务参数。
系统参数拼接在URL上，业务参数放在POST体中。
对于接口说明中的标记为必填项的字段，必须有相应的非空、合法性校验，并精确返回异常信息，如：
MobileNo不合法。
系统参数详细介绍如下；
业务参数由于不同API各自不同。
1、系统参数默认采用json格式，参数列表如下
序号
参数命名
参数名称
长度
类型
是否必选
备注
协议参数
1
method
能力编码
64
String
Y
如“SO_BUSI_CHANGE_IMEI”
2
format
业务参数格式
20
填json或xml,指定业务参数格式
3
appId
应用编码
12
Inter
501220
4
version
N
1.0
5
accessToken
oauh授权令牌
100
如5ea6f06f-796b-48a2-a825-
35a1909adffa
6
sign
数字签名
有传输防篡改需求时必填，参见下面2.数字签名生成
7
timestamp
时间
调用时间格式：
yyyyMMddHH24mmss
8
busiSerial
业务流水
10
京东默认传1
系统参数格式示例：
method=SO_BUSI_CHANGE_IMEI&
format=json&
appId=501449&
appKey=8ea63a3e403228eedf5dfd6a705c685c&
busiSerial=1&
version=3546fbdb6b1041cb4eb26339b9154e2c&
accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa&
timestamp=20140928165601&
sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5
业务参数
业务参数格式按照系统参数”format”所指定的格式来传递。
1）如json格式示例:
{"
BillId"
:
"
Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM"
}
2）xml格式示例：
<
root>
BillId>
Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM<
/BillId>
/root>
注：
如果系统参数需要放在POST体中，需要在URL中加入固定的参数及指定业务参数的key，URL示例如：
//ip:
port/oppf?
postSysParam=true&
busiKey=cmcc_json_paras
Post体内容示例如：
busiSerial=120003993902&
sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5&
cmcc_json_paras=8F9265B9DA900318B058594DD147DAD4C36F8A2E6CE008ABDB68CA16EBD0E29C7D3946D15D12284817BC2D6CA7B43C23
3.5.参数加密
对业务参数采用整体加密规则，使用AES256算法，调用sdk加密方法（sdk包见3.7生成数字签名）进行加密，加密示例如下：
StringbusiParam="
{\"
REGION_ID\"
\"
A\"
\"
CERT_TYPE\"
2\"
CERT_NO\"
1234567\"
}"
;
StringdataSecret="
501e3f2e8bd3c8b0bad3e16b795dd85b"
StringencyptBusiParam=SecurityUtils.encodeAES256HexUpper（busiParam,SecurityUtils.decodeHexUpper（dataSecret））;
System.out.println（encyptBusiParam）;
dataSecret为数据加密密钥，默认为应用密钥。
3.6.获取令牌
依据应用信息里的授权类型不同，分以下三种方式获取访问令牌：
3.6.1.授权码模式
适用于有服务端的应用（如web应用），分两步获取最终访问令牌：
1.调用授权接口：
20200/aopoauth/oauth/authorize
请求参数：
参数名
必选
说明
app_id
true
应用在开放平台注册时分配的应用标识
redirect_uri
与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。
response_type
响应类型，此处必须为”code”
响应参数：
code
授权码，用于调用令牌接口获取最终的访问令牌
open_id
用户唯一标识，根据app_id及移动手机用户标识生成。
在不同的app_id下，同一个手机号生成的open_id也不一样
调用范例：
20200/aopoauth/oauth/authorize?
app_id=501280&
redirect_uri=&
response_type=code
成功应答：
2.调用令牌接口：
20200/aopoauth/oauth/token
app_key
应用密钥，应用注册时平台分配。
grant_type
此处必须为”authorization_code”
授权码，调用授权接口获取。
access_token
获取到的访问令牌
expires_in
令牌有效期（以秒为单位）
refresh_token
false
刷新令牌，如果授权类型支持令牌刷新
20200/aopoauth/oauth/token?
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"
299}
3.6.2.简化模式
适用于没有服务端的应用（如手机/桌面客户端程序），通过调用开放平台授权接口，一步获得最终的访问令牌，获取方式如下：
调用授权接口：
应用注册时分配的应用密钥。
响应类型，此处必须为”token”
调用示例：
//10.87.30.12:
38081/aopoauth/oauth/authorize?
app_key=3ff70d60514774d0b3e9d13264c57813&
response_type=token
3.6.3.客户端信任模式
适用于无需用户登录授权的合作应用场合，应用凭自身的应用ID和应用密钥，通过调用令牌接口，直接获得无需用户授权的访问令牌。
调用令牌接口：
响应类型，此处必须为”client_credentials”
app_id=501295&
app_key=3888bd16498334490f5eaf4355be982f&
grant_type=client_credentials
fbf3315c-2715-49f5-8c0a-31b99dbf796e"
86399}
3.7.生成数据签名
sign字段为报文数字签名，具体的做法是将系统参数包装成一个map，将业务报文转换成相应格式（json或xml）的字符串，然后调用sdk数字签名接口生成签名，调用示例如下:
Map<
String,String>
sysParam=newHashMap<
（）;
sysParam.put（"
method"
"
CUST_QRY_CUST_INFO"
）;
format"
json"
timestamp"
20150702164343"
appId"
501300"
appKey"
f575e386e80d4cb634c2e9ae0b7b541a"
version"
1.0"
accessToken"
5801b0d7-013f-400e-bee8-59f7ac074880"
StringbusiParam=
Stringkey="
edf3def8681986d00cf19e654e2f9150"
Stringsign=SignUtil.sign（sysParam,busiParam,"
HmacSHA256"
key）;
System.out.println（sign）;
Sdk文件列表:
3.8.能力参数返回
返回参数
respCode
返回码
00000代表成功，其他代表异常编码
respDesc
返回描述
1000
result
返回值
200
业务中心返回的内容
JSON返回报文参考：
respCode"
00000"
respDesc"
调用成功"
.”result”：
{“BillId”.”137********”.”ResDes”.”号码正确”}}
XML返回报文参考：
返回报文：
?
xml
version="
encoding="
UTF-8"
>
respCode>
00000<
/respCode>
result>
CUST_NAME>
张三<
/CUST_NAME>
CONT_MOBILE>
13888888888<
/CONT_MOBILE>
RESIDE_ADDR>
中国中国十四行事实上郑州<
/RESIDE_ADDR>
CUST_BIRTHDAY>
1999-05-08
00:
00.0<
/CUST_BIRTHDAY>
CUST_CERT_ADDR>
郑州市金水区英协路<
/CUST_CERT_ADDR>
CONT_PHONE>
null<
/CONT_PHONE>
CUST_SEX>
0<
/CUST_SEX>
CONT_NAME>
李斯<
/CONT_NAME>
/result>
respDesc>
调用成功!
/respDesc>
4.对外开放能力API
4.1.集团类业务
4.1.1.成员添加/变更/删除
4.1.1.1.接口描述
主要完成集团成员的添加、变更和删除。
4.1.1.2.能力编码
SO_MEMBER_DEAL_OPER
4.1.1.3.请求方式
采用HTTPPOST方式。
4.1.1.4.接口类型
异步接口，回调接口规范见5.1
4.1.1.5.业务参数
参数
参数类型
加密字段
备注
GBILL_ID
集团计费号
是
FLAG
操作标识
1：
添加；
2：
修改；
3：
删除
4：
叠加包订购
BILL_ID
成员号码
有效河南移动手机号码
VALID_MONTH
赠送流量有效期
否
添加和修改操作时候，此字段为必填项且必须为数字,填1代表1个月有效期，2代表2个月有效期，3代表3个月有效期。
【包含订购当月】
MEM_SRVPKG
成员资费包
A：
个人30元500M
B：
个人50元1024M
C：
个人70元2048M
D：
个人100元3072M
E：
个人130元4096M
F：
个人180元6144M
G：
个人280元11264M
H：
个人3元10M
I：
个人5元30M
J：
个人10元70M
K：
个人20元150M
CUST_ORDER_ID
订单流水
外围系统请求过来的唯一流水
短信模板
0：
集团公司模板
个性化模板一
默认值为0
（叠加包还是默认的模板，不用选择。
）
范例：
{
"
GBILL_ID"
FLAG"
BILL_ID"
VALID_MONTH"
MEM_SRVPKG"
CUST_ORDER_ID"
“SMS_TEMPLATE”:
”0”
4.1.1.6.响应参数
返回结果代码
默认输出00000
返回结果描述
默认输出success
返回结果
正常应答报文如下：
respCode"
success"
4.1.2.集团成员已订购流量查询
4.1.2.1.接口描述
查询成员已订购的流量。
4.1.2.2.能力编码
SO_MEMBER_DEAL_QUERY
4.1.2.3.请求方式
4.1.2.4.接口类型
同步接口
4.1.2.5.请求参数
业务参数属性：
名称
长度
是否必须
示例值
默认值
取值说明
手机号码
V11
河南移动有效手机号码
4.1.2.6.响应参数
结果代码
接口调用的返回码
00000：
成功，其他：
失败
结果说明
接口调用的返回消息描述。
MAP
Result对象属性
SO_MEMBER_DEAL
结果集
LIST
SO_MEMBER_DEAL对象中各节点的属性
集团名称
GROUP_NAME
50
操作名称
MEM_SRVPKG_DESC
成员资费包描述
生效日期
VALID_DATE
25
失效日期
EXPIRE_DATE
折扣
DISCOUNT
result"
SO_MEMBER_D
升级会员 