liuliang / api_docs

api说明文档.md 8.81 KB

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

老版文档传送门(提单方式为get请求)

文档说明：

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

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

提交方式:  POST 
参数格式:  JSON
URL: https://服务器域名/api/accounts/chargeSingleNumber
提醒: 生成sign所需的api_key(50位): 请合作方登陆商户后台,点击左侧 "我的信息" 中查看

接收参数：

参数 类型 必填 描述 范例
username string 是 用户账号 username
phone string 是 充值号码 13888888888
capacity string 是 流量包大小: (单位:MB) 10
sign string 是 按此顺序拼接相应的字符串与值，并用标准的SHA1加密(40位小写):
SHA1("api_key=" + api_key + "&capacity=" + capacity + "&phone=" + phone + "&username=" + username)		 8814988657f8bc805e951bc46b0862bf90555b01
timestamp string 是 请求时间戳:
14位,格式: yyyyMMddHHmmss		 20160113133256
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 
json示例：
{ "username":    "11111",
  "phone":       "13888888888",
  "capacity":    "10",
  "sign":        "5e646367ae318627685f98aa2a6c13576f8e964c",
  "area":        "0", 
  "notify_url":  "http://www.buyaodianwo2333.com", 
  "timestamp":   "20160113133256" }

curl调用示例：

curl -d '{"area": "0", notify_url: "http://www.buyaodianwo2333.com", "timestamp":"20160113133256" "username": "11111", "phone": "13888888888", "capacity": "10", "sign": "5e646367ae318627685f98aa2a6c13576f8e964c"}' 'https://服务器域名/api/accounts/chargeSingleNumber' -H Content-Type:application/json -v

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

参数 类型 必填 描述 范例
success int 是 接口调用是否成功:
1: 调用成功
0: 调用失败		 1
message string 是 提示信息 充值请求提交成功！
group int 否 这次充值请求的批次号(13位) 1474866902069
code int 否 错误码 详见文档末详情见下文【五、错误码】 301
partner_order_no string 否 合作方订单唯一标识 2016011313325615104 
json示例：
{ "success":          1, 
  "message":          "充值请求提交成功!", 
  "group":            1474866902069,
  "partner_order_no": "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 
json示例: 
{ "phone":            13888888888, 
  "result":           1, 
  "group":            1474866902069,
  "remark":           "充值成功",
  "partner_order_no": "2016011313325615104" }

三、 按订单号查询单个订单状态(合作方主动查询,在无法接受回调时可使用)

特别说明： 只返回单条订单的充值状态。
提交方式： POST 
URL: https://服务器域名/api/accounts/querySingleOrder

接收参数:

参数 类型 必填 描述 范例
username string 是 用户账号 username
phone string 是 充值记录的手机号 13888888888
partner_order_no string 是 充值记录的合作方订单号 asdasdasdasd
sign string 是 按此顺序拼接相应的字符串与值，并用标准的SHA1加密(40位小写):SHA1("api_key=" + api_key + "&username=" + username) 8814988657f8bc805e951bc46b0862bf90555b01

调用示例：

curl -d '{"partner_order_no": "asdasdasdasd", "username": "12345678900", "phone": "13888888888", "sign": "8814988657f8bc805e951bc46b0862bf90555b01"}' 'https://服务器域名/api/accounts/querySingleOrder' -H Content-Type:application/json -v

同步响应参数说明:

参数 类型 必填 描述 范例
success int 是 接口调用是否成功 1
result int 是 1: 充值成功
0: 充值失败
2:正在充值		 1
phone string 是 充值记录的手机号 13888888888
partner string 是 充值记录的合作方订单号 asdasdasdasd
message string 是 描述 充值成功 
json示例：
{ "success":          1, 
  "result":           1, 
  "phone":            "13888888888",
  "message":          "充值成功",
  "partner_order_no": "asdasdasdasdasd" }

四、 加密方法

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

# 以“为单个号码充流量接口”为例
# 在调用该接口时,sign的加密需要[api_key, capacity, phone, username]四个参数。api_key在合作方登陆商户后台,点击左侧 "我的信息" 中查看

# Talk is cheap, here is code:

# 变量赋值
api_key = "asdasdasdasdasdasdasdasdasdasd..."
capacity = "10"
phone = "13888888888"
username = "your_username"

# 用标准的SHA1加密生成sign, 注意后方字符串拼接顺序不可变
sign = SHA1("api_key=" + api_key + "&capacity=" + capacity + "&phone=" + phone  + "&username=" + username)

# 特别提示:不同方法sign所需的加密参数不同,详见该方法中对sign的描述

五、 错误码

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