26、停车费合单补缴开放接口

# 停车费合单补缴开放接口

## 一、加密步骤

### 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. 格式转换：结果转为大写

**请求示例**：
```json
原始数据：
{
  "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     | 订单组（最多20条）                                                   |
| 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      | 停车时长（分钟）                                                     |
| enterPicUrl    | 否   | String   | 入场照片URL                                                          |
| exitPicUrl     | 否   | String   | 出场照片URL                                                          |
| on            | 否   | String   | 经度                                                                 |
| at            | 否   | String   | 纬度                                                                 |

**请求示例**：
```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/changeStatus`

#### 2.2 请求参数
| 参数名      | 必须 | 类型   | 说明                              |
|-------------|------|--------|-----------------------------------|
| union_id    | 是   | String | 联盟编号                          |
| comid       | 是   | String | 车场编号                          |
| orderList   | 是   | List   | 订单数组                          |
| orderNo  | 是   | String | 订单流水号                        |
| status   | 是   | String | 状态（0待支付/1支付中/2已支付/3作废/4支付失败） |

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

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

---

### 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）                   |
| amount   | 否   | int    | 金额（分）                        |
| payDate  | 否   | String | 支付时间                          |

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

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

---

### 4. 获取订单状态
#### 4.1 接口描述
- **功能**：缴费前查询订单状态
- **调用方**：泊链平台
- **接口地址**：`api/provider/park/queryOrders`

#### 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    | 状态（0待支付/1支付中/2已支付/3作废/4可续支付失败） |

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

```
> **关键说明**  
> 1. 所有接口需按 **1.2节** 进行数据签名和Base64编码  
> 2. 状态码定义统一：  
>    - `0`：待支付  
>    - `1`：支付中  
>    - `2`：已支付  
>    - `3`：作废  
>    - `4`：支付失败（可继续支付）
> 3. 金额单位统一为 **分**
> 4. 时间格式统一为 **yyyy-MM-dd HH:mm:ss**
```