25、停车费线索补缴开放接口

# 停车费线索补缴开放接口

## 一、加密步骤

### 1.1 接口协议
- **协议类型**：HTTP/HTTPS
- **请求方式**：POST
- **数据格式**：
  - 请求体：Base64编码字符串
  - 响应体：Base64编码字符串（需解码验证）
- **签名验证流程**：
  1. 解码返回数据获得原始JSON
  2. 对比返回的`sign`与本地计算的签名值
  3. 一致则视为合法数据

**响应示例**：
```json
{
  "sign": "7433C546E91399062E48CDCACEB8A615",
  "data": {
    "message": "签名错误",
    "state": 0
  }
}
```

### 1.2 数据签名
| 参数       | 说明                   |
|------------|------------------------|
| union_id   | 厂商编号（联盟编号）   |
| comid      | 车场编号               |
| ckey       | 车场秘钥               |

**签名生成步骤**：
1. 拼接数据：原始`data`字段值 + `key={ckey}`
2. 计算MD5：对拼接字符串进行MD5加密
3. 格式转换：结果转为大写

**请求示例**：
原始数据：

```
{
  "data": {
    "comid": "kytest2020032501",
    "union_id": "200279",
    "car_number": "晋QQ1234",
    "lock_status": 1
  }
}

```
签名串：
{"comid":"kytest2020032501","union_id":"200279","car_number":"晋QQ1234","lock_status":1}key=MAVXUU3C2545G9K1

最终请求体（Base64编码）：
eyJkYXRhIjp7ImNvbWlkIjoia3l0ZXN0MjAyMDAzMjUwMSIsInVuaW9uX2lkIjoiMjAwMjc5IiwiY2FyX251bWJlciI6IuaZi1FRMTIzNCIsImxvY2tfc3RhdHVzIjoxfSwic2lnbiI6IjQ5NzM3NjUwODlGMjBGQ0ZFNDU4Njg3OTZGODEyNzhBIn0=

## 二、接口定义

### 1. 三方平台助缴订单推送
#### 1.1 接口描述
- **功能**：推送欠费订单（增量推送，状态均为"待支付"）
- **限制**：单次≤20条
- **重复处理**：订单号重复需过滤并返回成功
- **调用方**：三方平台

#### 1.2 接口地址
- 测试环境：`http://ts.bolink.club/zld/arrearsRecovery/orderPush`
- 正式环境：`http://yun.bolink.club/zld/arrearsRecovery/orderPush`

#### 1.3 请求参数
| 参数名            | 必须 | 类型     | 说明                                                                 |
|-------------------|------|----------|----------------------------------------------------------------------|
| union_id          | 是   | String   | 联盟编号                                                             |
| comid             | 是   | String   | 车场编号                                                             |
| orderList         | 是   | List     | 订单组                                                               |
| ownerId        | 是   | String   | 业主ID                                                               |
| parkNo         | 是   | String   | 订单流水号                                                           |
| parkName       | 是   | String   | 车场/路段名称                                                        |
| parkingLocation| 是   | String   | 停车地址                                                             |
| vehPlates      | 是   | String   | 车牌号码                                                             |
| vehColor       | 是   | int      | 车牌颜色（0蓝/1黄/2黑/3白/4渐变绿/5黄绿双拼/6蓝白渐变/9不确定）       |
| enterTime      | 是   | String   | 进场时间（yyyy-MM-dd HH:mm:ss）                                      |
| exitTime       | 是   | String   | 离场时间（yyyy-MM-dd HH:mm:ss）                                      |
| amount         | 是   | String   | 金额（单位：分）                                                     |
| orderTime      | 是   | String   | 订单时间（yyyy-MM-dd HH:mm:ss）                                      |
| duration       | 是   | int      | 停车时长（分钟）                                                     |

**请求示例**：
```json
{
  "union_id": "1002348",
  "comid": "1002348",
  "orderList": [{
    "parkNo": "19998228ss",
    "parkName": "贵州贵阳白云区科教街停车场",
    "parkingLocation": "贵阳市白云区科教街北段_1号车位",
    "vehPlates": "贵Z91213",
    "vehColor": 0,
    "enterTime": "2024-07-28 00:00:00",
    "exitTime": "2024-07-28 01:00:00",
    "amount": 30,
    "orderTime": "2024-07-28 01:00:00",
    "duration": 60
  }]
}
```

#### 1.4 响应参数
| 参数名        | 必须 | 类型   | 说明               |
|---------------|------|--------|--------------------|
| message       | 是   | String | 操作结果消息       |
| code          | 是   | int    | 状态码（0成功）    |
| data          | 是   | Object | 响应数据           |
| ├─ failCount  | 是   | int    | 失败条数           |
| ├─ successCount| 是   | int    | 成功条数           |
| ├─ failReason | 是   | List   | 失败原因列表       |
| └── orderNo   | 是   | String | 失败订单号         |
| └── reason    | 是   | String | 具体失败原因       |

**响应示例**：
```json
{
  "message": "操作成功",
  "code": 0,
  "data": {
    "failCount": 1,
    "successCount": 1,
    "failReason": [{
      "orderNo": "abs",
      "reason": "金额不能为负数"
    }]
  }
}
```

---

### 2. 订单状态变更
#### 2.1 接口描述
- **功能**：泊链在缴费时向三方平台获取订单支付状态
- **调用方**：泊链平台
- **接口地址**：api/provider/park/queryOrdersTag

#### 2.2 请求参数
| 参数名      | 必须 | 类型   | 说明                              |
|-------------|------|--------|-----------------------------------|
| union_id    | 是   | String | 联盟编号                          |
| comid       | 是   | String | 车场编号                          |
| orderList   | 是   | List   | 订单数组                          |
| orderNo  | 是   | String | 订单流水号                        |

**请求示例**：
```json
{
  "union_id": "1002348",
  "comid": "1002348",
  "ownerId": "1",
  "orderNo": "2231580222123",
}
```

#### 2.3 响应参数
| 参数名      | 必须 | 类型   | 说明                              |
|-------------|------|--------|-----------------------------------|
| message    | 是   | String | 联盟编号                          |
| code       | 是   | String | 0成功 其他失败                          |
| data   | 是   | List   | 订单数组                          |
| -orderNo  | 是   | String | 订单流水号                        |
| -status  | 是   | String | 订单状态 ：0 待支付 1 支付中 2 已支付 3 作废 4 支付失败(可继续支付) |

示例：
```json
{
    "message": "操作成功",
    "code": 0,
    "data": {
        "orderNo":"123",
        "status":0
    }
}
```
---

### 3. 订单状态变更（三方→泊链）
#### 3.1 接口描述
- **功能**：推送状态变更（失效/支付中/已支付）
- **调用方**：三方平台
- **接口地址**：
  - 测试环境：`http://ts.bolink.club/zld/arrearsRecovery/updateStatus`
  - 正式环境：`http://yun.bolink.club/zld/arrearsRecovery/updateStatus`

#### 3.2 请求参数
| 参数名      | 必须 | 类型   | 说明                              |
|-------------|------|--------|-----------------------------------|
| union_id    | 是   | String | 联盟编号                          |
| comid       | 是   | String | 车场编号                          |
| orderList   | 是   | List   | 订单数组                          |
| ownerId  | 是   | int    | 业主ID                            |
| orderNo  | 是   | String | 订单流水号                        |
| status   | 是   | String | 状态（同接口2）                   |

**请求示例**：
```json
{
  "union_id": "1002348",
  "comid": "1002348",
  "orderList": [{
    "ownerId": "1",
    "orderNo": "2231580222123",
    "status": 2
  }]
}
```

#### 3.3 响应参数
（同接口1.4响应结构）

---

### 4. 获取订单状态
#### 4.1 接口描述
- **功能**：缴费前查询订单状态
- **调用方**：泊链平台

#### 4.2 请求参数
| 参数名    | 必须 | 类型   | 说明      |
|-----------|------|--------|-----------|
| union_id  | 是   | String | 联盟编号  |
| comid     | 是   | String | 车场编号  |
| ownerId   | 是   | String | 业主ID    |
| orderNo   | 是   | String | 订单号    |

**请求示例**：
```json
{
  "union_id": "1002348",
  "comid": "1002348",
  "ownerId": "1",
  "orderNo": "2231580222123"
}
```

#### 4.3 响应参数
| 参数名    | 必须 | 类型   | 说明                              |
|-----------|------|--------|-----------------------------------|
| message   | 是   | String | 操作结果消息                      |
| code      | 是   | int    | 状态码（0成功）                   |
| data      | 是   | Object | 响应数据                          |
| orderNo| 是   | String | 订单流水号                        |
| status | 是   | int    | 状态（同接口2，含4=可续支付失败） |

**响应示例**：
```json
{
  "message": "操作成功",
  "code": 0,
  "data": {
    "orderNo": "123",
    "status": 0
  }
}
```

```
**关键说明**  
1. 所有接口需按 **1.2节** 进行数据签名和Base64编码  
2. 状态码定义统一：  
  - `0`：待支付  
  - `1`：支付中  
  - `2`：已支付  
  - `3`：作废  
  - `4`：支付失败（可继续支付）
```