liuliang / api_docs

老版api文档.md 10.4 KB

51流量充值平台对外接口说明文档 V3.6

文档说明：

服务器： 地址具体咨询对接技术人员;  
参数描述： # 后面为注释内容; 
示例说明： 本文档接口调用示例采用Linux下的curl命令发起http请求;
返回参数说明： 本文档所有接口返回的数据一律为json格式数据;

一、 使用商户余额充流量接口（单个号码充值）

提交方式： GET

URL: https://服务器域名/api/accounts/chargeSingleNumber

接收参数：

参数 类型 必填 描述 范例
username string 是 用户账号 username
phone string 是 充值号码 13888888888
timestamp string 是 请求时间戳:
14位,格式: yyyyMMddHHmmss		 20160113133256
sign string 是 按照规则加密后的密文:
加密详情见下文【四、加密方法】		 8814988657f8bc805e951bc46b0862bf90555b01
capacity string 是 流量包大小: (单位:MB) 10
area string 是 流量范围:
0 : 全国包
1 : 省漫游包
2 : 省内包		 0
partner_order_no string 否 合作方订单唯一标识: 若提交,在推送中会带有partner_order_no信息 2016011313325615104
notify_url string 否 回调推送地址 http://www.buyaodianwo2333.com
available_length string 否 流量有效时长:
单位:小时。超过24小时的, 系统会换算成24的倍数。如: 传16表示效时长是16小时, 传24表示有效时长是24小时, 传25依然表示有效时长为24小时, 传55表示有效时长为48小时。
如果产品是以“天”为计量的, 请换算成小时。如: “10天”请传入240。
(不传默认当月有效)		 720
clear_type string 否 流量清零方式:
0: 零点清零
1: 按照流量有效时长清零
(不传默认零点清零) 		0
submit_area string 否 提交区域:
0: 全国范围
1: 省范围
2: 市范围
(不传根据area自动寻找范围,若要使用市包,请传2) 		1

调用示例：

curl 'https://服务器域名/api/accounts/chargeSingleNumber?area=0&username=11111&phone=13888888888&capacity=10&notify_url=http://www.buyaodianwo2333.com&timestamp=20160113133256&sign=7da67f8b9627d1783ef00311125ad246a4eed329' -H Content-Type:application/json -v

调用成功返回json数据,同步响应参数说明:

参数 类型 必填 描述 范例
success int 是 接口调用是否成功:
1: 调用成功
0: 调用失败		 1
message string 否 提示信息 充值请求提交成功！
group int 否 这次充值请求的批次号(13位) 1474866902069
code int 否 错误码 详见文档末详情见下文【五、错误码】 301
reason string 否 具体的失败原因描述 商户余额不足,无法充值
partner_order_no string 否 合作方订单唯一标识 2016011313325615104

二、 结果通知(接收回调,接口方推送)

特别说明：每条结果会默认推送5次，间隔为两分钟，合作方得到结果响应大写字符串"OK"，则停止该条结果推送。 结果通知与结果查询只要选择一种方式，建议合作方使用接收回调的方法。
推送地址: 由合作方提供。1: 可在发送订购请求中携带notify_url参数来声明。2: 在商户后台网页,点击"我的信息"=>"回调地址", 添加回调地址。(选择一种方式即可)
推送方式： POST 
参数格式: json

推送参数：

参数 类型 必填 描述 范例
phone int 是 充值号码 13888888888
group int 是 这次充值请求的批次号(13位) 1474866902069
result int 是 1: 充值成功
0: 充值失败		 1
remark string 是 结果描述 充值成功
partner_order_no string 否 合作方订单唯一标识 2016011313325615104

三、 按固定数量结果查询(合作方主动查询,不建议使用,后期可能会被关闭)

特别说明： 通过该方法查询的充值状态只可获取一次，记录在被查询过后就会被删除！结果通知与结果查询只要选择一种方式，建议合作方使用接收回调的方法。
提交方式： GET 
URL: https://服务器域名/api/accounts/querySeveralConsumptions

接收参数:

参数 类型 必填 描述 范例
username string 是 用户账号 username
count string 是 查询充值记录的数量(数量可自定义) 50
timestamp string 是 请求时间戳:
14位,格式: yyyyMMddHHmmss		 20160113133256
sign string 是 按照规则加密后的密文:
加密详情见下文【四、加密方法】		 8814988657f8bc805e951bc46b0862bf90555b01

调用示例：

curl 'https://服务器域名/api/accounts/querySeveralConsumptions?username=username&count=50&timestamp=20160113133256&sign=7d0ddc3d2de92eb5e49a8efa10fe1d0e67290220' -H Content-Type:application/json -v

同步响应参数说明:

参数 类型 必填 描述 范例
success int 是 接口调用是否成功 1
records array 是 充值记录(详见下方充值记录参数) [{group: 1474866902069, result: 1, phone: "13555554556"}]
code int 否 错误码 详见文档末详情见下文【五、错误码】 401
reason string 否 具体的失败原因描述 该商户不存在此条记录

充值记录参数

参数 类型 必填 描述 范例
phone int 是 充值号码 13888888888
group int 是 充值记录批次号,请根据group和手机号码 2个条件判断更新充值状态 1474866902069
result int 是 1: 充值成功
0: 充值失败		 1

四、 加密方法

所谓加密就是生成sign参数。

# 以“为单个号码充流量接口”为例，假定你想发送这样的请求内容:
# ../chargeSingleNumber?area=0&capacity=10&clear_type=0&partner_order_no=b7aa1b4e3bf04225b3e897c8a7860b11&phone=13812700845&timestamp=20161130140634&username=17714052511
# 上面的URL是完全正确的写法, 但少了"sign"参数, 本方法就是用于生成"sign"参数的。在完成"sign"值的生成后，把"sign"值拼接到URL最后, 如 "...&sign=0ee45942d184a11e64c62bec00cfc4c0bb855ad2"
# 上述URL参数转成Hash后, 如:
# {
#   area: "0",
#   capacity: "10",
#   clear_type: "0",
#   partner_order_no: "b7aa1b4e3bf04225b3e897c8a7860b11",
#   phone: "13812700845",
#   timestamp: "20161130140634",
#   username: "17714052511"
# }
# STEP 1、这里有两点要注意
# 1、如果某个参数你想用我方的默认值，比如"clear_type"我方的默认值是"0"，那么请把"clear_type"从请求参数中去掉，就是说"../chargeSingleNumber?area=0&capacity=10&clear_type=&partner_order_no=b7aa1b4e3bf04225b3e897c8a7860b11....", 这样的请求是不好的, 因为"clear_type="没有赋值。
# 2、参数按参数名的字母顺序排序(非必须)。如上例中"area"排在"capacity"前面，因为"a"在"c"的前面。虽然我方接口程序可以处理不按参数字母顺序排列的参数请求，不过因为你使用的发送请求的第三方包可能对您发到我方的参数顺序作了自动排列了，所以建议您请求参数顺序以参数名的字母先后排序。
#
# 下面的例子是用Ruby语言写的，而我猜您是一名Java工程师。这没有关系，请您仔细阅读下面的代码，并把下面的例子逐行转成Java就可以了。
#
# STEP 2、本方法的入参params_array是一个数组，存放的是参数值。
#   [area, capacity, clear_type, partner_order_no, phone, timestamp, username] 对应的params_array值如:
#   ["0", "10", "0", "b7aa1b4e3bf04225b3e897c8a7860b11", "13812700845", "20161130140634", "17714052511"]
def generate_sign(params_array)
  # STEP 3、把“你的密码”用SHA1加密并放在数组的最后，如: ["0", "10", "0", "b7aa1b4e3bf04225b3e897c8a7860b11", "13812700845", "20161130140634", "17714052511", "7e6ff36ae115681fcbfc110dc2195e2b7557a483"]
  params_array = (params_array << Digest::SHA1.hexdigest(your_password))
  logger.info(params_array) # 这里请打印日志，方便排查问题。在调试成功后再把日志去掉。

  # STEP 4、把数组值拼接成字符串，用英文逗号(,)分隔，如: "0,10,0,b7aa1b4e3bf04225b3e897c8a7860b11,13812700845,20161130140634,17714052511,7e6ff36ae115681fcbfc110dc2195e2b7557a483"。这里所有的参数值都应该有值，不应该出现空字符串值的情况。
  params_string = params_array.join(',')
  logger.info(params_string) # 打印日志，原因同上

  # STEP 5、用SHA1加密上一步生成的字符串，并作为结果返回，如: 0ee45942d184a11e64c62bec00cfc4c0bb855ad2
  sign = Digest::SHA1.hexdigest(params_string)
  logger.info(sign) # 打印日志，原因同上
  return sign
end

五、 错误码

错误码 说明
201 手机号码不正确!
202 必须要有手机号
301 商户余额不足,无法充值
302 该商户不存在
303 该商户被禁用
305 无该省份充值权限
306 未使用授权ip
307 不存在或不拥有该套餐充值权限,请检查流量包
308 该接口不支持代理商子级商户
309 商户尚未开通该产品
310 折扣尚未确认
311 订单号重复
401 该商户不存在此条记录
501 上级代理商余额不足
601 号码与流量包不匹配
602 该运营商充值渠道暂时关闭
603 该省充值渠道暂时关闭
604 该运营商不提供此流量包
605 缺少号码所需的流量包
606 sign验证失败
608 该方法已关闭
607 未知错误
701 该商品尚未激活
702 该商品维护中