api说明文档.md
15.8 KB
51流量充值平台对外接口说明文档 V3.6
文档说明：
服务器： 新版接口使用https接口，老版的http接口也支持, https和http的接口服务器地址不同，具体咨询对接技术人员;
参数描述： # 后面为注释内容;
示例说明： 本文档接口调用示例采用Linux下的curl命令发起http请求;
返回参数说明： 本文档所有接口返回的数据一律为json格式数据; 分为调用成功返回和调用失败返回两种格式。一、 使用商户余额充流量接口（可接受批量号码和单个号码）
提交方式： GET
URL: https://服务器域名/api/accounts/chargeBatchNumbers
接收参数：
{
"username" : "username", # 用户账号（必填）
"password" : "password", # 用户密码（必填，由我方提供，密码是通过标准的SHA1加密（40位小写）
"phone" : "13888888888|15555555555", # 充值号码，多个号码用英文竖线(|)隔开(一次最多100个号码,号码不可重复)，单个号码不用分隔（必填）
"cmCapacity": "10", # 移动流量包大小 单位为MB (若待充值号码中没有对应运营商则赋空值。)
"cuCapacity": "20", # 联通流量包大小 单位为MB (若待充值号码中没有对应运营商则赋空值。)
"ctCapacity": "", # 电信流量包大小 单位为MB (若待充值号码中没有对应运营商则赋空值。)
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用示例：
curl 'https://服务器域名/api/accounts/chargeBatchNumbers?username=11111&password=7b21848ac9af35be0ddb2d6b9fc3851934db8420&phone=13888888888|15555555555&cmCapacity=10&cuCapacity=20×tamp=2160113133256&sign=7da67f8b9627d1783ef00311125ad246a4eed329' -H Content-Type:application/json -v
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
"message": "充值请求提交成功！", # 提示信息
"group" : 12 # 这次充值请求的批次号。如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 请根据group和手机号码 2个条件判断更新充值状态。同一个group不会有相同的手机号码
"gruop" : 12 # 拼写错误,已废弃,与group结果相同
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 301, # 错误码 详见文档末详情见下文【八、错误码】
"reason" : "商户余额不足,无法充值" # 具体的失败原因描述,（如果是手机号码格式不正确，reason会返回具体的错误的号码用逗号分隔）
}二、 查询充值状态（按数量）
特别说明： 通过该方法查询的充值状态只可获取一次，记录在被查询过后就会被删除！
提交方式： GET
URL: https://服务器域名/api/accounts/querySeveralConsumptions
接收参数：
{
"username" : "username", # 用户账号（必填）
"password" : "password", # 用户密码（必填，由我方提供，密码是通过标准的SHA1加密（40位小写）
"count" : 5, # 查询充值记录的数量(大于0小于500)
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用示例：
curl 'https://服务器域名/api/accounts/querySeveralConsumptions?username=12345678900&password=7c222fb2927d828af22f592134e8932480637c0d&count=50×tamp=2160113133256&sign=7d0ddc3d2de92eb5e49a8efa10fe1d0e67290220' -H Content-Type:application/json -v
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
records:[
{
group: 1, # 充值记录批次号
# 【注意】 如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 请根据group和手机号码 2个条件判断更新充值状态。同一个group不会有相同的手机号码
result: 1, # 1-充值成功，0-充值失败
phone: "13555554556" # 充值手机号码
},
{
group: 2, # 充值记录批次号
# 【注意】 如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 请根据group和手机号码 2个条件判断更新充值状态。同一个group不会有相同的手机号码
result: 0, # 1-充值成功，0-充值失败
phone: "15644334456" # 充值手机号码
},
]
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 401, # 错误码 详情见下文【八、错误码】
"reason" : "该商户不存在此条记录" # 具体的失败原因描述
}三、 查询充值状态（按指定group）
特别说明： 通过该方法查询的充值状态获取无限制，记录永远存在！
提交方式： GET
URL: https://服务器域名/api/accounts/queryByGroup
接收参数：
{
"username" : "username", # 用户账号（必填）
"password" : "password", # 用户密码（必填，由我方提供，密码是通过标准的SHA1加密（40位小写）
"group" : 5252, # 提交充值请求后返回的的group值
# 【注意】 如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 请根据group和手机号码 2个条件判断更新充值状态。同一个group不会有相同的手机号码
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用示例：
curl 'https://服务器域名/api/accounts/queryByGroup?username=12345678900&password=7c222fb2927d828af22f592134e8932480637c0d&group=5252×tamp=2160113133256&sign=7d0ddc3d2de92eb5e49a8efa10fe1d0e67290220' -H Content-Type:application/json -v
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
records:[
{
group: 5252, # 充值记录批次号
result: 1, # 1: 充值成功，0: 充值失败，-1: 充值中
phone: "13555554556" # 充值手机号码
},
{
group: 5252, # 充值记录批次号
result: 0, # 1: 充值成功，0: 充值失败，-1: 充值中
phone: "15644334457" # 充值手机号码
},
{
group: 5252, # 充值记录批次号
result: -1, # 1: 充值成功，0: 充值失败，-1: 充值中
phone: "15644334458" # 充值手机号码
},
]
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 401, # 错误码 详情见下文【八、错误码】
"reason" : "该商户不存在此条记录" # 具体的失败原因描述
}四、 通过卡密查询流量充值卡具体信息
提交方式： GET
URL: https://服务器域名/api/cards/queryPassword
接收参数：
{
"password" : "2g8myv", #卡密内容（必填）
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用示例：
curl 'https://服务器域名/api/cards/queryPassword?password=47u4s5×tamp=20160113133256&sign=8814988657f8bc805e951bc46b0862bf90555b01' -H Content-Type:application/json -v
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
"data": {
"card_id": 100001, # 卡号
"state": 0, # 0: 该卡可用；1: 该卡正在充值；2: 该卡已被使用；3: 该卡已过期；
"price": 3, # 单位 元
"cm_capacity": 10, # 可充移动流量包大小
"cu_capacity": 20, # 可充联通流量包大小
"ct_capacity": 10, # 可充电信流量包大小
"expire_date": "2015-10-16", # 卡过期日
"password": "abcdef" # 卡密
}
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 101, # 错误码 详见文档末
"reason" : "不存在的卡" # 具体的失败原因描述详情见下文【八、错误码】
}五、 通过卡密充值流量接口
提交方式： GET
URL: https://服务器域名/api/cards/charging
接收参数：
{
"password" : "2g8myv", # 卡密内容（必填）
"phone" : "15061975627", # 手机号码(必填)
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用示例：
curl 'https://服务器域名/api/cards/charging?timestamp=20160113133256&password=47u4s5&phone=15534433433&sign=1a68355541530b09030dc4107a25bbadbd4f3cc0' -H Content-Type:application/json -v
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
"group" : 12 # 这次充值请求的批次号。如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 查询是请根据group和手机号码 2个条件判断。同一个group不会有相同的手机号码
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 101, # 错误码 详见文档末
"reason" : "不存在的卡" # 具体的失败原因描述详情见下文【八、错误码】
}六、 使用商户余额充流量接口（单个号码充值）（已过时，不推荐使用）
提交方式： GET
URL: https://服务器域名/api/accounts/chargeSingleNumer
接收参数：
{
"username" : "username", # 用户账号（必填）
"password" : "password", # 用户密码（必填，由我方提供，密码是通过标准的SHA1加密（40位小写）
"capacity" : 150, # 流量包大小（必填）
"phone" : "15061975627", # 手机号（必填）
"timestamp" : "20160113133256", # 请求时间戳(必填，14位)
"sign" : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【七、加密方法】)
}
调用成功返回json数据：
{
"success": 1, # 1: 接口调用成功，
"message": "充值请求提交成功！", # 提示信息
"group" : 12 # 这次充值请求的批次号。如果同一商户两次请求时间非常接近，
# 系统会默认合并为一次请求，则这两次提交的到的group是相同的，
# 请根据group和手机号码 2个条件判断更新充值状态。同一个group不会有相同的手机号码
}
调用失败返回json数据：
{
"success": 0, # 0: 接口调用失败，
"code" : 301, # 错误码 详见文档末
"reason" : "商户余额不足,无法充值" # 具体的失败原因描述详情见下文【八、错误码】
}七、 加密方法
1. 组合加密字符串
将参数值按照顺序进行连接，以英文逗号(,)分隔，并去掉为空的参数
如：如果要传递的数据为
username=aaaaa&password=7b21848ac9af35be0ddb2d6b9fc3851934db8420&phone=15939393939|13878787878&cmCapacity=10&cuCapacity=20&ctCapacity=timestamp=20160223120445
（若有password,在组合前，参数password的值必须是SHA1加密的），
则组合后的加密字符串为：
aaaaa,7b21848ac9af35be0ddb2d6b9fc3851934db8420,15939393939|13878787878,10,20,20160223120445
2. 加密组合后的字符串
按照标准的SHA1（40位小写）加密方式对组合后的字符串进行加密。加密结果如：加密前为：
aaaaa,7b21848ac9af35be0ddb2d6b9fc3851934db8420,15939393939|13878787878,10,20,20160223120445
加密后为：
82427b3f7823d45d4a253c7d31afe472251b2036
加密方法的Ruby语言 Demo
# 加密方法的Ruby语言 Demo
# params = {
# username: aaaaa
# password: 7b21848ac9af35be0ddb2d6b9fc3851934db8420
# phone: 15939393939|13878787878
# cmCapacity: 10
# cuCapacity: 20
# ctCapacity: ""
# timestamp: 20160223120445
# }
def get_sign(params)
# 将参数值按照顺序进行连接，以英文逗号(,)分隔，并去掉为空的参数
result = params.each.inject([]){ |arr, p| p[1].blank? ? arr : arr << p[1] }
# 我这里把参数放到一个数组里，非必须
# result = [aaaaa,7b21848ac9af35be0ddb2d6b9fc3851934db8420,15939393939|13878787878,10,20,20160223120445]
# 将数组按逗号分隔拼接成字符串，并按照标准的SHA1(40位小写)加密方式，对组合后的字符串进行加密
Digest::SHA1.hexdigest(result.join(','))
# 得到加密后的结果为：82427b3f7823d45d4a253c7d31afe472251b2036
end八、 错误码
101: 不存在的卡
102: 该卡兑换中
103: 该卡已过期
104: 该卡已被使用
105: 五十元卡密不支持中国联通号码
201: 手机号码不正确!
202: 必须要有手机号
301: 商户余额不足,无法充值
302: 该商户不存在
303: 该商户被禁用
401: 该商户不存在此条记录
501: 上级代理商余额不足
601: 号码与流量包不匹配、
602: 该运营商充值渠道暂时关闭
603: 该省充值渠道暂时关闭
604: 该运营商不提供此流量包
605: 缺少号码所需的流量包
606: 参数格式有误
607: 未知错误