# 慧明宝供应链平台 · Java 对接示例

对接方（下单平台）调用慧明宝接口的完整示例，与平台 PHP 端口径一一对应。

配套文档：《慧明宝供应链平台接口文档 V1.0.17》。本示例等价于平台自带的联调脚本 `qyt_test.php`。

---

## 一、对接链路

```mermaid
flowchart LR
    subgraph A["你方（下单平台）"]
        A1["业务系统"]
    end
    subgraph B["慧明宝平台"]
        B1["开放接口<br/>partners.php"]
        B2["发放队列"]
        B3["回调队列"]
    end
    subgraph C["上游油品平台（企油通）"]
        C1["运单油费下发"]
        C2["司机加油"]
    end

    A1 -->|"① 分油 share<br/>RSA+AES 加密"| B1
    B1 -->|"② 同步返回 oilCardNo<br/>（仅代表受理）"| A1
    B1 --> B2
    B2 -->|"③ 下发油费"| C1
    C1 -->|"④ 查发放结果"| B2
    B2 -->|"⑤ 通知 share_oil"| A1
    C2 -->|"⑥ 加油消费推送"| B3
    B3 -->|"⑦ 通知 add_oil（每笔一次）"| A1
    A1 -->|"⑧ 退款 refund（可选）"| B1
    B1 -->|"⑨ 通知 refund"| A1
```

不看图的话，一句话版本：**分油是异步的**。同步返回只代表平台受理，真正到账要等 `share_oil` 通知，或自己查订单状态。

```mermaid
sequenceDiagram
    participant Y as 你方系统
    participant P as 慧明宝平台
    participant Q as 企油通

    Y->>P: share 分油（金额/司机/身份证/车牌）
    P-->>Y: code=00 + oilCardNo（受理）
    P->>Q: 运单油费下发
    Q-->>P: 受理
    P->>Q: 查发放结果（轮询）
    Q-->>P: 发放成功
    P-->>Y: 通知 optType=share_oil
    Note over Y,P: 此时 oil_status_zsy=2，油费才真正到账

    Q-->>P: 司机加油（一单可多次）
    P-->>Y: 通知 optType=add_oil（每笔推一次）

    opt 司机没加完，需要退款
        Y->>P: refund 退款
        P->>Q: 调低司机凭证额度
        P-->>Y: 通知 optType=refund
    end
```

---

## 二、快速开始

```bash
mvn -q compile exec:java -Dexec.mainClass=com.hmb.openapi.demo.ShareDemo
```

运行前改 `ShareDemo.java` 顶部 5 个配置（平台分配）：

| 配置 | 说明 |
|---|---|
| `BASE_URL` | 接口域名，不含结尾斜杠 |
| `APP_KEY` | 平台分配的 appKey |
| `ORG_NO` | 公司编号，作为业务参数 `orgNo` |
| `PARTNER_PRIVATE_KEY` | **你方**私钥，PKCS#8 一行 base64，用于加签 |
| `PLATFORM_PUBLIC_KEY` | **平台**公钥，X.509 一行 base64，用于加密与验签回调 |

私钥若是 PKCS#1（`-----BEGIN RSA PRIVATE KEY-----`），Java 读不了，先转换：

```bash
openssl pkcs8 -topk8 -inform PEM -in old.pem -outform PEM -nocrypt -out pkcs8.pem
```

### 目录结构

```
src/main/java/com/hmb/openapi/
├── HmbConfig.java           配置与地址拼接
├── HmbCrypto.java           签名、加解密、PHP 兼容的 urlencode
├── JsonPhp.java             请求体序列化（必须与 PHP 口径一致）
├── HmbApiClient.java        五个业务接口
├── HmbResponse.java         响应封装
├── HmbNotifyVerifier.java   接收油卡变动通知（解密 + 验签）
└── demo/
    ├── ShareDemo.java            下单 → 查状态 → 取加油地址
    └── NotifyControllerDemo.java 接收通知的 Spring 示例
```

---

## 三、请求地址

**域名 + `/partners.php` + 接口路径**。平台没配 URL 重写，中间的入口文件不能省。

| 接口 | method（请求头） | 路径 |
|---|---|---|
| 用户分油 | `syb.oil.oilCard.share` | `/oilCard/share` |
| 订单状态查询 | `syb.oil.oilCard.orderStatus` | `/oilCard/orderStatus` |
| 订单退款 | `syb.oil.oilCard.refund` | `/oilCard/refund` |
| 付款码申请 | `syb.pay.qrCode.request` | `/oilCard/getPayQrCode` |
| 分油记录查询 | `syb.oil.oilCard.shareList` | `/oilCard/shareList` |
| 合作商余额查询 | `syb.oil.account.balance` | `/oilCard/balance` |
| 司机可用额度 | `syb.oil.driver.quota` | `/oilCard/driverQuota` |

例：`http://47.104.73.7/partners.php/oilCard/share`

---

## 四、报文结构

### 请求

请求头（自定义 HTTP 头）：

| 头 | 说明 |
|---|---|
| `version` | 固定 `1.0.0` |
| `appKey` | 平台分配 |
| `method` | 接口标识，填错返回 `0005` |
| `requestId` | **必须全局唯一**，重复返回 `0012` |
| `sign` | 见下方加签步骤 |

请求体（业务参数不出现在明文里）：

```json
{"key": "RSA加密后的AES密钥(base64)", "data": "AES加密后的业务报文(base64)"}
```

### 加签与加密（顺序不能变）

1. 业务参数序列化成 `bodyJson`（PHP 口径，见「六、常见坑」第 2 条）
2. 拼待签串：`http_build_query([version, appKey, method, requestId, body])`
3. `SHA256withRSA` 用**你方私钥**签名，base64 → 放进请求头 `sign`
4. 随机 32 字节 AES 密钥，`AES-256-ECB/PKCS5Padding` 加密 `bodyJson`，base64 → `data`
5. 用**平台公钥** `RSA/ECB/PKCS1Padding` 加密该 AES 密钥，base64 → `key`

待签串长这样（注意 body 整体被 urlencode 了）：

```
version=1.0.0&appKey=abc&method=syb.oil.oilCard.share&requestId=abcXXXX&body=%7B%22orgNo%22%3A%22U230%22%2C%22name%22%3A%22%E5%BC%A0%E4%B8%89%22%7D
```

### 响应

平台响应是**明文 JSON，不加密**：

```json
{"code":"00","message":"请求成功","errCode":null,"errMessage":null,"data":{"oilCardNo":"OIL1756...","amount":"100.00"}}
```

`code=00` 为成功，否则看 `errCode` / `errMessage`。

---

## 五、接口字段

### 5.1 用户分油 share

| 参数 | 必填 | 说明 |
|---|---|---|
| `orgNo` | 是 | 公司编号 |
| `amount` | 是 | 分油金额（元），最多两位小数且大于 0 |
| `mobile` | 是 | 司机手机号 |
| `name` | 是 | 司机姓名，用于上游实名二要素核验 |
| `idCard` | 是 | 司机身份证号，18 位 |
| `plateNo` | 是 | 车牌号，平台侧留存展示，**不上送上游** |
| `saleOrderNo` | 是 | 你方内部销售单号，**同一单号重复提交返回原订单（幂等）** |
| `oilCardType` | 是 | 固定 `zsy_ticket` |

返回 `data`：`oilCardNo`（油卡编号，后续接口都用它）、`amount`。

### 5.2 订单状态查询 orderStatus

入参 `orgNo` + `oilCardNo`。关键返回字段：

| 字段 | 说明 |
|---|---|
| `oil_status_zsy` | **0 未提交 / 1 发放中 / 2 发放成功 / 3 发放失败**。只有 2 才是真正到账 |
| `used_amount` | 已加油金额（一单可多次加油，累计值） |
| `used_num` | 加油次数 |
| `remain_amount` | 剩余金额 = 分油金额 − 已加油 − 已退款，未退款时即可退金额 |
| `refund_status` | 0 未退款 / 1 退款中 / 2 已退款 / 3 退款失败 / 4 退款结果确认中 |
| `use_status` | 0 未加油 / 1 有加油记录（可能只加了一部分） |

### 5.3 订单退款 refund

入参 `orgNo` + `oilCardNo` + `reason`（选填）。

- 退款金额**固定为剩余未加油金额**，不能指定，已加油部分不退
- 每单只能成功退一次
- 返回 `refundStatus=2` 成功；`=4` 表示结果确认中，**此时切勿重复发起**，稍后查订单状态或等 `refund` 通知

---

## 六、常见坑

**1. `http_build_query` 的编码规则和 Java `URLEncoder` 不一样**

Java 的 `URLEncoder` 不编码 `*`，PHP 会编成 `%2A`；报文里只要出现一个这样的字符，验签就失败。本示例用 `HmbCrypto.phpUrlEncode()` 复刻了 PHP 规则：只有 `A-Z a-z 0-9 - _ .` 原样保留，空格编成 `+`，其余按 UTF-8 编成 `%XX` 大写十六进制。

**2. 请求体 JSON 里的 `/` 必须转义成 `\/`**

平台收到后会把 body 反序列化再**重新序列化**去验签，用的是 PHP `json_encode($body, JSON_UNESCAPED_UNICODE)`，它默认转义斜杠，而 Java 的 JSON 库不会。备注里带个日期 `2026/09/29` 就会对不上。所以请求体请用本示例的 `JsonPhp.encode()`，**不要**换成 Jackson/Gson。中文要原样输出，不能转 `\uXXXX`。

**3. `requestId` 必须全局唯一**

平台按它拦重复请求，重复返回 `0012`。

**4. 分油是异步的**

同步返回只代表受理。真正到账看 `oil_status_zsy=2`，或等 `share_oil` 通知。

**5. 一张订单可以分多次加油**

每笔加油单独推一次 `add_oil` 通知，`amount` 是**本次**占用金额，`orderAmount` 才是订单总金额。请按 `shareNo`（企油通消费订单号，每笔不同）做幂等去重。

**6. 验签回调时，body 用解密出来的明文原串**

不要反序列化后再序列化 —— 不同语言的 JSON 输出不一定一致。本示例已这样处理。

---

## 七、接收油卡变动通知

把你的接收地址填到平台后台的合作商「回调地址」。报文与请求方向同构，解析步骤：

1. 用**你方私钥**解出 AES 密钥 → 解出业务报文明文
2. 用**平台公钥**验签，待签串是**原样拼接**（不 urlencode）：
   `version=..&appKey=..&method=..&requestId=..&body={解密出的明文}`

业务字段：

| 字段 | 说明 |
|---|---|
| `oilCardNo` | 油卡编号，对应下单返回值 |
| `optType` | `share_oil` 分油 / `add_oil` 加油 / `refund` 退款 |
| `amount` | 分油=分油金额；加油=**本次**加油占用金额；退款=退款金额 |
| `orderAmount` | 订单实付金额（即分油金额），三种场景都推，便于与 `amount` 对照 |
| `shareNo` | 分油=分油记录编号；加油=企油通消费订单号（**每笔不同，用于去重**） |
| `type` | `add` 增加 / `sub` 减少 |

处理成功必须返回 `{"code":"00","message":"请求成功"}`，否则平台按 60 秒 / 5 分钟 / 30 分钟退避重试 3 次。

---

## 八、错误码

| errCode | 含义 |
|---|---|
| 0001 | 缺少必填请求参数（如未传 `idCard` / `plateNo`） |
| 0005 | 请求头 method 不正确 |
| 0006 | 签名验证不通过 |
| 0012 | 请求流水号重复 |
| 0013 | 请求参数不正确（格式校验未过） |
| 0014 | `orgNo` 与 `appKey` 不匹配 |
| 2023 | 销售单号重复且原单发放失败，请换新单号 |
| 2028 | 账户余额不足 |
| 2032 | 该订单退款正在处理中 |
| 2036 | 未找到对应的分油记录 |
| 2048 | 退单状态异常（不满足退款前置条件，如已全部加油） |
| 2049 | 调用上游退款失败（凭证余额不足或上游拒绝） |

完整列表见接口文档附录 4.3。