# api对接参数

**Repository Path**: gate-assembly/api-docking-parameters

## Basic Information

- **Project Name**: api对接参数
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2021-12-11
- **Last Updated**: 2022-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 话费充值平台V2.0

## 1	环境变量

### 接口
| 参数名 | 字段值 |
| ------ | ------ |
|baseurl|http://域名/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
### 接口说明
> 提交充值订单
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| out_trade_num|string||true|商户订单号，由商户自己生成唯一单号。<br>（同一商户，不能存在相同单号订单，相同订单号不能提单）|
| product_id|number||true|产品ID（代理后台查看）|
| mobile|string||true|充值号码（手机号、电费户、qq号等）|
| notify_url|string||true|回调地址，用于接收充值状态回调|
| userid|string||true|商户ID，通过客服或代理后台获取|
| amount|number||false|面值，（不传不校验）如果产品的面值与此参数不同，提单驳回|
| price|number||false|最高成本，（不传不校验）如果产品成本超过这个值，提单驳回|
| area|string||false|电费省份/直辖市，如：四川、北京、上海，仅电费带此参数|
| ytype|string||false|电费验证三要素，1-身份证后6位，2-银行卡后六位,3-营业执照后六位，仅南网电费带此参数|
| id_card_no|string||false|身份证后6位/银行卡后6位/营业执照后6位，仅南网电费带此参数|
| city|string||false|地级市名，仅部分南网电费带此参数，是否带此参数需咨询渠道方|
| sign|string||true|签名；签名规则见“签名说明”|

```
请求示例：
out_trade_num=ABC1111&product_id=11&mobile=18899998888&notify_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
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|string||true|账号ID|
| sign|string||true|签名；签名规则见“签名说明”|
### 响应体
● 响应数据格式：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
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|string||true|商户ID|
| sign|string||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
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|string||true|商户ID|
| type|int||false|产品类型ID,非必须|
| cate_id|iNt||false|分类ID,非必须|
| sign|string||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
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|string||true|账户ID|
| out_trade_nums|string||true|商户订单号；多个用英文,分割|
| sign|string||true|签名|
### 响应体
● 响应数据格式：JSON

| 参数名称 | 类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| errno|string||true|错误码，0代表成功，非0代表失败|
| errmsg|string||true|错误描述|
| data|object||true|errno=0时 返回数据|
|⇥ order_number|string||true|系统订单号|
|⇥ out_trade_num|string||true|商户订单号|
|⇥ create_time|string||true|下单时间|
|⇥ mobile|string||true|手机号|
|⇥ product_id|string||true|产品ID|
|⇥ charge_amount|float||true|充值成功面额|
|⇥ state|string||true|充值状态：-1取消，0充值中 ，1充值成功，2充值失败，3部分成功|


## 2.7	充值结果通知-异步通知

> POST-表单格式 
> 回调地址：订单提交时参数中传的回调的地址
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|int||true|商户ID|
| order_number|string||true|系统订单号|
| out_trade_num|string||true|商户订单号|
| otime|number||true|成功/失败时间，10位时间戳|
| state|number||true|充值状态；-1取消， 0充值中， 1充值成功 ，2充值失败，3部分成功（-1,2做失败处理；1做成功处理；3做部分成功处理）|
| mobile|string||true|充值手机号|
| remark|string||true|备注信息|
| charge_amount|float||true|充值成功面额|
| voucher|string||true|凭证|
| sign|string||true|签名字符串，用于验签,以保证回调可靠性。<br>签名规则见：签名说明<br>注：所有参数都要参与签名，请获取所有参数签名，而不是获取现有参数表中的字段签名，以免回调参数增加时导致签名不通过|
### 响应体
● 收到回调响应文本“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
### 请求体(Request Body)
| 参数名称 | 数据类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| userid|string||true|账号ID|
| sign|string||true|签名；签名规则见“签名说明”|
### 响应体
● 响应数据格式：JSON

| 参数名称 | 类型 | 默认值 | 不为空 | 描述 |
| ------ | ------ | ------ | ------ | ------ |
| errno|string||true|错误码，0代表查询成功，非0代表失败|
| errmsg|string||true|错误描述|
| data|array||true|errno=0时 返回数据|
|⇥ city_name|string||true|地区名称|
|⇥ sort|int||true|排序|
|⇥ initial|string||true|首字母|
|⇥ need_ytype|Int||true|是否三要素认证|
|⇥ need_city|Int||true|是否需要选择城市（当此开关打开以后才有下面的城市列表）|
|⇥ city|Array||true|支持的地级市|
|⇥⇥ city_name|string||true|城市名称|
|⇥⇥ initial|string||true|首字母|