加油站税控加油业务接口文档

# 加油站税控加油业务接口文档

## 通用加密规范

### 加密流程

业务 JSON 明文 -> UTF-8 字节编码 -> AES-128-CBC 加密 -> Base64 编码 -> 赋值外层 `secret_json_data`。

### 解密流程

获取密文字段 `secret_json_data` -> Base64 解码 -> AES-128-CBC 解密 -> UTF-8 解析 JSON 对象。

### 响应外层固定结构

所有接口的 HTTP 响应统一为：

```json
{
  "return_json_data": "Base64密文字符串"
}
```

业务响应明文 JSON 经 AES-128-CBC 加密和 Base64 编码后，放入 `return_json_data` 返回。

### 全局错误码

| code 编码 | 说明 |
| --- | --- |
| 200 | 业务处理成功 |
| 400 | 请求参数错误，缺少 `secret_json_data` |
| 401 | 解密失败，密文、密钥或 IV 不匹配 |
| 404 | 接口不存在或业务参数校验失败 |
| 500 | 服务内部异常 |

## 接口 1 推送税控加油数据

- 请求地址：`https://api.ruishengyi.com/rb-pay/openPlatform/router/oilmachine/{厂家标识}/notify`
- 请求方式：`POST`
- Body 类型：`form-data`

`{厂家标识}` 由平台与厂家在联调前约定；厂家应使用约定的标识拼接接口路径。

### 外层 form-data 请求参数

| 字段名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `secret_json_data` | String | 是 | 加密业务报文密文，Base64 字符串 |

### secret_json_data 内部明文参数

| 参数名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `requestId` | string | 是 | 流水编号，全局唯一；开票成功回调时原样带回该编号用于业务匹配 |
| `stationCode` | string | 是 | 加油站编码 |
| `gunOilNo` | string | 是 | 油枪编号，例如 2 号枪 |
| `fuelDispenserNo` | string | 是 | 加油机编号，例如 1 号加油机 |
| `addOilStartTime` | string | 是 | 加油开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `addOilStopTime` | string | 是 | 加油结束时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `oilVal` | number | 是 | 加油油量 |
| `amount` | number | 是 | 总价 |
| `price` | number | 是 | 单价 |
| `oilProduct` | string | 是 | 油品 |

### 请求明文示例

```json
{
  "requestId": "20260831143025000100000001a3f2d1",
  "stationCode": "1234567890",
  "gunOilNo": "2",
  "fuelDispenserNo": "1",
  "addOilStartTime": "2026-08-31 14:28:10",
  "addOilStopTime": "2026-08-31 14:30:25",
  "oilVal": 35.5,
  "amount": 220,
  "price": 6.8,
  "oilProduct": "92#"
}
```

### return_json_data 解密后响应明文

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 状态码，`200` 成功、`404` 失败 |
| `msg` | string | 返回描述信息 |

成功示例：

```json
{
  "code": "200",
  "msg": "成功"
}
```

失败示例：

```json
{
  "code": "404",
  "msg": "参数校验失败"
}
```

## 接口 2 开票返回

- 请求地址：`{厂家接口网关地址}/api/add_oil_data/invoiceNotify`
- 请求方式：`POST`
- Body 类型：`form-data`

### 外层 form-data 请求参数

| 字段名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `secret_json_data` | String | 是 | 加密业务报文密文，Base64 字符串 |

### secret_json_data 内部明文参数

| 参数名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `requestId` | string | 否 | 流水编号，唯一；有推送时返回推送的编号，自行创建交易订单时无需返回 |
| `stationCode` | string | 是 | 加油站编码 |
| `gunOilNo` | string | 是 | 油枪编号 |
| `fuelDispenserNo` | string | 否 | 加油机编号 |
| `oilVal` | number | 是 | 油量 |
| `amount` | number | 是 | 总价 |
| `price` | number | 是 | 单价 |
| `oilProduct` | string | 是 | 油品 |
| `invoice` | object | 是 | 发票信息对象，具体字段由双方联调确认 |
| `addOilTime` | string | 是 | 加油时间，格式 `yyyy-MM-dd HH:mm:ss` |

### 请求明文示例

```json
{
  "requestId": "20260831143025000100000001a3f2d1",
  "stationCode": "1234567890",
  "gunOilNo": "1",
  "fuelDispenserNo": "01",
  "oilVal": 35.5,
  "amount": 320.45,
  "price": 9.03,
  "oilProduct": "92#汽油",
  "invoice": {},
  "addOilTime": "2026-08-31 14:30:25"
}
```

`invoice` 的子字段由双方联调确认，示例中的空对象仅表示该字段位置。

### return_json_data 解密后响应明文

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 状态码，`200` 成功、`404` 失败 |
| `msg` | string | 返回描述信息 |

成功示例：

```json
{
  "code": "200",
  "msg": "成功"
}
```

## 接口 3 主动查询加油记录

- 请求地址：`{厂家接口网关地址}/api/add_oil_data/queryBmqRecord`
- 请求方式：`POST`
- Body 类型：`form-data`

### 外层 form-data 请求参数

| 字段名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `secret_json_data` | String | 是 | 加密业务报文密文，Base64 字符串 |

### secret_json_data 内部明文参数

| 参数名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `stationCode` | string | 是 | 加油站编码 |
| `gunOilNo` | string | 是 | 油枪编号 |
| `addOilStartTime` | string | 否 | 加油开始时间；为空默认当天 0 点，格式 `yyyy-MM-dd HH:mm:ss` |
| `addOilStopTime` | string | 否 | 加油结束时间；为空默认当天 24 点，格式 `yyyy-MM-dd HH:mm:ss` |

### 请求明文示例

```json
{
  "stationCode": "1234567890",
  "gunOilNo": "1",
  "addOilStartTime": "2026-08-31 00:00:00",
  "addOilStopTime": "2026-08-31 23:59:59"
}
```

### return_json_data 解密后响应明文

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 状态码，`200` 成功、`404` 失败 |
| `msg` | string | 返回描述信息 |
| `oilStatus` | integer | 设备在线状态：`1` 在线，`2` 不在线；值为 `2` 时 `data` 为空 |
| `data` | array[object] | 加油记录数组 |

#### data 数组内对象字段说明

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| `requestId` | string | 流水编号，唯一；有推送时返回推送值，无推送时自行创建 |
| `stationCode` | string | 加油站编码 |
| `fuelDispenserNo` | string | 加油机编号 |
| `gunOilNo` | string | 油枪编号 |
| `addOilStartTime` | string | 加油开始时间 |
| `addOilStopTime` | string | 加油结束时间 |
| `oilProduct` | string | 油品 |
| `price` | number | 单价 |
| `oilVal` | string | 油量 |
| `amount` | string | 总价 |

### 查询成功明文示例

```json
{
  "code": "200",
  "msg": "成功",
  "oilStatus": 1,
  "data": [
    {
      "requestId": "20260831143025000100000001a3f2d1",
      "stationCode": "1234567890",
      "fuelDispenserNo": "01",
      "gunOilNo": "1",
      "addOilStartTime": "2026-08-31 14:28:10",
      "addOilStopTime": "2026-08-31 14:30:25",
      "oilProduct": "92#汽油",
      "price": 9.03,
      "oilVal": "35.50",
      "amount": "320.45"
    }
  ]
}
```

## 接口 4 商户油品油枪查询接口

- 请求地址：`https://api.ruishengyi.com/rb-pay/openPlatform/router/oilmachine/{厂家标识}/fuelInfo`
- 请求方式：`POST`
- Body 类型：`form-data`

### 外层 form-data 请求参数

| 字段名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `secret_json_data` | String | 是 | 加密业务报文密文，Base64 字符串 |

### secret_json_data 内部明文参数

| 参数名 | 类型 | 必填 | 描述说明 |
| --- | --- | --- | --- |
| `stationCode` | string | 是 | 加油站编码，即商户号 |

### 请求明文示例

```json
{
  "stationCode": "8114930554100020"
}
```

### return_json_data 解密后响应明文

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 状态码，`200` 成功、`404` 失败 |
| `msg` | string | 返回描述信息 |
| `data` | array[object] | 油品数组 |

#### data 数组内对象字段说明

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| `shortName` | string | 油品名称，例如 `0#柴油`、`92#汽油`、`95#汽油` |
| `productCode` | string | 油品商品编号 |
| `oilGunList` | Array | 该油品关联的油枪列表 |

#### oilGunList 油枪字段说明

| 参数名 | 类型 | 描述 |
| --- | --- | --- |
| `oilGunNo` | string | 油枪编号 |
| `oilGunName` | string | 油枪名称，例如 1 号枪、2 号枪 |

### 查询成功明文示例

```json
{
  "msg": "成功",
  "data": [
    {
      "oilGunList": [
        {
          "oilGunName": "1号枪",
          "oilGunNo": "811493055410002001"
        }
      ],
      "productCode": "OIL2074797983941136384",
      "shortName": "0#柴油"
    },
    {
      "oilGunList": [
        {
          "oilGunName": "1号枪",
          "oilGunNo": "811493055410002002"
        }
      ],
      "productCode": "OIL2074798657701548032",
      "shortName": "92#汽油"
    },
    {
      "oilGunList": [
        {
          "oilGunName": "1号枪",
          "oilGunNo": "811493055410002003"
        }
      ],
      "productCode": "OIL2074798817303203840",
      "shortName": "95#汽油"
    }
  ],
  "code": "200"
}
```

## 业务交互流程

1. 油站系统调用“推送税控加油数据”上送加油交易，生成唯一的 `requestId`。
2. 需要开票时，服务端调用“开票返回”接口，携带相同的 `requestId` 推送开票信息。
3. 可调用“主动查询加油记录”，按油站、油枪和时间范围查询历史加油交易记录。

## 对接注意事项

- 全部接口统一使用 AES-128-CBC 加密传输，外层固定字段为 `secret_json_data`、`return_json_data`，大小写敏感。
- 加密密钥和 IV 由双方联调确定；填充模式为 `PKCS5Padding`，编码为 UTF-8。
- 加密输出必须为 Base64，禁止输出十六进制字符串。
- `requestId` 全局唯一，作为加油交易和开票业务的关联主键。
- 平台回调地址、厂家接口网关地址、厂家标识和加密参数均以双方联调配置为准；生产环境应使用正式配置。
- 网络超时建议业务侧增加重试机制。