API 综述

本 API 提供给用户使用,提供了快捷下单进行充值的业务。如需要任何帮助,欢迎联系我们的 QQ 开发支持:995557469

基本流程

接入 API 的基本流程是:

  1. 申请帐号,获得 API_KEY 和 SECRET_KEY
  2. 预存金额进入系统
  3. 进行开发测试
  4. 部署上线

如何获得 API_KEY 和 SECRET_KEY

登录后,后台“设置”页面可以找到,你还可以随时重置它们,特别是当你怀疑有可能被泄露时,请及时重置它。

关于调用 IP 限制

登录后,后台“设置”页面可以设置IP限制,限制后,只有你指定的IP的机器才可以访问你的API账户。最大限度保护了资金和账户安全。我们强烈要求设置此项目,以免损失。

签名

API调用时,需要传入api_key,同时用 secret_key 做签名。

签名方法如下:

  1. 把所有参数作为一个数组 A,按照数组键值的字母升序排列。获得一个新数组 B。(参数mod不参与签名)
  2. 对数组 B 按照'key1value1key2value2'排列。变成一个字符串 C。
  3. 对字符串 C 结尾跟上你自己的 secret_key。
  4. 对字符串进行 MD5 计算,结果以小写表示。

代码示例:


    $secret_key = '12322222';
    
    $params = array(
        'phone_number' =>  '13800138000',
        'card_worth'    =>  '100',
        'api_key'       =>  '1234567889'
    );
    
    ksort($params);     /// 按键名升序对数组进行排序
    
    $paramString = '';
    foreach($params as $key => $value){
        $paramString .= "{$key}{$value}";
    }

    $sign = md5($paramString . $secret_key);
                    

全局API

account.balance

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=account.balance

获得当前余额。

参数名 请求类型 是否必须 中文名 备注
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status    = "success" | "failure"
        message = null | ERROR MESSAGE
        data =
        {
            balance = 账户余额,单位:元。最多精确到两位小数
        }
    }
                    

返回示例:


    {
        "status": "success",
        "data":
        {
            "balance": 2350
        }
    }
                    

话费充值API

注意 : 目前开通的的手机话费充值面额有:1,2,5,10,20,50,100,300[元]

order.phone.get

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.phone.get

获得单个订单信息,包括状态,可以用这个接口来检查是否完成了充值。

order_id 和 sp_order_id 至少需要传一个。

参数名 请求类型 是否必须 中文名 备注
order_id GET 至少传一个 话费多订单号
sp_order_id GET 至少传一个 您的系统中的订单号
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status    = "success" | "failure"
        message   = null | <error message>
        data = { 订单数据 }
    }
                    

返回示例:


    {
        "status": "success", 
        "data": {
            "mobile_num": "13800138000", 
            "price": "10.30", 
            "card_worth": "10.00", 
            "create_time": "1385972375", 
            "status": "init", 
            "order_id": "2013120216200109432",
            "sp_order_id": "2013120517220131245"
        }
    }                   
                    

单个订单信息格式:

参数名 中文名 备注
order_id 话费多订单号
status 状态 可能为:success(成功),failure(失败),recharging(充值中),init(初始化,等待充值)4个状态
sp_order_id 您的系统中的订单号
price 充值成本
card_worth 面值
create_time 订单生成时间 UNIX 时间戳,自 1970 年 1 月 1 日零时以来经过的秒数
last_status_change_time 最后一次状态改变的时间 UNIX 时间戳,自 1970 年 1 月 1 日零时以来经过的秒数

order.phone.list

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.phone.list

获得多个订单信息,主要可以用于对账。

时间、状态和订单编号参数至少需要传一个。如果要获取一段时间内的所有订单,则只需要传递时间参数即可。

时间范围不能大于一个月。

参数名 请求类型 是否必须 中文名 备注
start_time GET 至少传一个 开始时间 和 end_time 成对出现,格式为 UNIX 时间戳。
end_time GET 至少传一个 结束时间 和 start_time 成对出现,格式为 UNIX 时间戳。
status GET 至少传一个 订单状态 可以为 success, recharging 或 failure 其中的一个
order_id GET 至少传一个 订单编号 如果有多个订单号,则订单号之间使用半角逗号分隔
page GET 可选 页码 每次最多返回 50 条结果,可以使用此参数来控制返回第几页结果
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status    = "success" | "failure"
        message   = null | <error message>
        data      = 
        {
            count     = <查询结果总数>
            page      = <当前页码>
            page_size = <每页记录数量>
            orders =
            [
                { 订单数据 1 },
                { 订单数据 2 },
                ...
            ]
    }
                    

返回示例:


    {
        "status": "success", 
        "data": 
        {
            "count": "52", 
            "page": "2", 
            "page_size": 50, 
            "orders": 
            [
                {
                    "mobile_num": "13800138000", 
                    "price": "10.30", 
                    "card_worth": "10.00", 
                    "create_time": "1386040164", 
                    "status": "success", 
                    "order_id": "2013120311100104114",
                    "sp_order_id": "2013120515400202535"
                }, 
                {
                    "mobile_num": "13800138123", 
                    "price": "10.30", 
                    "card_worth": "20.00", 
                    "create_time": "1386040104", 
                    "status": "init", 
                    "order_id": "2013120311100204793",
                    "sp_order_id": null
                }, 
            ]
    }
                    

order.phone.check

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.phone.check

检查当前是否可以下单,以及下单价格。

参数名 请求类型 是否必须 中文名 备注
card_worth GET 必需 充值卡面值
phone_number GET 必需 手机号码
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status    = "success" | "failure"
        data = 
        {
            price = 49.5,
            card_worth = 50,
            phone_number = 15623720747,
            area = 湖北武汉,
            platform = 联通
        }
        error_code = 1 | 2,3,4...
    }
    //查询成功时只返回 status = "success",查询失败时才返回message,error_code
                    

返回示例:


    {
        "status" : "success",
        "message" : "error message",
        "error_code" : 1
    }
                    

order.phone.status

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.phone.status

检查当前订单状态(实时询问运营商),为了避免某些订单状态有疑问,提供此接口在于实时检查当前运营商返回订单状态。

参数名 请求类型 是否必须 中文名 备注
sp_order_id GET 必需 商户订单号
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status = "success" | "failure"
        data = 
        {
	    "order_status" = "init" | "recharging" | "success" | "failure" //依次对应的状态意义为:初始化,充值中,充值成功,充值失败
        }
    }
    //查询失败时只返回 status = "failure",查询成功时才返回data
                    

返回示例:


    {
        "status" : "success",
        "data" : 
		 "order_status":"success"
    }
                    

order.phone.submit

需要签名验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.phone.submit

下单接口,下单后接口会立即返回成功,如遇运营商维护等情况,会立即返回失败。

当一笔订单处理完成后 话费多会向notify_url[如果提交订单时传入了此参数]发送异步通知,告知商户充值结果 详情见回调结果

参数名 请求类型 是否必须 中文名 备注
card_worth GET 必需 充值卡面值 面前开放的面值有:1,2,5,10,20,50,100,300[元]
phone_number GET 必需 要充值的手机号码
notify_url GET 可选 商户接收充值结果的回调地址 包含域名和文件路径的完整有效url
sp_order_id GET 必需 商户订单号 商户网站唯一订单号
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status    = "success" | "failure"
        message = null | error message
        order_id = 话费多订单号[成功提交订单时返回]
    }
    //提交成功时只返回 status = "success",提交失败时才返回message,error_code
                    

返回示例:


    {
        "status" : "success",
        "order_id" : "2011122900544110011"
    }
                    

回调说明

当订单处理完成后,话费多会主动发送异步回调通知,请求方法为 GET,请求地址为提交订单时指定的回调地址(order.phone.submit 中的 notify_url)

充值完成后,程序回调接口会回调你提供的 notify 接口,你的 notify 接口处理完成后应该输出 success。

注意:

  • 只有在订单处理完成后才会发送回调通知。
  • 运营商在处理一些订单的时候,有可能撤销已经成功的订单,所以(极其少量的)订单有可能会发出两次通知,第一次回调通知充值成功,在运营商撤销订单后发送回调通知充值失败。
参数名 请求类型 中文名 备注
order_id GET 话费多订单号 订单在话费多平台的订单号
status GET 订单处理结果 该值只可能为"success"和"failure"其中一项 "success"为充值成功,"failure"为充值失败
worth GET 面值 订单中话费充值面额
price GET 成本价 订单所消耗的话费多余额 即订单总价
phone GET 手机号码 该订单充值的手机号码
sp_order_id GET 商户订单号 即通过order.phone.submit提交订单时传入的sp_order_id
sign GET 签名 回调GET参数与secret_key的签名结果

  sign的生成方式如下:

  1. order_id + status + worth + price+ phone + sp_order_id + secret_key得到字符串A
  2. 将A字符串进行md5即得到最终结果[结果字符串为小写]

Q 币及 QQ 类商品充值 API

order.qq.check

需要签名 验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.qq.check

检查商品当前是否可以购买,并获取商品当前的售价。

参数名 请求类型 是否必须 中文名 备注
product_id GET 必需 QQ 类产品编号
quantity GET 可选 购买数量,如果不传此参数则默认购买 1 件
account GET 可选 充值账户(如 QQ 号码)
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status: "success" | "failure",
        message: null | ERROR MESSAGE,
        data:
        {
            product_id: 商品编号,
            quantity: 购买的商品数量,
            unit_price: 商品单价(单位:元),
            total_price: 商品总价(单位:元)
        }
    }
                    

返回示例:


    {
        status: "success",
        data:
        {
            product_id: "230101",
            quantity: "1",
            unit_price: "4.51",
            total_price: "4.51"
        }
    }
           
                    

order.qq.product

需要签名 验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.qq.product

查询商品列表。该接口会以数组方式返回所有在售商品,并包括商品信息。

参数名 请求类型 是否必须 中文名 备注
product_id GET 可选 产品编号 如果不传此参数,那么返回结果中将包含所有产品的信息。如果传递了此参数,那么返回的结果中将只包含指定编号的产品。
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status: "success" | "failure",
        message: null | ERROR MESSAGE,
        data:
        [
            {
                product_id: 商品编号,
                price: 商品售价,
                name: 商品名字,
                type: 商品类型
            },  /* 第一个商品 */
            {
                ... /* 第二个商品的信息 */
            },
            ...
        ]
    }
                    

商品信息中 type 字段的意义如下:

  • 当 type 的值为 recharge 时,表明该商品是直充类商品(如 QQ 会员直充)
  • 当 type 的值为 buy 时,表明该商品是卡密类商品(如 Q 币充值卡)

返回示例:


    {
        "status": "success", 
        "data":
        [
            {
                "product_id": "015077", 
                "price": "37.0000", 
                "name": "Q 币 40 元卡密", 
                "type": "buy"
            },
            {
                "product_id": "699248", 
                "price": "61.1000", 
                "name": "QQ 会员 70 元直充", 
                "type": "recharge"
            }
        ]
    }
           
                    

order.qq.submit

需要签名 验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.qq.submit

提交一个 Q 币充值或 QQ 类商品的订单

参数名 请求类型 是否必须 中文名 备注
product_id GET 必需 产品编号 要购买的产品编号
sp_order_id GET 必需 商户订单编号 您的系统中的订单编号,订单编号不能和以前提交过的订单编号重复
account GET 可选 充值账号 充值账号应该是一个 QQ 号码,如果号码不正确会导致充值失败。当购买的商品类型是直充类商品时,必须提供此参数
notify_url GET 可选 回调通知地址 当订单处理完毕后,会这个地址发送回调。有关回调的信息请参考 Q 币及 QQ 类商品回调说明
quantity GET 可选 数量 购买数量。如果不传此参数,则默认购买数量为 1。每笔订单最多可以同时订购 10 个产品。
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status: success | failure,
        message: null | ERROR MESSAGE
        data:
        {
            order_id: 话费多订单号
        }
    }
                    

返回示例:


    {
        status: "success",
        data:
        {
            order_id: "2014052310424010043"
        }
    }
           
                    

order.qq.status

需要签名 验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.qq.status

查询一个 Q 币充值或 QQ 类商品订单的状态

sp_order_id 和 order_id 至少需要传其中的一个

参数名 请求类型 是否必须 中文名 备注
sp_order_id GET 可选 商户订单编号 您系统中的订单编号
order_id GET 可选 话费多订单号 话费多的订单编号
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status: success | failure,
        message: null | ERROR MESSAGE
        data:
        {
            order_status: init | recharging | success | failure
        }
    }
                    

其中 order_status 字段值的含义为:

字段值 含义
init 订单正在初始化
recharging 订单正在处理中
success 充值(或购买)成功
failure 充值(或购买)失败

返回示例:


    {
        status: "success",
        data:
        {
            order_status: "recharging"
        }
    }
           
                    

order.qq.card

需要签名 验证IP

API : http://api.huafeiduo.com/gateway.cgi?mod=order.qq.card

获取购买成功的卡密类订单的卡号和密码,以数组方式返回。如果只有一张卡片,则数组中只包含一张卡片的信息。如果有多张卡片,则数组中就包含多张卡片的信息。

sp_order_id 和 order_id 至少需要传其中的一个

参数名 请求类型 是否必须 中文名 备注
sp_order_id GET 可选 商户订单编号 您系统中的订单编号
order_id GET 可选 话费多订单号 话费多的订单编号
sign GET 必需 签名 必须要签名
api_key GET 必需 API KEY 必须要有 api_key

返回结果格式:


    {
        status: success,
        message: null | ERROR MESSAGE
        data: 
        {
            cards:
            [
                {
                    number: 卡号,
                    password: 密码,
                    expire_time: 失效日期,UNIX 时间戳格式
                },
                ...
            ]
        }

    }
 
                    

其中 order_status 字段值的含义为:

字段值 含义
init 订单正在初始化
recharging 订单正在处理中
success 充值(或购买)成功
failure 充值(或购买)失败

返回示例:


    {
        status: success,
        data: 
        {
            cards:
            [
                {
                    number: "8429967705",
                    password: "0579288568",
                    expire_time: 1716170000
                },
                {
                    number: "8429967706",
                    password: "5521099948",
                    expire_time: 1716170000
                }
            ]
        }
    }
           
                    

回调说明

当订单处理完成后,话费多会主动发送异步回调通知,请求方法为 GET,请求地址为提交订单时指定的回调地址(order.qq.submit 中的 notify_url)

充值完成后,程序回调接口会回调你提供的 notify 接口,你的 notify 接口处理完成后应该输出 success。

注意:只有在订单处理完成后才会发送回调通知。

参数名 请求类型 中文名 备注
order_id GET 话费多订单号 订单在话费多平台的订单号
status GET 订单处理结果 该值只可能为"success"和"failure"其中一项 "success"为充值(或购买)成功,"failure"为充值(或购买)失败
unit_price GET 产品单价 一件商品的价格
total_price GET 总价 订单总价
quantity GET 产品数量 该订单购买的产品数量
account GET 充值账号 被充值的账号
sp_order_id GET 商户订单号 您的系统中的订单编号
sign GET 签名 回调GET参数与secret_key的签名结果

签名计算方法和 签名 小节中描述的签名计算方法一致。但要注意,在回调接口中,sign 是签名结果,不参与签名计算。

group在线支持
contacts客服QQ
995557439
code技术QQ
995557469
work商务QQ
995557499
call联系电话
010-58496350