硕汉宽固业务查询接口
协议版本号
|
序号
|
协议变更内容
|
协议版本号
|
版本日期
|
更新人
|
|
1
|
制定硕汉业务接口协议1.0版本
|
1.0
|
2015.4.16
|
江龙
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1接口设计
1.1接口调用方式
1.1.1通信协议
Http协议、GET方式
1.1.2调用参数
分为系统参数和业务参数
1.1.2.1 系统参数
|
名称
|
类型
|
是否必须
|
描述
|
|
method
|
string
|
Y
|
API接口名称 queryUserInfo
|
|
timestamp
|
string
|
Y
|
时间戳，格式为yyyyMMddHHmmssSSS，例如：20130506135203528。
|
|
format
|
string
|
N
|
可选，指定响应格式。默认json，目前可选值：json
|
|
seller_id
|
string
|
Y
|
用户名
|
|
v
|
string
|
N
|
API协议版本，默认1.0，目前可选值:1.0
|
|
sign
|
string
|
Y
|
对 API 输入参数进行签名
|
|
sign_method
|
string
|
N
|
参数的签名方法选择，默认MD5，目前可选值是：MD5
|
1.1.2.2 业务参数
所有的业务参数采用json格式，整个json串采用名称biz_paras进行标示。
业务参数由于不同 API 各自不同，这里举例说明，更多请参考具体的业务API章节。
|
名称
|
参数名
|
类型
|
是否必须
|
示例值
|
默认值
|
取值说明
|
|
手机号码
|
phoneNo
|
String
|
是
|
13800001111
|
|
|
最终的业务参数json串为：
biz_paras={" phoneNo ":"13800001111"}
1.1.3 签名sign
1.1.3.1签名算法：MD 5
调用API 时需要对请求参数进行签名，服务器端需要会对该请求参数进行验证是否合法的，API提供方需为硕汉提供签名需要的secret密钥串，如：12jjse83jd93hf20sjfos93bk29
1.1.3.2 签名内容
- sign参数不参与签名
- 将其他所有系统参数和biz_paras按照参数名称字符升序排列，排序后，所有参数以&连接起来，最后再拼接上secret密钥串，则得到待签名的字符串
- 使用MD5算法进行签名，签名得到的byte[]以十六进制Hex转为字符串，然后赋给sign参数
- 签名使用utf-8字符集编码
- phoneNo ":"13800001111"}&format=json&method=queryUserInfo
- 12jjse83jd93hf20sjfos93bk29（密钥）
1.1.4完整的http请求
假定签名后得到的签名值为5364C12B837RE89D256DB2A301A3E，则完整的http请求url为：
http://ip:port/…?sign=5364C12B837RE89D256DB2A301A3E ×tamp=20150309135203528&v=1.0&sell_id=12345678&method= queryUserInfo&format=json& biz_paras={" phoneNo":"13800001111"}&sign_method= MD5
注意：传递的参数值需要采用utf-8进行编码
1.1.5应答报文
Json格式，最外层节点为result，里面包含三个子节点： code（经转换后硕汉所需的结果码），desc(结果描述，格式为：API提供方内部的具体结果码#具体结果描述)、bizResp（具体的业务结果）
示例如下：
{
"result": {
"code": "",//本接口协议定义的错误编码，API提供方需要将内部编码进行
"desc": "",//格式要求：API提供方内部错误编码#内部错误的详细说明
"bizResp": {
"业务结果": "参照具体的api说明"
}
},
"sign": "对result节点的签名"//待签名串的字符串为result={"code": "","desc": "","bizResp": {"业务结果": "参照具体的api说明"}}12jjse83jd93hf20sjfos93bk29（密钥）
}
1.2接口列表
1.2.1余额查询
用于查询手机号码的余额、流量、分钟数信息
queryBalance
|
名称
|
参数名
|
类型
|
是否必须
|
示例值
|
默认值
|
取值说明
|
|
手机号码
|
phoneNo
|
String
|
是
|
|
|
|
|
业务编码
|
busiCode
|
String
|
是
|
10000表示查余额
11000
表示查余额和流量剩余总量，以此类推
|
|
6位标志位串码：第一位标识查余额，
第二位表示查流量剩余总量，
第三位表示查流量剩余明细，
第四位表示查剩余分钟数，
第5，6位备用
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
名称
|
参数名
|
类型
|
是否必须
|
取值说明
|
|
用户余额
|
accountBalance
|
String
|
否
|
以“元”为单位
|
|
用户流量剩余总额
|
flowBalance
|
String
|
否
|
以“KB”为单位
|
|
用户流量明细
|
flowDetail
|
Array
|
否
|
详见参数描述“用户流量明细”
|
|
用户剩余通话分钟数
|
minuteBalance
|
String
|
否
|
以“分钟”为单位
|
|
|
|
|
|
|
用户流量明细结构描述
|
名称
|
参数名
|
类型
|
是否必须
|
取值说明
|
|
资源类型
|
resType
|
String
|
否
|
5位标志位串码：
第一位表示本地或全国流量(0,1)，
第二位表示3G流量或4G流量或通用流量(0,1,2)
第三位表示闲时流量或非闲时流量
第4，5位备用
|
|
资源总量
|
totalFlow
|
String
|
否
|
以（KB）为单位
|
|
资源已使用量
|
usedFlow
|
String
|
否
|
以（KB）为单位
|
|
资源剩余量
|
flowBalance
|
String
|
否
|
以（KB）为单位
|
2附录
2.1结果码和结果描述（沿用之前已定义的结果码，新增可补充）
|
结果码
|
结果描述
|
|
0000
|
交易成功
|
|
0001
|
幂等结果码
此次请求是上一次的重复请求，且上一次处理结果返回0000，例子：
场景1：
第一次的请求服务方收到，且处理结果为0000，但调用方没有收到，调用方第二次重新发送请求时，服务方返回0001。
场景2：
第一次的请求服务方收到，且处理失败返回错误码1001，但调用方没有收到，调用方第二次重新发送请求时，服务方返回对应的错误编码1001。
|
|
0002
|
系统其他未知异常
|
|
0003
|
业务处理结果未明确，需重试
|
|
|
|
|
1001
|
订单不存在
|
|
1002
|
订单状态非法
|
|
1003
|
订单交易推进失败
|
|
1004
|
-交易已关闭，用户已退款
|
|
|
|
|
2001
|
宽带账号不存在
|
|
2002
|
当前宽带账号欠费
|
|
2003
|
。。。。。。（待补充）
|
2.2接口枚举编码及含义
所有的编码统一采用的标准定义编码
2.2.1待补充
