# 中数电动第三方接入API文档

## 目录

- [1. 平台认证](#1-平台认证)
  - [1.1 运营商ID](#11-运营商id)
  - [1.2 请求格式要求](#12-请求格式要求)
  - [1.3 加密说明](#13-加密说明)
  - [1.4 ret 返回值说明](#14-ret-返回值说明)
- [2. 获取Token](#2-获取token)
- [3. 充值档位信息分页列表](#3-充值档位信息分页列表)
- [4. 获取用户信息](#4-获取用户信息)
- [5. 充点券购买](#5-充点券购买)
- [6. 获取充电站列表](#6-获取充电站列表)
- [7. 获取充电站详情与充电终端列表](#7-获取充电站详情与充电终端列表)
- [8. 获取充电终端详情](#8-获取充电终端详情)
- [9. 启动充电](#9-启动充电)
- [10. 停止充电](#10-停止充电)
- [11. 查询充电订单列表](#11-查询充电订单列表)
- [12. 查询充电订单详情](#12-查询充电订单详情)
- [附录：配置模板](#附录配置模板)

---

## 1. 平台认证

### 1.1 运营商ID

运营商ID是平台分配给对应渠道方的唯一代码（长度9位，由数字及大小写字符组成）。

### 1.2 请求格式要求

查询接口和回调接口均需要满足以下格式要求:

- 消息头需配置 `Content-Type` 为 `application/json`; `Authorization` 为 `Bearer token`(平台认证接口用于获取token)
- 入参消息体应由运营商标识(operatorId)、参数内容(data)、时间戳(timeStamp)、自增序列(seq)和数字签名(sig)组成

**入参示例：**

```json
{
  "operatorId": "123456789",
  "data": "mYvffpNoFf4E/ZTC1tOw41TC5OlkEobfAYCm5N8hEusaLUaUIqOrXtdbMrSck0DSmfM7mRuOGMoCQzH0nWPGuw==",
  "timeStamp": "20180120165755",
  "seq": "0001",
  "sig": "D2D584A14F3F284445DF85D0E8C0697C"
}
```

**出参示例：**

```json
{
  "ret": 0,
  "msg": "",
  "data": "uxeKP0ezR5yL8xSg4/ZCDh/N91/u86NXFxd2DrwZVW8zCPYcpl59Twz/yQZ3RaO4rDDrGmkvQignmNEJ+k4PGxdmIC+4fpJ8rU6osSobY+AeA0uueuQ5+eQiWBL6p6v5XMMm91brtK8yfFELYUWQzVcxABnAwK/+dyxtUhqLIxUpkwTEU/4ktN40df9IzzlLO5uvUknPGYu9yL0pp5w9vdRxmA1RiiTDNCysz6klr9bunGV3VJa2qpLcgeZMf/oG",
  "sig": "58E52010C7DEE87FE183B0AFA5B2BE30"
}
```

### 1.3 加密说明

- `data` 里的内容为接口的实际入参和出参，均需要密文传输
- 加解密方法为 AES 128位加解密，加解密模式为 CBC，填充模式为 PKCS5Padding
- 签名(sig)采用 HMAC-MD5算法，采用MD5作为散列函数，通过签名密钥(sigSecret)对整个消息主体各参数的值拼接后进行加密
- 入参拼接顺序为: `operatorId + data + timeStamp + seq`
- 出参拼接顺序为: `ret + msg + data`
- ⚠️ 注意：参数签名必须大写

### 1.4 ret 返回值说明

| 返回码 | 说明 |
|--------|------|
| 0 | 请求成功 |
| 500 | 系统错误 |
| 4001 | 签名错误 |
| 4002 | token错误 |
| 4003 | 参数不合法，缺少必需的参数：operatorId、sig、timeStamp、data、seq |
| 4004 | 请求的业务参数不合法，各接口定义自己的必须参数 |

---

## 2. 获取Token

### 2.1 接口描述

- **接口名称：** query_token
- **接口说明：** Token作为全局唯一凭证，调用各接口时均需要使用
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_token`

### 2.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| operatorId | 运营商标识 | String | 请求方唯一编号 | 是 |
| operatorSecret | 运营商密钥 | String | 被调用方分配的唯一识别密钥 | 是 |

### 2.3 请求示例

**data加密前：**

```json
{
  "operatorId": "123456789",
  "operatorSecret": "1234567890abcdef"
}
```

### 2.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| operatorId | 运营商标识 | String | 运营商唯一标识 |
| resultStatus | 操作结果标识 | Integer | 0-成功，1-失败 |
| accessToken | 访问令牌 | String | token令牌 |
| tokenExpirationTime | token有效期 | Integer | 有效期，单位秒 |
| failReason | 失败原因 | Integer | 0-无，1-operatorId无效 |

### 2.5 返回示例

**data解密后：**

```json
{
  "operatorId": "123456789",
  "resultStatus": 0,
  "accessToken": "kVnStIRknCCOBdXgJrmu8rb3pcccifKW2NcQrysKKIzb7iQBxkkjeq3WoGdjgrIL",
  "tokenExpirationTime": 7200,
  "failReason": 0
}
```

---

## 3. 充值档位信息分页列表

### 3.1 接口描述

- **接口名称：** query_recharge_level_page
- **接口说明：** 第三方获取充值档位分页数据
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_recharge_level_page`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 3.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|------|------|----------|
| pageNum | 页码 | Long | 页码，默认1 | 否 |
| pageSize | 每页记录数 | Long | 每页记录数，默认10 | 否 |

### 3.3 请求示例

**data加密前：**

```json
{
  "pageNum": 1,
  "pageSize": 10
}
```

### 3.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型    | 描述 |
|----------|----------|---------|------|
| total | 总记录数 | Long    | 总记录数 |
| pageNum | 当前页码 | Long    | 当前页码 |
| pageSize | 每页记录数 | Long    | 每页记录数 |
| pages | 总页数 | Long    | 总页数 |
| records | 数据列表 | Array   | 充值档位列表 |

**records 数组元素：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| id | 档位ID | Long | 档位ID |
| name | 档位名称 | String | 充值档位名称 |
| money | 充值金额 | BigDecimal | 充值金额 |
| status | 状态 | Integer | 0-不可用，1-可用 |
| tips | 充值提示 | String | 充值提示 |

### 3.5 返回示例

**data解密后：**

```json
{
  "total": 5,
  "pageNum": 1,
  "pageSize": 10,
  "pages": 1,
  "records": [
    {
      "id": 1,
      "name": "10元档位",
      "money": 10.00,
      "status": 1,
      "tips": "此券可以用于抵扣充电费用"
    }
  ]
}
```

---

## 4. 获取用户信息

### 4.1 接口描述

- **接口名称：** query_user_info
- **接口说明：** 第三方根据手机号获取用户信息
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_user_info`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 4.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| phone | 手机号 | String | 用户手机号 | 是 |

### 4.3 请求示例

**data加密前：**

```json
{
  "phone": "13800138000"
}
```

### 4.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| isNewUser | 是否新用户 | Integer | 0-否，1-是 |
| userInfo | 用户信息 | Object | 用户基本信息 |
| accountInfo | 账户信息 | Object | 用户账户信息 |

**userInfo 对象：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| userId | 用户ID | Long | 用户ID |
| nickName | 昵称 | String | 用户昵称 |
| phone | 手机号 | String | 用户手机号 |
| openid | 微信openid | String | 微信openid |

**accountInfo 对象：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| accountId | 账户ID | Long | 账户ID |
| balance | 可用抵用券余额 | BigDecimal | 可用抵用券余额 |
| redeemBalance | 兑换余额 | BigDecimal | 兑换余额 |
| integral | 积分 | BigDecimal | 积分 |

### 4.5 返回示例

**data解密后：**

```json
{
  "isNewUser": 0,
  "userInfo": {
    "userId": 10001,
    "nickName": "张三",
    "phone": "13800138000",
    "openid": "oXyZ123456"
  },
  "accountInfo": {
    "accountId": 20001,
    "balance": 100.00,
    "redeemBalance": 50.00,
    "integral": 500.00
  }
}
```

---

## 5. 充点券购买

### 5.1 接口描述

- **接口名称：** charge_order_pay
- **接口说明：** 第三方充点券购买
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/charge_order_pay`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 5.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| levelId | 充值档位ID | Long | 充值档位ID | 是 |
| userId | 用户ID | Long | 用户ID | 是 |
| phone | 手机号 | String | 用户手机号 | 是 |
| orderNo | 订单号 | String | 第三方订单号 | 是 |
| payTime | 支付时间 | String | 支付时间 | 是 |
| totalMoney | 总金额 | String | 充值总金额 | 是 |

### 5.3 请求示例

**data加密前：**

```json
{
  "levelId": 1,
  "userId": 10001,
  "phone": "13800138000",
  "orderNo": "TP2024031600001",
  "payTime": "2024-03-16 10:30:00",
  "totalMoney": "100.00"
}
```

### 5.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| result | 充值结果 | Integer | 0-成功，1-失败 |
| message | 结果消息 | String | 结果描述 |
| userId | 用户ID | Long | 用户ID |
| rechargeMoney | 充值金额 | BigDecimal | 实际充值金额 |
| balanceAfter | 充值后余额 | BigDecimal | 充值后账户余额 |
| orderNo | 第三方订单号 | String | 第三方订单号 |

### 5.5 返回示例

**data解密后：**

```json
{
  "result": 0,
  "message": "充值成功",
  "userId": 10001,
  "rechargeMoney": 100.00,
  "balanceAfter": 200.00,
  "orderNo": "TP2024031600001"
}
```

---

## 6. 获取充电站列表

### 6.1 接口描述

- **接口名称：** query_charge_station_list
- **接口说明：** 第三方获取充电站列表
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_charge_station_list`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 6.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型       | 描述 | 是否必填 |
|----------|----------|------------|------|----------|
| pageNum | 页码 | Long       | 页码，默认1 | 否 |
| pageSize | 每页记录数 | Long       | 每页记录数，默认10 | 否 |
| sortType | 请求类别 | Integer    | 1-离我最近、2-空闲最多、3-电费最低 | 否 |
| longitude | 经度 | BigDecimal | 用户当前位置经度 | 否 |
| latitude | 纬度 | BigDecimal | 用户当前位置纬度 | 否 |

### 6.3 请求示例

**data加密前：**

```json
{
  "pageNum": 1,
  "pageSize": 10,
  "sortType": 1,
  "longitude": 116.404,
  "latitude": 39.915
}
```

### 6.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型  | 描述 |
|----------|----------|-------|------|
| total | 总记录数 | Long  | 总记录数 |
| pageNum | 当前页码 | Long  | 当前页码 |
| pageSize | 每页大小 | Long  | 每页大小 |
| pages | 总页数 | Long  | 总页数 |
| list | 站点列表 | Array | 充电站列表 |

**list 数组元素：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| stationId | 站点ID | Long | 充电站ID |
| stationName | 站点名称 | String | 充电站名称 |
| tips | 提示语 | String | 站点提示信息 |
| distance | 距离 | BigDecimal | 距离（km） |
| fastCharging | 快充 | String | 格式：空闲/总数 |
| slowCharging | 慢充 | String | 格式：空闲/总数 |
| peakValue | 当前峰值 | String | 当前峰值 |
| peakTime | 峰时段时间 | String | 峰时段时间 |
| periodFlag | 时段标志 | Integer | 1-尖，2-峰，3-平，4-谷 |
| platformPrice | 平台价 | BigDecimal | 平台价格 |

### 6.5 返回示例

**data解密后：**

```json
{
  "total": 50,
  "pageNum": 1,
  "pageSize": 10,
  "pages": 5,
  "list": [
    {
      "stationId": 1,
      "stationName": "XX充电站",
      "tips": "充电减免2小时停车费",
      "distance": 1.5,
      "fastCharging": "5/10",
      "slowCharging": "3/8",
      "peakValue": "1.2元/度",
      "peakTime": "10:00-13:00",
      "periodFlag": 2,
      "platformPrice": 1.20
    }
  ]
}
```

---

## 7. 获取充电站详情与充电终端列表

### 7.1 接口描述

- **接口名称：** query_charge_station_detail
- **接口说明：** 第三方获取充电站详情与充电设备列表
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_charge_station_detail`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 7.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| stationId | 充电站ID | Long | 充电站ID | 是 |
| longitude | 经度 | BigDecimal | 用户当前位置经度 | 否 |
| latitude | 纬度 | BigDecimal | 用户当前位置纬度 | 否 |

### 7.3 请求示例

**data加密前：**

```json
{
  "stationId": 1,
  "longitude": 116.404,
  "latitude": 39.915
}
```

### 7.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| stationId | 站点ID | Long | 充电站ID |
| stationName | 站点名称 | String | 充电站名称 |
| tips | 提示语 | String | 标签提示信息 |
| distance | 距离 | BigDecimal | 距离（km） |
| address | 详细地址 | String | 充电站详细地址 |
| longitude | 经度 | BigDecimal | 站点经度 |
| latitude | 纬度 | BigDecimal | 站点纬度 |
| pictures | 站点图片 | String | 站点图片列表(JSON数组) |
| currentPrice | 当前价 | BigDecimal | 当前价（元/度） |
| currentPeriod | 当前时段 | String | 当前时段描述 |
| originalPrice | 原价 | BigDecimal | 原价/划线价（元/度） |
| periodFlag | 时段标志 | Integer | 1-尖，2-峰，3-平，4-谷 |
| idleCount | 空闲终端数 | Integer | 空闲终端数量 |
| occupiedCount | 占用终端数 | Integer | 占用终端数量 |
| offlineCount | 离线终端数 | Integer | 离线终端数量 |
| businessHours | 营业时间 | String | 营业时间 |
| serviceProvider | 服务提供方 | String | 服务提供方名称 |
| invoiceProvider | 发票提供方 | String | 发票提供方名称 |
| customerServiceHotline | 客服热线 | String | 客服电话 |
| connectorList | 充电终端列表 | Array | 充电终端信息列表 |

**connectorList 数组元素：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| connectorId | 充电终端ID | Long | 充电终端ID |
| connectorName | 终端名称 | String | 终端名称 |
| equipmentType | 终端分类 | String | 终端分类描述 |
| connectorCode | 终端编码 | String | 终端编码 |
| status | 状态 | Integer | 0-离线，1-空闲，2-占用 |
| statusName | 状态名称 | String | 状态描述 |

### 7.5 返回示例

**data解密后：**

```json
{
  "stationId": 1,
  "stationName": "XX充电站",
  "tips": "充电减免2小时停车费，超出部分按每小时3元计费",
  "distance": 1.5,
  "address": "北京市朝阳区XX路XX号",
  "longitude": 116.404,
  "latitude": 39.915,
  "pictures": "[\"http://xxx.com/1.jpg\"]",
  "currentPrice": 1.20,
  "currentPeriod": "峰10:00-13:00",
  "originalPrice": 1.50,
  "periodFlag": 2,
  "idleCount": 5,
  "occupiedCount": 3,
  "offlineCount": 2,
  "businessHours": "周一至周日 00:00-24:00",
  "serviceProvider": "XX充电服务",
  "invoiceProvider": "XX科技有限公司",
  "customerServiceHotline": "400-XXX-XXXX",
  "connectorList": [
    {
      "connectorId": 101,
      "connectorName": "101号直流充电桩",
      "equipmentType": "直流设备",
      "connectorCode": "CONN001",
      "status": 1,
      "statusName": "空闲"
    }
  ]
}
```

---

## 8. 获取充电终端详情

### 8.1 接口描述

- **接口名称：** query_charge_device_detail
- **接口说明：** 第三方获取充电终端详情
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_charge_device_detail`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 8.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| id | 设备主键ID | Long | 设备主键ID | 否 |
| equipmentId | 设备编码 | String | 设备编码 | 否 |

> 注：id 和 equipmentId 至少传一个

### 8.3 请求示例

**data加密前：**

```json
{
  "id": 101,
  "equipmentId": "EQ001"
}
```

### 8.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| connectorId | 充电设备接口ID | Long | 充电设备接口ID |
| connectorCode | 充电设备接口编码 | String | 充电设备接口编码 |
| connectorName | 充电设备接口名称 | String | 充电设备接口名称 |
| stationId | 充电站ID | Long | 所属充电站ID |
| stationName | 充电站名称 | String | 所属充电站名称 |
| stationAddress | 充电站地址 | String | 所属充电站地址 |
| equipmentId | 设备ID | Long | 设备ID |
| equipmentCode | 设备编码 | String | 设备编码 |
| equipmentName | 设备名称 | String | 设备名称 |
| equipmentType | 设备类型 | Integer | 1-直流设备，2-交流设备，3-交直流一体设备，4-无线设备，5-其他 |
| equipmentTypeName | 设备类型名称 | String | 设备类型描述 |
| parkNo | 车位号 | String | 车位号 |
| status | 终端状态 | Integer | 0-离网，1-空闲，2-占用(未充电)，3-占用(充电中)，4-占用(预约锁定)，255-故障 |
| statusName | 终端状态名称 | String | 终端状态描述 |
| connectorType | 接口类型 | Integer | 1-家用插座，2-交流接口插座，3-交流接口插头，4-直流接口枪头，5-无线充电座，6-其他 |
| connectorTypeName | 接口类型名称 | String | 接口类型描述 |
| voltageUpperLimits | 额定电压上限 | Integer | 单位V |
| voltageLowerLimits | 额定电压下限 | Integer | 单位V |
| current | 额定电流 | Integer | 单位A |
| power | 额定功率 | BigDecimal | 单位kW |
| nationalStandard | 国家标准 | Integer | 1-2011，2-2015 |
| nationalStandardName | 国家标准名称 | String | 国家标准描述 |
| currentPrice | 常规价格 | BigDecimal | 元/度（电价+服务费+常规运营费+增值费用） |
| periodFlag | 时段标志 | Integer | 1-尖，2-峰，3-平，4-谷 |
| currentPeriodDesc | 当前时段描述 | String | 当前时段描述 |
| parkingTips | 停车费说明 | String | 提示语/停车费说明 |

### 8.5 返回示例

**data解密后：**

```json
{
  "connectorId": 101,
  "connectorCode": "CONN001",
  "connectorName": "101号充电口",
  "stationId": 1,
  "stationName": "XX充电站",
  "stationAddress": "北京市朝阳区XX路XX号",
  "equipmentId": 10,
  "equipmentCode": "EQ001",
  "equipmentName": "1号直流充电桩",
  "equipmentType": 1,
  "equipmentTypeName": "直流设备",
  "parkNo": "A001",
  "status": 1,
  "statusName": "空闲",
  "connectorType": 4,
  "connectorTypeName": "直流接口枪头",
  "voltageUpperLimits": 750,
  "voltageLowerLimits": 200,
  "current": 250,
  "power": 120.00,
  "nationalStandard": 2,
  "nationalStandardName": "2015",
  "currentPrice": 1.20,
  "periodFlag": 2,
  "currentPeriodDesc": "峰时段 10:00-13:00",
  "parkingTips": "充电减免2小时停车费"
}
```

---

## 9. 启动充电

### 9.1 接口描述

- **接口名称：** invoke_charge
- **接口说明：** 第三方启动充电
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/invoke_charge`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 9.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| equipmentId | 充电桩编号 | String | 充电桩编号 | 是 |
| stationId | 第三方充电站ID | String | 充电站ID | 是 |
| connectorId | 充电设备接口编码 | String | 充电设备接口编码 | 是 |
| channelOrderNo | 渠道方订单编号 | String | 第三方平台订单编号 | 是 |
| channelUserPhone | 渠道方用户手机号 | String | 用户手机号 | 是 |
| channelPreAmt | 渠道方预支付金额 | BigDecimal | 预支付金额 | 是 |

### 9.3 请求示例

**data加密前：**

```json
{
  "equipmentId": "EQ001",
  "stationId": "1",
  "connectorId": "CONN001",
  "channelOrderNo": "CH2024031600001",
  "channelUserPhone": "13800138000",
  "channelPreAmt": 100.00
}
```

### 9.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| result | 启动结果 | Integer | 0-成功，1-失败 |
| message | 结果消息 | String | 结果描述 |
| chargeOrderId | 充电订单ID | Long | 平台充电订单ID |
| chargeOrderNo | 充电订单编号 | String | 平台充电订单编号 |
| status | 充电状态 | Integer | 0-待启动，1-充电中，2-结算中，3-已完成，5-未成功充电 |

### 9.5 返回示例

**data解密后：**

```json
{
  "result": 0,
  "message": "启动充电成功",
  "chargeOrderId": 100001,
  "chargeOrderNo": "CD2024031600001",
  "status": 1
}
```

---

## 10. 停止充电

### 10.1 接口描述

- **接口名称：** stop_charge
- **接口说明：** 第三方停止充电
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/stop_charge`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 10.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| chargeOrderNo | 充电订单编号 | String | 平台充电订单编号 | 是 |

### 10.3 请求示例

**data加密前：**

```json
{
  "chargeOrderNo": "CD2024031600001"
}
```

### 10.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| result | 停止结果 | Integer | 0-成功，1-失败 |
| message | 结果消息 | String | 结果描述 |
| chargeOrderId | 充电订单ID | Long | 平台充电订单ID |
| chargeOrderNo | 充电订单编号 | String | 平台充电订单编号 |
| status | 充电状态 | Integer | 0-待启动，1-充电中，2-结算中，3-已完成，5-未成功充电 |

### 10.5 返回示例

**data解密后：**

```json
{
  "result": 0,
  "message": "停止充电成功",
  "chargeOrderId": 100001,
  "chargeOrderNo": "CD2024031600001",
  "status": 2
}
```

---

## 11. 查询充电订单列表

### 11.1 接口描述

- **接口名称：** query_charge_order_list
- **接口说明：** 第三方查询充电订单列表（只查询渠道类型订单）
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_charge_order_list`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 11.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型   | 描述 | 是否必填 |
|----------|----------|--------|------|----------|
| operatorId | 运营商ID | String | 运营商唯一标识 | 是 |
| userId | 用户ID | Long   | 用户ID | 否 |
| chargeOrderNo | 充电订单号 | String | 充电订单号 | 否 |
| pageNo | 页码 | Long   | 页码，默认1 | 否 |
| pageSize | 每页记录数 | Long   | 每页记录数，默认10 | 否 |

### 11.3 请求示例

**data加密前：**

```json
{
  "operatorId": "123456789",
  "userId": 10001,
  "pageNo": 1,
  "pageSize": 10
}
```

### 11.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型    | 描述 |
|----------|----------|---------|------|
| total | 总记录数 | Long    | 总记录数 |
| pageNo | 当前页码 | Long    | 当前页码 |
| pageSize | 每页记录数 | Long    | 每页记录数 |
| pages | 总页数 | Long    | 总页数 |
| records | 数据列表 | Array   | 订单列表 |

**records 数组元素：**

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| id | 订单ID | Long | 订单ID |
| userId | 用户ID | Long | 用户ID |
| chargeOrderNo | 充电订单号 | String | 充电订单号 |
| equipmentId | 充电桩编号 | String | 充电桩编号 |
| connectorId | 充电设备接口编码 | String | 充电设备接口编码 |
| stationName | 充电站名称 | String | 充电站名称 |
| connectorName | 充电设备接口名称 | String | 充电设备接口名称 |
| startTime | 充电开始时间 | String | 充电开始时间 |
| endTime | 充电结束时间 | String | 充电结束时间 |
| chargeTime | 充电时长 | Integer | 充电时长（秒） |
| totalCharge | 实际充电度数 | BigDecimal | 单位：kW/h |
| status | 订单状态 | Integer | 0-待启动，1-充电中，2-结算中，3-已完成，5-未成功充电 |
| preAmt | 预充值金额 | BigDecimal | 预充值金额 |
| phoneNum | 手机号 | String | 用户手机号 |
| plateNum | 车牌号 | String | 车牌号 |
| stopType | 停止类型 | Integer | 1-主动停止，2-充满停止，3-余额不足停止，4-电桩按钮停止 |
| stopReason | 停止原因 | String | 停止原因描述 |
| createTime | 创建时间 | String | 订单创建时间 |

### 11.5 返回示例

**data解密后：**

```json
{
  "total": 100,
  "pageNo": 1,
  "pageSize": 10,
  "pages": 10,
  "records": [
    {
      "id": 100001,
      "userId": 10001,
      "chargeOrderNo": "CD2024031600001",
      "equipmentId": "EQ001",
      "connectorId": "CONN001",
      "stationName": "XX充电站",
      "connectorName": "101号充电口",
      "startTime": "2024-03-16 10:00:00",
      "endTime": "2024-03-16 11:30:00",
      "chargeTime": 5400,
      "totalCharge": 30.50,
      "status": 3,
      "preAmt": 100.00,
      "phoneNum": "13800138000",
      "plateNum": "京A12345",
      "stopType": 2,
      "stopReason": "充满停止",
      "createTime": "2024-03-16 10:00:00"
    }
  ]
}
```

---

## 12. 查询充电订单详情

### 12.1 接口描述

- **接口名称：** query_charge_order_info
- **接口说明：** 第三方查询充电订单详情（只查询渠道类型订单）
- **请求格式：** JSON
- **请求方式：** POST
- **接口路径：** `/third-party/v1/query_charge_order_info`
- **认证方式：** 需要在Header中携带 `Authorization: Bearer {accessToken}`

### 12.2 输入参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 | 是否必填 |
|----------|----------|----------|------|----------|
| chargeOrderNo | 充电订单号 | String | 充电订单号 | 是 |

### 12.3 请求示例

**data加密前：**

```json
{
  "chargeOrderNo": "CD2024031600001"
}
```

### 12.4 返回参数（data解密后）

| 参数名称 | 参数定义 | 参数类型 | 描述 |
|----------|----------|----------|------|
| result | 查询结果 | Integer | 0-成功，1-失败 |
| message | 失败原因 | String | 失败原因描述 |
| id | 订单ID | Long | 订单ID |
| userId | 用户ID | Long | 用户ID |
| chargeOrderNo | 充电订单号 | String | 充电订单号 |
| equipmentId | 充电桩编号 | String | 充电桩编号 |
| connectorId | 充电设备接口编码 | String | 充电设备接口编码 |
| stationName | 充电站名称 | String | 充电站名称 |
| connectorName | 充电设备接口名称 | String | 充电设备接口名称 |
| startTime | 充电开始时间 | String | 充电开始时间 |
| endTime | 充电结束时间 | String | 充电结束时间 |
| chargeTime | 充电时长 | Integer | 充电时长（秒） |
| totalCharge | 实际充电度数 | BigDecimal | 单位：kW/h |
| status | 订单状态 | Integer | 0-待启动，1-充电中，2-结算中，3-已完成，5-未成功充电 |
| preAmt | 预充值金额 | BigDecimal | 预充值金额 |
| phoneNum | 手机号 | String | 用户手机号 |
| plateNum | 车牌号 | String | 车牌号 |
| stopType | 停止类型 | Integer | 1-主动停止，2-充满停止，3-余额不足停止，4-电桩按钮停止 |
| stopReason | 停止原因 | String | 停止原因描述 |
| createTime | 创建时间 | String | 订单创建时间 |

### 12.5 返回示例

**data解密后：**

```json
{
  "result": 0,
  "message": "",
  "id": 100001,
  "userId": 10001,
  "chargeOrderNo": "CD2024031600001",
  "equipmentId": "EQ001",
  "connectorId": "CONN001",
  "stationName": "XX充电站",
  "connectorName": "101号充电口",
  "startTime": "2024-03-16 10:00:00",
  "endTime": "2024-03-16 11:30:00",
  "chargeTime": 5400,
  "totalCharge": 30.50,
  "status": 3,
  "preAmt": 100.00,
  "phoneNum": "13800138000",
  "plateNum": "京A12345",
  "stopType": 2,
  "stopReason": "充满停止",
  "createTime": "2024-03-16 10:00:00"
}
```

---

## 附录：配置模板

对接需要配置以下参数，由平台给第三方平台提供这些参数信息：

| 参数名称 | 参数定义 | 参数说明 | 是否必填 | 备注                              |
|----------|----------|----------|----------|---------------------------------|
| operatorId | 运营商ID | 平台分配给对应渠道方的唯一代码（长度9位，由数字及大小写字符组成） | 是 | 用于标识运营商身份                       |
| apiBaseUrl | 接口地址 | 平台提供的API接口基础地址 | 是 | 例如: https://cd.admin.zswlgz.com |
| operatorSecret | 运营商密钥 | 用于获取Token的密钥，由对方平台分配 | 是 | 用于申请认证                          |
| sigSecret | 签名密钥 | 用于生成和验证消息签名的密钥 | 是 | 用于HMAC-MD5签名算法                  |
| dataSecret | 数据密钥 | 用于AES加密和解密数据的密钥 | 是 | 16位密钥，用于data字段加解密               |
| dataSecretIV | 数据加密向量 | AES加密算法使用的初始化向量(IV) | 是 | 16字节向量，用于CBC模式加密                |

**配置示例：**

```json
{
  "operatorId": "123456789",
  "apiBaseUrl": "https://cd.admin.zswlgz.com",
  "operatorSecret": "your_operator_secret_key",
  "sigSecret": "your_sign_secret_key",
  "dataSecret": "your_data_encryption_key",
  "dataSecretIV": "your_data_iv_vector"
}
```

> ⚠️ **重要提示：**
> - 以上所有参数由平台提供给第三方平台
> - 密钥信息需要严格保密，不得泄露
> - 配置参数需要双方确认无误后再进行接口对接