API 综述

基本流程

接入 API 的基本流程是:

  1. 申请话费多帐号,获得 API_KEY 和 SECRET_KEY
  2. 预存充值货款到账户余额
  3. 进行开发测试
  4. 部署上线

如何获得 API_KEY 和 SECRET_KEY

登录话费多管理后台,在“设置”页面可以找到,你还可以随时重置它们,特别是当你怀疑帐号信息有可能泄露时,请及时重置它们。

关于帐号安全设置

为确保你的帐号、资金安全,建议正式使用之前在“设置” → “基本设置” 中完善以下设置项:

  1. API访问IP白名单(只允许指定IP访问API)
  2. 管理员登录提醒(短信 & 邮件提醒)
  3. 余额提醒(短信提醒)

签名

API调用时,需要传入两个基本请求参数:api_key(即后台获取的 API_KEY )、sign(用 SECRET_KEY 对其它请求参数签名后的结果)

签名(计算sign参数)方法如下:

  1. 把所有请求参数作为数组 A (参数mod除外,即后面你将会看到的API接口名称,不参与签名),对数组 A 按照键名进行升序排序。
  2. 把数组 A 中的键值对,顺序按照“key1value1key2value2...keyNvalueN”连接,得到一个字符串 B。
  3. 在字符串 B 的结尾跟上你自己的 SECRET_KEY,得到字符串 C。
  4. 对字符串 C 进行 MD5 (32位、小写)加密,得到签名sign。

代码示例:


    /* 话费多后台获取的API_KEY */
    $api_key = 'NtxrPCJlVGVp8BlPpWgVLYBPlUN9583FpqX5SvfD32TWr8AHQHervG7GqIDjEwOA';
    /* 话费多后台获取的SECRET_KEY */
    $secret_key = 'MCOuVTYMJHy2ASxgvCxQ8sme2QwvbkeOAS8sAXYOtl1U0c1vOmbMKoZv5l67lVJM';
    
    /* 接口请求参数 */
    $params = array(
        'phone_number' =>  '13006681888',
        'card_worth'    =>  100,
        'api_key'       =>  $api_key
    );
    
    /* 按键名升序对数组进行排序 */
    ksort($params);
    
    /* 连接参数为字符串 */
    $paramString = '';
    foreach($params as $key => $value){
        $paramString .= "{$key}{$value}";
    }

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

账户接口

account.balance

接口地址:http://api.huafeiduo.com/gateway.cgi?mod=account.balance

接口用途:查询账户余额。

请求方式:HTTP GET

返回格式:JSON

请求参数说明:

参数名 是否必须 描述
api_key 即在后台“设置”页面查询到的API_KEY,用于识别请求用户
sign 对请求参数的签名值,详见签名方法

返回结果说明:


    {
        status    = success | failure
        message = 失败消息,仅在接口调用失败(status=failure)时返回
        data =
        {
            balance = 账户余额,最多精确到两位小数
        }
    }
                    

返回示例:


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

订单接口

order.phone.check

接口地址:http://api.huafeiduo.com/gateway.cgi?mod=order.phone.check

接口用途:检查手机号是否能下单充值,并获取下单(进货)价格,以及手机号运营商、归属地等相关信息。

请求方式:HTTP GET

返回格式:JSON

请求参数说明:

参数名 是否必须 描述
phone_number 充值手机号
card_worth 充值面额,目前支持的面额有:1、2、5、10、20、30、50、100、300[元]
api_key 即在后台“设置”页面查询到的API_KEY,用于识别请求用户
sign 对请求参数的签名值,详见签名方法

返回结果:


    {
        status    = success | failure
        message = 失败消息,仅在接口调用失败(status=failure)时返回
        data = 
        {
            price = 49.6,下单(进货)价格
            card_worth = 50,充值面额
            phone_number = 13006681888,手机号
            area = 广东深圳,手机号归属地
            platform = 联通,所属运营商
        }
    }
                    

返回示例:


    {
        "status": "success", 
        "data":
        {
            "price": "49.60",
            "card_worth": "50", 
            "phone_number": "13006681888", 
            "area": "广东深圳", 
            "platform": "联通"
        }
    }
                    

order.phone.submit

接口地址:http://api.huafeiduo.com/gateway.cgi?mod=order.phone.submit

接口用途:提交充值订单。

请求方式:HTTP GET

返回格式:JSON

特别说明:

该接口返回的是下单结果,并不代表充值结果,因为充值过程需要提交到运营商异步处理。要获取最终的充值结果,请通过充值结果回调通知,或通过订单状态查询接口查询。

正常情况下(请求参数合法),通过该接口提交订单会立即返回下单成功,如遇到运营商维护或系统维护的情况,会立即返回下单失败。

请求参数说明:

参数名 是否必须 描述
phone_number 充值手机号
card_worth 充值面额,目前支持的面额有:1、2、5、10、20、30、50、100、300[元]
sp_order_id 商户订单号,你自己系统中的唯一订单号,用于关联你自己系统的订单和话费多平台订单,最大长度32位
notify_url 回调通知地址(包含域名和文件路径的完整有效url),充值结果会通过该地址通知给商户
api_key 即在后台“设置”页面查询到的API_KEY,用于识别请求用户
sign 对请求参数的签名值,详见签名方法

返回结果说明:


    {
        status    = success | failure (仅代表下单结果)
        message = 失败消息,仅在接口调用失败(status=failure)时返回
        order_id = 话费多平台订单号,长度19位,提交订单成功后返回
    }
                    

返回示例:


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

充值结果回调通知

如果提交订单时指定了回调通知地址(order.phone.submit 中的 notify_url 参数),那么订单处理完成后,话费多会把订单信息及充值结果以参数的形式,请求该地址通知给你。

你的回调地址在处理完话费多的请求后,应当输出“success”,以告知话费多你已经收到通知。

回调请求方式为:HTTP GET

特别说明:

在极少数情况下,运营商在处理订单的时候,有可能会撤销掉之前已经返回成功的订单,所以这样的(极少数)订单会发出两次回调通知,第一次回调通知充值成功,第二次在确认订单撤销后通知充值失败,请根据实际需求做好相应的处理。

在回调请求时,话费多会把回调参数签名,签名算法与请求话费多接口中的一致(详见签名方法),你可以通过验证签名值来确认回调请求的合法性。

回调参数说明:

参数名 描述
order_id 话费多平台订单号
status 订单充值结果,success(充值成功) | failure(充值失败)
worth 订单充值面额
price 订单下单(进货)价格
phone 订单充值手机号
sp_order_id 商户订单号,即通过order.phone.submit提交订单时传入的sp_order_id
sign 对回调参数的签名值,详见签名方法

order.phone.status

接口地址:http://api.huafeiduo.com/gateway.cgi?mod=order.phone.status

接口用途:查询充值订单状态。

请求方式:HTTP GET

返回格式:JSON

请求参数说明:

参数名 是否必须 描述
sp_order_id 商户订单号
api_key 即在后台“设置”页面查询到的API_KEY,用于识别请求用户
sign 对请求参数的签名值,详见签名方法

返回结果说明:


    {
        status = success | failure
        message = 失败消息,仅在接口调用失败(status=failure)时返回
        data = 
        {
	    order_status = init(订单初始化) | recharging(充值中) | success(充值成功) | failure(充值失败)
        }
    }
                    

返回示例:


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

order.phone.get

接口地址:http://api.huafeiduo.com/gateway.cgi?mod=order.phone.get

接口用途:获取充值订单信息。

请求方式:HTTP GET

返回格式:JSON

请求参数说明:

参数名 是否必须 描述
order_id 至少传一个 话费多平台订单号,它和sp_order_id至少传一个
sp_order_id 至少传一个 商户订单号,它和order_id至少传一个
api_key 即在后台“设置”页面查询到的API_KEY,用于识别请求用户
sign 对请求参数的签名值,详见签名方法

返回结果格式:


    {
        status    = success | failure
        message = 失败消息,仅在接口调用失败(status=failure)时返回
        data = { 订单数据 }
    }
                    

返回示例:


    {
        "status": "success", 
        "data":
        {
            "order_id": "2013120216200109432",
            "sp_order_id": "58c90e50530f320653",
            "status": "recharging",
            "phone_number": "13006681888", 
            "price": "49.60", 
            "card_worth": "50",
            "area": "广东深圳", 
            "platform": "联通",
            "create_time": "1385972375",
            "last_status_change_time": "1385972386"
        }
    }                   
                    

data中订单数据说明:

字段名 描述
order_id 话费多平台订单号
sp_order_id 商户订单号
status 订单状态,init(订单初始化) | recharging(充值中) | success(充值成功) | failure(充值失败)
phone_number 充值手机号
price 订单下单(进货)价格
card_worth 订单充值面额
area 手机号归属地
platform 运营商
create_time 订单创建时间,格式为时间戳
last_status_change_time 订单最近一次状态改变的时间(例如从充值中变为充值成功),格式为时间戳
group在线支持
contacts客服QQ
995557439
code技术QQ
995557469
work商务QQ
995557499
call联系电话
010-58496350