# 話費充值平臺V2.0
## 1 環境變量
### 接口
| 參數名 | 字段值 |
| --- | --- |
| baseurl | [http://域名/yrapi.php/](http://xn--eqrt2g/yrapi.php/) |
## 2 話費流量供應系統
## 2.1 接口說明
api提交方式：HTTP POST(表單) Content-Type：application/x-www-form-urlencoded
充值回調方式：HTTP POST(表單) 參數格式實例：order\_number=1&out\_trade\_num=1&mobile=1&otime=1&state=1
## 2.2 簽名說明
簽名步驟：
1、準備好所有待簽名參數（所有”請求參數“或所有”回調參數“都要參數簽名，除開sign字段，沒個api傳遞的參數都不同，這句提示很重要）
2、生成簽名字符串（參數名字典升序排序，apikey不參與排序，直接放最后，如后面示例進行組裝）“a=1&b=2&c=3&apikey=你的商戶key”。(實際字段名并非是a、b、c這里只是演示)
3、對簽名字符串進行大寫md5，簽名=md5(簽名字符串)
特別說明：簽名字符串不進行URL編碼，如果使用php 的http\_build\_query拼裝字符串時，會自動進行URL編碼，建議對簽名字符串進行一次URL解碼 ；提交報文中不要包含秘鑰，容易造成秘鑰暴露且不能驗簽通過；
php簽名實例（其它語言自行編寫）：
~~~
//簽名參數只是示例，并非真實提交數據
$param = ["參數名稱"=>"參數值",...];
//字典排序
ksort($param);
//拼接簽名串
$sign_str = http_build_query($param) . '&apikey=aaaaaaaaaaaaaaaaaaa';
//簽名
$sign = strtoupper(md5(urldecode($sign_str)));
$param['sign'] = $sign;
$httpdata = $param;
~~~
## 2.3 充值提交接口
> POST[http://域名/yrapi.php/index/recharge](http://xn--eqrt2g/yrapi.php/index/recharge)
### 接口說明
> 提交充值訂單
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| out\_trade\_num | string | GG5822222266 | true | 商戶訂單號，由商戶自己生成唯一單號。
（同一商戶，不能存在相同單號訂單，相同訂單號不能提單） |
| product\_id | number | 68 | true | 產品ID（代理后臺查看） |
| mobile | string | 18866667777 | true | 充值號碼（手機號、電費戶、qq號等） |
| notify\_url | string | [http://www.abc.com](http://www.abc.com/) | true | 回調地址，用于接收充值狀態回調 |
| userid | string | 10001 | true | 商戶ID，通過客服或代理后臺獲取 |
| amount | number | 100 | false | 面值，（不傳不校驗）如果產品的面值與此參數不同，提單駁回 |
| price | number | 94.8 | false | 最高成本，（不傳不校驗）如果產品成本超過這個值，提單駁回 |
| area | string | 廣東 | false | 電費省份/直轄市，如：四川、北京、上海，僅電費帶此參數 |
| ytype | string | 1 | false | 電費驗證三要素，1-身份證后6位，2-銀行卡后六位,3-營業執照后六位，僅南網電費帶此參數 |
| id\_card\_no | string | 123456 | false | 身份證后6位/銀行卡后6位/營業執照后6位，僅南網電費帶此參數 |
| city | string | 廣州 | false | 地級市名，僅部分南網電費帶此參數，是否帶此參數需咨詢渠道方 |
| param1 | string | \* | false | 擴展參數，后臺查看提交的產品類目是否需要提交此參數 |
| param2 | string | \* | false | 擴展參數，后臺查看提交的產品類目是否需要提交此參數 |
| param3 | string | \* | false | 擴展參數，后臺查看提交的產品類目是否需要提交此參數 |
| sign | string | JCXHF8S66BO6MPG5JNW2DGEJ9SB3F7ST | true | 簽名；簽名規則見2.2“簽名說明” |
~~~
請求示例：
out_trade_num=ABC1111&product_id=11&mobile=18899998888¬ify_url=http://www.abc.com/yuanren&userid=10001&sign=GZWDK8X7TGJFA8N8O9HILQ6WSI46C8FJ
~~~
### 響應體
● 響應數據格式：JSON，當“http狀態非200”或者“響應體無數據時”可能是服務器或其他鏈路出現故障，無法準確判定是否成功下單，請通過訂單查詢或者人工方式再次確認狀態。
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | \* | true | 錯誤碼，0代表成功，非0代表提交失敗 |
| errmsg | string | \* | true | 錯誤描述 |
| data | object | \* | true | errno=0時 返回數據 |
| ? order\_number | string | \* | true | 系統定單號 |
| ? mobile | string | \* | true | 充值手機號 |
| ? product\_id | string | \* | true | 產品ID |
| ? total\_price | string | \* | true | 消費金額 |
| ? out\_trade\_num | string | \* | true | 商戶訂單號 |
| ? title | string | \* | true | 充值產品說明 |
~~~
響應示例：
{
"errno": 0,
"errmsg": "下單成功",
"data": {
"order_number": "XYZ111111",
"mobile": "18866667777",
"product_id": 10001,
"total_price": "95.00",
"out_trade_num": "ABC1111",
"title": "100元話費",
}
}
~~~
## 2.4 查詢用戶信息
> POST[http://域名/yrapi.php/index/user](http://xn--eqrt2g/yrapi.php/index/user)
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | string | 1001 | true | 賬號ID |
| sign | string | JCXHF8S66BO6MPG5JNW2DGEJ9SB3F7ST | true | 簽名；簽名規則見2.2“簽名說明” |
### 響應體
● 響應數據格式：JSON
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | \* | true | 錯誤碼，0代表成功，非0代表失敗 |
| errmsg | string | \* | true | 錯誤描述 |
| data | object | \* | true | errno=0時 返回數據 |
| ? id | string | \* | true | userid |
| ? username | string | \* | true | 名稱 |
| ? balance | string | \* | true | 余額 |
## 2.5 獲取產品類型和產品分類
> POST[http://域名/yrapi.php/index/typecate](http://xn--eqrt2g/yrapi.php/index/typecate)
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | string | 1001 | true | 商戶ID |
| sign | string | JCXHF8S66BO6MPG5JNW2DGEJ9SB3F7ST | true | 簽名 |
### 響應體
● 響應數據格式：JSON
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | \* | true | 返回0 |
| errmsg | string | \* | true | 錯誤描述 |
| data | object | \* | true | errno=0時 返回數據 |
| ? id | string | \* | true | 產品類型id |
| ? type\_name | string | \* | true | 產品類型名稱 |
| ? cate | array | \* | true | 分類列表 |
| ?? id | int | \* | true | 分類ID |
| ?? cate | string | \* | true | 分類名稱 |
| ?? type | string | \* | true | 產品類型ID |
## 2.5 獲取產品
> POST[http://域名/yrapi.php/index/product](http://xn--eqrt2g/yrapi.php/index/product)
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | string | 10001 | true | 商戶ID |
| type | int | 1 | false | 產品類型ID,非必須 |
| cate\_id | int | 10 | false | 分類ID,非必須 |
| sign | string | JCXHF8S66BO6MPG5JNW2DGEJ9SB3F7ST | true | 簽名 |
### 響應體
● 響應數據格式：JSON
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | \* | true | 錯誤碼，0代表成功，非0代表失敗 |
| errmsg | string | \* | true | 錯誤描述 |
| data | object | \* | true | errno=0時 返回數據 |
| ? id | int | \* | true | 分類ID |
| ? cate | string | \* | true | 分類名稱 |
| ? sort | string | \* | true | 排序 |
| ? type | string | \* | true | 產品類型ID |
| ? products | array | \* | true | 產品列表 |
| ?? id | string | \* | true | 產品ID,下單報文中用此參數 |
| ?? name | string | \* | true | 產品名稱 |
| ?? desc | string | \* | true | 產品說明 |
| ?? api\_open | string | \* | true | 自動充值 |
| ?? isp | string | \* | true | 運營商集合（話費、流量有效），1移動,2電信,3聯通,4虛擬 |
| ?? ys\_tag | string | \* | true | 標簽 |
| ?? price | string | \* | true | 價格，下單扣費金額 |
| ?? y\_price | string | \* | true | 原價 |
| ?? max\_price | string | \* | true | 封頂價格 |
| ?? type | string | \* | true | 產品類型ID |
| ?? cate\_name | string | \* | true | 產品分類名稱 |
| ?? type\_name | string | \* | true | 產品類型名稱 |
## 2.6 自發查詢訂單狀態
> POST[http://域名/yrapi.php/index/check](http://xn--eqrt2g/yrapi.php/index/check)
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | string | 10001 | true | 賬戶ID |
| out\_trade\_nums | string | CZH668877,CZH9988666 | true | 商戶訂單號；多個用英文,分割 |
| sign | string | JCXHF8S66BO6MPG5JNW2DGEJ9SB3F7ST | true | 簽名 |
### 響應體
● 響應數據格式：JSON
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | 0 | true | 錯誤碼，0代表成功，非0代表失敗 |
| errmsg | string | 查詢成功 | true | 錯誤描述 |
| data | object | \* | true | errno=0時 返回數據 |
| ? order\_number | string | CZH1111111 | true | 系統訂單號 |
| ? out\_trade\_num | string | AB882863666 | true | 商戶訂單號 |
| ? create\_time | string | 1652403339 | true | 下單時間 |
| ? mobile | string | 18866667777 | true | 手機號 |
| ? product\_id | string | 88 | true | 產品ID |
| ? charge\_amount | float | 100 | true | 充值成功面額 |
| ? charge\_kami | string | yspm1mkdksald | true | 卡密流水 |
| ? state | string | 1 | true | 充值狀態：-1取消，0充值中 ，1充值成功，2充值失敗，3部分成功 |
## 2.7 充值結果通知-異步通知
> POST-表單格式
> 回調地址：訂單提交時參數中傳的回調的地址
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | int | 10001 | true | 商戶ID |
| order\_number | CZH000000000 | string | | true |
| out\_trade\_num | string | ABC2222 | true | 商戶訂單號 |
| otime | number | 1652403339 | true | 成功/失敗時間，10位時間戳 |
| state | number | 1 | true | 充值狀態；-1取消， 0充值中， 1充值成功 ，2充值失敗，3部分成功（-1,2做失敗處理；1做成功處理；3做部分成功處理） |
| mobile | string | 18866667777 | true | 充值手機號 |
| remark | string | 充值成功 | true | 備注信息 |
| charge\_amount | float | 100 | true | 充值成功面額 |
| voucher | string | [http://www.abc.com/xxx](http://www.abc.com/xxx) | true | 憑證 |
| charge\_kami | string | 3etydgd45gf11 | true | 卡密/流水號 |
| sign | string | DS9V0606ITN8GLJM5M4L4DYWQX0VDMVM | true | 簽名字符串，用于驗簽,以保證回調可靠性。
簽名規則見：2.2簽名說明
注：所有參數都要參與簽名，請獲取所有參數簽名，而不是獲取現有參數表中的字段簽名，以免回調參數增加時導致簽名不通過 |
| ... | \* | \* | \* | 更多參數 |
### 響應體
● 收到回調響應文本“success”，如果不響應系統每隔1分鐘會再次發起回調，最多回調5次。
~~~
success
~~~
~~~
php版回調驗簽示例：
$apikey="你的秘鑰";
$data = $_POST;//接收所有post的數據
unset($data['sign']);//刪除掉sign字段
ksort($data);//排序
$sign_str = urldecode(http_build_query($data)) . '&apikey=' . $apikey;//獲得簽名原串
$mysign=strtoupper(md5($sign_str));//簽名
if($mysign==$_POST['sign']){
//簽名正確
}
~~~
## 2.8 電費支持地區查詢
> POST[http://域名/yrapi.php/index/elecity](http://xn--eqrt2g/yrapi.php/index/elecity)
### 請求體(Request Body)
| 參數名稱 | 數據類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| userid | string | 10001 | true | 賬號ID |
| sign | string | DS9V0606ITN8GLJM5M4L4DYWQX0VDMVM | true | 簽名；簽名規則見2.2“簽名說明” |
### 響應體
● 響應數據格式：JSON
| 參數名稱 | 類型 | 示例 | 不為空 | 描述 |
| --- | --- | --- | --- | --- |
| errno | string | 0 | true | 錯誤碼，0代表查詢成功，非0代表失敗 |
| errmsg | string | 查詢成功 | true | 錯誤描述 |
| data | array | \* | true | errno=0時 返回數據 |
| ? city\_name | string | 廣東 | true | 地區名稱 |
| ? sort | int | 100 | true | 排序 |
| ? initial | string | G | true | 首字母 |
| ? need\_ytype | Int | 1 | true | 是否三要素認證 |
| ? need\_city | Int | 1 | true | 是否需要選擇城市（當此開關打開以后才有下面的城市列表） |
| ? city | Array | \* | true | 支持的地級市 |
| ?? city\_name | string | 廣州 | true | 城市名稱 |
| ?? initial | string | G | true | 首字母 |
