能力开放平台接口规范31版本流量统付.docx
《能力开放平台接口规范31版本流量统付.docx》由会员分享，可在线阅读，更多相关《能力开放平台接口规范31版本流量统付.docx（25页珍藏版）》请在冰点文库上搜索。
能力开放平台接口规范31版本流量统付
能力开放平台接口规范
编写
赵树伟
编写时间
2015-8-21
审批
审批者姓名（及其职务）
审批时间
修订说明
1.成员添加/变更/删除接口能力编码业务参数：
VALID_MONTH修改备注说明
王洪奎
2015-09-22
修订说明
2.成员添加/变更/删除接口能力编码业务参数新增：
SMS_TEMPLATE
王洪奎
2015-10-10
版本
能力开放平台接口规范
2015-10-10
1.前言
本文档主要用于定义第三方应用与能力开放平台之间通讯的接口规范，作为程序开发的依据。
本规范主要包括以下几方面内容：
接口通信机制、接口描述和接口定义。
1.1.术语
本规范涉及的术语描述如下：
表1-1术语
术语/定义
解释
1.2.缩略语
表1-2缩略语
缩略语
英文全称
中文含义
DEV
ApplicationDeveloper
应用开发者
APP
Application
应用
EA
Enabler
能力
Ø
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.接入方式
协议：
http
3.3.接入地址
3.4.沙箱测试地址：
业务接口地址:
调用参数
调用API，需传入系统参数和业务参数。
系统参数拼接在URL上，业务参数放在POST体中。
对于接口说明中的标记为必填项的字段，必须有相应的非空、合法性校验，并精确返回异常信息，如：
MobileNo不合法。
系统参数详细介绍如下；业务参数由于不同API各自不同。
1、系统参数默认采用json格式，参数列表如下
序号
参数命名
参数名称
长度
类型
是否必选
备注
协议参数
1
method
能力编码
64
String
Y
如“SO_BUSI_CHANGE_IMEI”
2
format
业务参数格式
20
String
Y
填json或xml,指定业务参数格式
3
appId
应用编码
12
Inter
Y
501220
4
version
版本
20
String
N
5
accessToken
oauh授权令牌
100
String
Y
如5ea6f06f-796b-48a2-a825-
35a1909adffa
6
sign
数字签名
100
String
Y
有传输防篡改需求时必填，参见下面2.数字签名生成
7
timestamp
时间
20
String
Y
调用时间格式：
yyyyMMddHH24mmss
8
busiSerial
业务流水
10
String
Y
京东默认传1
系统参数格式示例：
method=SO_BUSI_CHANGE_IMEI&format=json&appId=501449&appKey=8ea63a3e403228eedf5dfd6a705c685c&busiSerial=1&version=3546fbdb6b1041cb4eb26339b9154e2c&accessToken=5ea6f06f-796b-48a2-a825-35a1909adffa×tamp=20&sign=EEd8sPcxlULRz7MThkVcUfIVEwfuT5Db+Tb8qfmRib2pK2hCHG8MqgsVebW1mmSv6Ml8jnqJmh1czWLgY1DuL8f4wJ3c68yTc8l5
业务参数
业务参数格式按照系统参数”format”所指定的格式来传递。
1）如json格式示例:
{"BillId":
"Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM"}
2）xml格式示例：
Qbnx8gxDELYpQODlqYFbM9nq7XnqQHIt0lu2mC4ozOJYKJKiD2fMTkrPKRsY4uXeUek/8IVfcE2ywCzTwZXlrzr/f2QXRA2jLNuM
注：
如果系统参数需要放在POST体中，需要在URL中加入固定的参数及指定业务参数的key，URL示例如：
3.5.参数加密
对业务参数采用整体加密规则，使用AES256算法，调用sdk加密方法（sdk包见生成数字签名）进行加密，加密示例如下：
StringbusiParam="{\"REGION_ID\":
\"A\",\"CERT_TYPE\":
\"2\",\"CERT_NO\":
\"1234567\"}";
StringdataSecret="501e3f2e8bd3c8b0bad3e16b795dd85b";
StringencyptBusiParam=（busiParam,（dataSecret））;
注：
dataSecret为数据加密密钥，默认为应用密钥。
3.6.获取令牌
依据应用信息里的授权类型不同，分以下三种方式获取访问令牌：
3.6.1.授权码模式
适用于有服务端的应用（如web应用），分两步获取最终访问令牌：
调用授权接口：
请求参数：
参数名
必选
类型
说明
app_id
true
String
应用在开放平台注册时分配的应用标识
redirect_uri
true
String
与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。
response_type
true
String
响应类型，此处必须为”code”
响应参数：
参数名
必选
类型
说明
code
true
String
授权码，用于调用令牌接口获取最终的访问令牌
open_id
true
String
用户唯一标识，根据app_id及移动手机用户标识生成。
在不同的app_id下，同一个手机号生成的open_id也不一样
调用范例：
&redirect_uri=&response_type=code
成功应答：
&open_id=8911f179-bc87-4412-9712-24b4921f2c31
调用令牌接口：
请求参数：
参数名
必选
类型
说明
app_id
true
String
应用在开放平台注册时分配的应用标识
app_key
true
String
应用密钥，应用注册时平台分配。
grant_type
true
String
此处必须为”authorization_code”
code
true
String
授权码，调用授权接口获取。
redirect_uri
true
String
与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。
响应参数：
参数名
必选
类型
说明
access_token
true
String
获取到的访问令牌
expires_in
true
String
令牌有效期（以秒为单位）
refresh_token
false
String
刷新令牌，如果授权类型支持令牌刷新
调用范例：
&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.简化模式
适用于没有服务端的应用（如手机/桌面客户端程序），通过调用开放平台授权接口，一步获得最终的访问令牌，获取方式如下：
调用授权接口：
请求参数：
参数名
必选
类型
说明
app_id
true
String
应用在开放平台注册时分配的应用标识
app_key
true
String
应用注册时分配的应用密钥。
redirect_uri
true
String
与应用信息中的回调地址保持一致，用户授权后回调信息给应用时使用。
response_type
true
String
响应类型，此处必须为”token”
响应参数：
参数名
必选
类型
说明
access_token
true
String
获取到的访问令牌
expires_in
true
String
令牌有效期（以秒为单位）
open_id
true
String
用户唯一标识，根据app_id及移动手机用户标识生成。
在不同的app_id下，同一个手机号生成的open_id也不一样
调用示例：
&app_key=3ff70dd0b3e9d13264c57813&redirect_uri=&response_type=token
成功应答：
&token_type=bearer&open_id=8911f179-bc87-4412-9712-24b4921f2c31&expires_in=299
3.6.3.客户端信任模式
适用于无需用户登录授权的合作应用场合，应用凭自身的应用ID和应用密钥，通过调用令牌接口，直接获得无需用户授权的访问令牌。
调用令牌接口：
请求参数：
参数名
必选
类型
说明
app_id
true
String
应用在开放平台注册时分配的应用标识
app_key
true
String
应用注册时分配的应用密钥。
grant_type
true
String
响应类型，此处必须为”client_credentials”
响应参数：
参数名
必选
类型
说明
access_token
true
String
获取到的访问令牌
expires_in
true
String
令牌有效期（以秒为单位）
调用示例：
&app_key=3888bdf5eaf4355be982f&grant_type=client_credentials
成功应答：
{"access_token":
"fbf3315c-2715-49f5-8c0a-31b99dbf796e","token_type":
"bearer","expires_in":
86399}
3.7.生成数据签名
sign字段为报文数字签名，具体的做法是将系统参数包装成一个map，将业务报文转换成相应格式（json或xml）的字符串，然后调用sdk数字签名接口生成签名，调用示例如下:
MapsysParam=newHashMap（）;
（"method","CUST_QRY_CUST_INFO"）;
（"format","json"）;
（"timestamp","20"）;
（"appId","501300"）;
（"appKey","f575e386e80d4cb634c2e9ae0b7b541a"）;
（"version",""）;
（"accessToken","5801b0d7-013f-400e-bee8-59f7ac074880"）;
StringbusiParam=
"{\"REGION_ID\":
\"A\",\"CERT_TYPE\":
\"2\",\"CERT_NO\":
\"1234567\"}";
Stringkey="edf3def8681986d00cf19e654e2f9150";
Stringsign=（sysParam,busiParam,"HmacSHA256",key）;
文件列表:
3.8.能力参数返回
序号
参数命名
参数名称
长度
类型
是否必选
备注
返回参数
1
respCode
返回码
10
String
Y
00000代表成功，其他代表异常编码
2
respDesc
返回描述
1000
String
Y
3
result
返回值
200
String
Y
业务中心返回的内容
JSON返回报文参考：
{"respCode":
"00000","respDesc":
"调用成功".”result”：
{“BillId”.””.”ResDes”.”号码正确”}}
XML返回报文参考：
返回报文：
00000张三中国中国十四行事实上郑州1999-05-08 00:
00:
郑州市金水区英协路null0李斯调用成功!
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.接口类型
异步接口，回调接口规范见
4.1.1.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元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
订单流水
是
外围系统请求过来的唯一流水
SMS_TEMPLATE
短信模板
否
String
0：
集团公司模板
1：
个性化模板一
默认值为0
（叠加包还是默认的模板，不用选择。
）
范例：
{
"GBILL_ID":
""
"FLAG":
"",
"BILL_ID":
"",
"VALID_MONTH":
"",
"MEM_SRVPKG":
"",
"CUST_ORDER_ID":
"",
“SMS_TEMPLATE”:
”0”
}
4.1.1.6.响应参数
参数
说明
是否必选
参数类型
备注
respCode
返回结果代码
是
String
默认输出00000
respDesc
返回结果描述
是
String
默认输出success
返回结果
正常应答报文如下：
{
"respCode":
"00000",
"respDesc":
"success"
}
4.1.2.集团成员已订购流量查询
4.1.2.1.接口描述
查询成员已订购的流量。
4.1.2.2.能力编码
SO_MEMBER_DEAL_QUERY
4.1.2.3.请求方式
采用HTTPPOST方式。
4.1.2.4.接口类型
同步接口
4.1.2.5.请求参数
业务参数属性：
名称
参数名
类型
长度
是否必须
示例值
默认值
取值说明
手机号码
BILL_ID
String
V11
是
河南移动有效手机号码
范例：
{
"BILL_ID":
""
}
4.1.2.6.响应参数
参数
说明
是否必选
参数类型
备注
respCode
结果代码
必选
String
接口调用的返回码
00000：
成功，其他：
失败
respDesc
结果说明
必选
String
接口调用的返回消息描述。
result
返回结果
必选
MAP
Result对象属性
参数
说明
是否必选
参数类型
备注
SO_MEMBER_DEAL
结果集
必选
LIST
SO_MEMBER_DEAL对象中各节点的属性
名称
参数名
类型
长度
是否必须
示例值
默认值
取值说明
集团名称
GROUP_NAME
String
50
是
集团名称
操作名称
MEM_SRVPKG_DESC
String
50
是
成员资费包描述
生效日期
VALID_DATE
String
25
是
生效日期
失效日期
EXPIRE_DATE
String
25
是
失效日期
折扣
DISCOUNT
String
50
是
折扣
返回结果
正常应答报文如下：
{
"respCode":
"00000",
"respDesc":
"调用成功!
",
"result":
{
"SO_MEMBER_DEAL":
[
{
"DISCOUNT":
"70",
"EXPIRE_DATE":
"2015-09-3023:
59:
",
"GROUP_NAME":
"aaaaaa",
"MEM_SRVPKG_DESC":
"个人5元30M",
"VALID_DATE":
"2015-09-0618:
15:
"
},
{
"DISCOUNT":
"70",
"EXPIRE_DATE":
"2015-09-3023:
59:
",
"GROUP_NAME":
"bbbbb",
"MEM_SRVPKG_DESC":
"个人3元10M",
"VALID_DATE":
"2015-09-0616:
40:
"
}
]
}
}
4.1.3.成员处理情况查询
4.1.3.1.接口描述
根据外围渠道订单流水查询运营商订单处理情况。
4.1.3.2.能力编码
SO_MEMBER_RETURN_QUERY
4.1.3.3.请求方式
采用HTTPPOST方式。
4.1.3.4.接口类型
同步接口
4.1.3.5.请求参数
参数
说明
长度
是否必选
参数类型
加密字段
备注
CUST_ORDER_ID
流水
25
是
String
是
外围渠道给CRM侧流水
范例：
{
“CUST_ORDER_ID”:
””
}
4.1.3.6.响应参数
参数
说明
是否必选
参数类型
备注
respCode
结果代码
必选
String
接口调用的返回码
00000：
成功，其他：
失败
respDesc
结果说明
必选
String
接口调用的返回消息描述。
result
返回结果
必选
List
Result属性
参数
说明
是否必选
参数类型
备注
BILL_ID
手机号码
是
String
手机号码
MEM_SRVPKG_DESC
订购资费
是
String
成员资费包描述
VALID_DATE
生效日期
是
String
生效日期
STATE
处理结果
是
String
W正在受理M全网业务集团公司受理中Y处理成功N处理失败E反馈异常
DEAL_RESULT
处理结果
是
String
CRM侧处理结果
范例：
返回json格式：
{
"result":
{
“BILL_ID”:
””,
“MEM_SRVPKG_DESC”:
””,
"VALID_DATE":
"",
"STATE":
"",
"DEAL_RESULT":
""
},
"respCode":
"00000",
"respDesc":
"success"
}
集团帐户实时余额查询—新增接口
4．．1接口描述
集团帐户实时余额查询
4．．2能力编码
QRY_GRP_BALANCE
4．．3请求方式
采用HTTPPOST方式。
4．．4接口类型
同步接口
4．．5请求参数
参数
说明
长度
是否必选
参数类型
加密字段
备注
BILL_ID
集团计费号
11
是
String
是
集团计费号
范例：
{
“BILL_ID”:
””
}
4．．6响应参数
参数
说明
是否必选
参数类型
备注
respCode
结果代码
必选
String
接口调用的返回码
升级会员 