liuliang / api_docs

api说明文档(全).md 15.7 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
area string 是 流量范围:
0 : 全国包
1 : 省漫游包
2 : 省内包		 0
capacity string 是 流量包大小: (单位:MB) 10
available_length string 否 流量有效时长:
单位:小时。大于24小时则以'天'记。如:传16则认为有效时长是16小时,传24则认为有效时长是一天,传25则依然认为有效时长为一天。
(不传默认当月有效)		 720
clear_type string 否 流量清零方式:
0: 零点清零
1: 按照流量有效时长清零
(不传默认零点清零) 		0
partner_order_no string 否 合作方订单唯一标识: 若提交,在推送中会带有partner_order_no信息 2016011313325615104

调用示例：

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

同步响应参数说明:

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

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

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

推送参数：

参数 类型 必填 描述 范例
phone int 是 充值号码 13888888888
group int 是 这次充值请求的批次号 12
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=12345678900&count=50&timestamp=2160113133256&sign=7d0ddc3d2de92eb5e49a8efa10fe1d0e67290220' -H Content-Type:application/json -v

同步响应参数说明:

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

充值记录参数

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

五、 通过卡密查询流量充值卡具体信息

    提交方式： GET 
    URL: https://服务器域名/api/cards/queryPassword
    接收参数：
    {
        "password"  : "2g8myv",            #卡密内容（必填）
        "timestamp" : "20160113133256",    # 请求时间戳(必填，14位)
        "sign"      : "8814988657f8bc805e951bc46b0862bf90555b01" # 按照规则加密后的密文(必填，加密详情见下文【八、加密方法】)
    } 

    调用示例：
    curl 'https://服务器域名/api/cards/queryPassword?password=47u4s5&timestamp=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/chargeBatchNumbers

接收参数：

参数 类型 必填 描述 范例
username string 是 用户账号 username
phone string 是 充值号码:
多个号码用英文竖线(|)隔开(一次最多100个号码,号码不可重复)，单个号码不用分隔		 13888888888|15555555555
timestamp string 是 请求时间戳:
14位,格式: yyyyMMddHHmmss		 20160113133256
sign string 是 按照规则加密后的密文:
加密详情见下文【八、加密方法】		 8814988657f8bc805e951bc46b0862bf90555b01
area string 是 流量范围:
0 : 全国包
1 : 省漫游包
2 : 省内包		 0
cmCapacity string 否 移动流量包大小:
单位:MB		 10
cuCapacity string 否 联通流量包大小:
单位:MB		 20
ctCapacity string 否 电信流量包大小:
单位:MB		 5
available_length string 否 流量有效时长:
单位:小时。大于24小时则以'天'记。如: 传16则认为有效时长是16小时,传24则认为有效时长是一天,传25则依然认为有效时长为一天。
(不传默认当月有效)		 720
clear_type string 否 流量清零方式
0: 零点清零
1: 按照流量有效时长清零
不传默认零点清零 		0
partner_order_no string 否 合作方订单唯一标识: 若提交,在推送中会带有partner_order_no信息 2016011313325615104

调用示例：

curl 'https://服务器域名/api/accounts/chargeBatchNumbers?area=0&username=11111&phone=13888888888|15555555555&cmCapacity=10&cuCapacity=20&timestamp=2160113133256&sign=7da67f8b9627d1783ef00311125ad246a4eed329' -H Content-Type:application/json -v

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

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

八、 商户查询该号码可充的产品

提交方式： GET URL: https://服务器域名/api/phone/get_products

接收参数：

参数 类型 必填 描述 范例
username string 是 用户账号 username
phone string 是 充值号码，单个号码 13888888888
sign string 是 按照规则加密后的密文:
加密详情见下文【九、加密方法】		 8814988657f8bc805e951bc46b0862bf90555b01

调用示例：

curl 'https://服务器域名/api/phone/get_products?username=12345678900&phone=18662548960&sign=038cd8cfa77ab73a0f713a187b77c2e40a59ab63' -H Content-Type:application/json -v

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

参数 类型 必填 描述 范例
success int 是 接口调用是否成功 1
mobile json 是 号码信息 {"carrier":"联通","province":"江苏","city":"苏州","number":"18662548960"}
products array 否 该号码产品列表 [{"name":"联通全国包20M","area":"0","capacity":20,"available_length":"720","clear_type":"0","discount":0.6,"price":3.0,"active":true,"msg":"可用"}]
code int 否 错误码 详见文档末详情见下文【十、错误码】 301
reason string 否 具体的失败原因描述 商户不存在

九、 加密方法

1. 组合加密字符串

将参数值按照自定义顺序进行连接，以英文逗号(,)分隔，并去掉为空的参数

如：如果要传递的数据为

username=aaaaa&phone=15939393939|13878787878&cmCapacity=10&cuCapacity=20timestamp=20160223120445

2. 将用户password进行SHA1加密(40位小写),将得到的password字符串拼接在加密字符串尾部，若SHA1(password)=7b21848ac9af35be0ddb2d6b9fc3851934db8420

则组合后的加密字符串为：

aaaaa,15939393939|13878787878,10,20,20160223120445,7b21848ac9af35be0ddb2d6b9fc3851934db8420

3. 加密组合后的字符串

按照标准的SHA1（40位小写）加密方式对组合后的字符串进行加密。加密结果如：加密前为：

aaaaa,15939393939|13878787878,10,20,20160223120445,7b21848ac9af35be0ddb2d6b9fc3851934db8420

加密后为：

0ee45942d183a11e64c62bec00cfc4c0bb855ad2

加密方法的Ruby语言 Demo

    # 加密方法的Ruby语言 Demo
    # params = {
    #    username:   aaaaa
    #    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 << SHA1(password)
      # 我这里把参数放到一个数组里，非必须
      # result = [aaaaa,15939393939|13878787878,10,20,20160223120445,7b21848ac9af35be0ddb2d6b9fc3851934db8420]
      # 将数组按逗号分隔拼接成字符串，并按照标准的SHA1(40位小写)加密方式，对组合后的字符串进行加密
      Digest::SHA1.hexdigest(result.join(','))
      # 得到加密后的结果为：0ee45942d183a11e64c62bec00cfc4c0bb855ad2
    end

十、 错误码

错误码 说明
101 不存在的卡
102 该卡兑换中
103 该卡已过期
104 该卡已被使用
105 五十元卡密不支持中国联通号码
201 手机号码不正确!
202 必须要有手机号
301 商户余额不足,无法充值
302 该商户不存在
303 该商户被禁用
305 无该省份充值权限
306 未使用授权ip
307 不存在或不拥有该套餐充值权限,请检查流量包
401 该商户不存在此条记录
501 上级代理商余额不足
601 号码与流量包不匹配
602 该运营商充值渠道暂时关闭
603 该省充值渠道暂时关闭
604 该运营商不提供此流量包
605 缺少号码所需的流量包
606 参数格式有误
607 未知错误