api说明文档.md
11.9 KB
51流量充值平台对外接口说明文档 V4.2
- 文档说明：
-
服务器域名: 地址具体咨询对接技术人员;
- 参数描述: # 后面为注释内容;
- 示例说明: 本文档接口调用示例采用Linux下的curl命令发起http请求;
- 请求参数设置 Content-Type:application/json;
- 返回参数说明: 本文档所有接口返回的数据一律为json格式数据;
- api_key: 生成sign所需的api_key(50位): 请合作方登陆商户后台,点击左侧 "我的信息" 中查看;
-
服务器域名: 地址具体咨询对接技术人员;
接口目录
一、 使用商户余额充流量接口（单个号码充值）
- 提交方式: POST
- 参数格式: JSON
-
URL:
https://服务器域名/api/accounts/chargeSingleNumber
接收参数：
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| 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",
"area": "0",
"notify_url": "http://www.buyaodianwo2333.com",
"timestamp": "20160113133256",
"partner_order_no": "2016011313325615104",
"sign": "5e646367ae318627685f98aa2a6c13576f8e964c" }curl调用示例：
curl -d '{"username": "11111", "phone": "13888888888", "capacity": "10","area": "0", notify_url: "http://www.buyaodianwo2333.com", "timestamp":"20160113133256", "partner_order_no": "2016011313325615104","sign": "5e646367ae318627685f98aa2a6c13576f8e964c"}' 'https://服务器域名/api/accounts/chargeSingleNumber' -H Content-Type:application/json -v调用成功返回json数据,同步响应参数说明:
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| success | int | 是 |
充值请求否处理: 1: 调用成功，已处理 0: 调用失败,未处理 |
1 |
| message | string | 是 | 提示信息 | 充值请求提交成功！ |
| group | int | 否 | 这次充值请求的批次号(15位,不唯一) | 147486690206934 |
| code | int | 否 | 错误码(只在调用失败时返回) 详见文档末详情见下文【六、错误码】 | 301 |
| partner_order_no | string | 否 | 合作方订单唯一标识 | 2016011313325615104 |
返回json示例：
{ "success": 1,
"message": "充值请求提交成功!",
"group": 1474866902069,
"partner_order_no": "2016011313325615104" }二、 结果通知(接收回调,接口方推送)
- 特别说明: 每条结果会默认推送5次，间隔为两分钟，合作方得到结果响应大写字符串"OK"，则停止该条结果推送。 结果通知与结果查询只要选择一种方式，建议合作方使用接收回调的方法。
- 推送地址: 由合作方提供。可在发送订购请求中携带notify_url参数来声明
- 通知方式: POST
- 参数格式: JSON
- 编码格式: UTF-8
推送参数：
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| phone | int | 是 | 充值号码 | 13888888888 |
| group | int | 是 | 这次充值请求的批次号(若将此作为订单号,请结合号码查找订单) | 147486690206934 |
| result | int | 是 | 1: 充值成功 0: 充值失败 |
1 |
| remark | string | 否 | 结果描述 | 充值成功 |
| partner_order_no | string | 否 | 合作方订单唯一标识 | 2016011313325615104 |
json示例：
{ "phone": 13888888888,
"result": 1,
"group": 1474866902069,
"remark": "充值成功",
"partner_order_no": "2016011313325615104" }三、 按订单号查询单个订单状态(合作方主动查询,在无法接受回调时可使用)
- 特别说明: 只返回单条订单的充值状态,相同订单的查询频率不可小于60秒
-
URL:
https://服务器域名/api/accounts/querySingleOrder - 提交方式: POST
- 提交参数格式: JSON
- 返回参数格式: JSON
- 返回参数编码: UTF-8
接收参数:
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| username | string | 是 | 用户账号 | username |
| phone | string | 是 | 充值记录的手机号 | 13888888888 |
| partner_order_no | string | 是 | 充值记录的合作方订单号 | asdasdasdasd |
| sign | string | 是 |
签名: 按此顺序拼接相应的字符串与值，并用标准的SHA1加密(40位小写): SHA1("api_key=" + api_key + "&username=" + username) |
8814988657f8bc805e951bc46b0862bf90555b01 |
调用json示例：
{ "username": "username",
"phone": "13888888888",
"sign": "8814988657f8bc805e951bc46b0862bf90555b01",
"partner_order_no": "asdasdasdasdasd" }curl调用示例：
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: 调用成功(不代表充值成功) 0:调用失败(不代表充值失败) |
1 |
| result | int | 否 |
订单结果状态,仅在调用成功时出现。 1: 充值成功 0: 充值失败 2: 正在充值 |
1 |
| phone | string | 是 | 充值记录的手机号 | 13888888888 |
| partner | string | 是 | 充值记录的合作方订单号 | asdasdasdasd |
| message | string | 是 | 描述 | 充值成功 |
| code | int | 否 | 错误码 详见文档末详情见下文【六、错误码】 | 606 |
返回json示例：
{ "success": 1,
"result": 1,
"phone": "13888888888",
"message": "充值成功",
"partner_order_no": "asdasdasdasdasd" }四、 商户余额查询
- 说明: 返回商户当前的余额。
-
URL:
https://服务器域名/api/accounts/getBalance - 提交方式: POST
- 参数格式: JSON
接收参数:
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| username | string | 是 | 用户账号 | username |
| sign | string | 是 |
签名: 按此顺序拼接相应的字符串与值，并用标准的SHA1加密(40位小写): SHA1("api_key=" + api_key + "&username=" + username) |
8814988657f8bc805e951bc46b0862bf90555b01 |
调用json示例：
{ "username": "username",
"sign": "8814988657f8bc805e951bc46b0862bf90555b01"}curl调用示例：
curl -d '{"username": "your_username", "sign": "8814988657f8bc805e951bc46b0862bf90555b01"}' 'https://服务器域名/api/accounts/getBalance' -H Content-Type:application/json -v同步响应参数说明:
| 参数 | 类型 | 必填 | 描述 | 范例 |
|---|---|---|---|---|
| success | int | 是 | 接口调用是否成功 | 1 |
| company_name | string | 是 | 商户名称 | 51流量 |
| balance | float | 是 | 余额 | 2333.33 |
| message | string | 是 | 提示信息 | 余额查询成功! |
| code | int | 否 | 错误码 详见文档末详情见下文【六、错误码】 | 606 |
返回json示例：
{ "success":1,
"company_name":"51流量",
"balance":2333.33 }五、 加密方法
所谓加密就是生成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 | 找不到该订单 |
| 403 | 查询订单号不可为空! |
| 405 | 相同订单查询频率需小于60秒! |
| 501 | 上级代理商余额不足 |
| 601 | 号码与流量包不匹配 |
| 602 | 该运营商充值渠道暂时关闭 |
| 603 | 该省充值渠道暂时关闭 |
| 604 | 该运营商不提供此流量包 |
| 605 | 缺少号码所需的流量包 |
| 606 | sign验证失败 |
| 608 | 该方法已关闭 |
| 607 | 未知错误 |
| 701 | 该商品尚未激活 |
| 702 | 该商品维护中 |
| 703 | 折扣配置有误,请联系商务 |