131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# 汇吉采 → 一站式代理平台：标书订单推送接口鉴权规范
|
||
|
||
> 用途：本文档是**本平台（汇吉采标书购买平台，下称「官方网」）调用一站式代理平台接口**时的鉴权规范，用于对接一站式平台开发人员，请对方按此规则在服务端做校验。
|
||
> 目标接口：`POST /api/biz/createPurchaseDetails`（本平台推送购买记录与订单信息到一站式平台落盘）
|
||
|
||
---
|
||
|
||
## 1. 共享凭证（双方提前约定，不通过网络传输）
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|---|---|---|
|
||
| `appKey` | `HJC_Official_Website` | 调用方标识，明文放在请求头 |
|
||
| `password` | `vQ8$kR3#mW6@xP2!nF` | **签名密钥（Secret）**，仅双方服务端持有，**不放在请求头、不出现于任何请求/日志/报文** |
|
||
|
||
> ⚠️ 出于安全考虑，本规范**不把 `password` 明文放请求头**。原始需求中「把 password 明文字段加到请求头」的做法会泄露密钥，改为「用 password 参与签名、请求头只带签名结果」的等价且更安全的方案（见第 3 节）。如需严格沿用原始「明文 password 头」方案，见附录 A。
|
||
|
||
---
|
||
|
||
## 2. 请求头（请求方——官方网——每次调用携带 3 个）
|
||
|
||
| Header | 示例值 | 说明 |
|
||
|---|---|---|
|
||
| `appKey` | `HJC_Official_Website` | 明文 appKey（固定值） |
|
||
| `timestamp` | `202604080103` | 签名时间，格式 `yyyyMMddHHmm`（24 小时制，北京时区，精确到分钟） |
|
||
| `sign` | `9f7c…（32 位小写十六进制）` | 签名值，算法见第 3 节 |
|
||
|
||
另需：`Content-Type: application/json`。
|
||
|
||
---
|
||
|
||
## 3. 签名算法
|
||
|
||
```
|
||
sign = MD5( appKey + password + timestamp )
|
||
```
|
||
|
||
- `+` 表示**字符串直接拼接**，中间无分隔符。
|
||
- `timestamp` 使用与请求头 `timestamp` **完全相同**的值。
|
||
- `MD5` 输出**小写** 32 位十六进制字符串。
|
||
|
||
步骤：
|
||
|
||
1. 取当前北京时间的分钟表示 `timestamp = yyyyMMddHHmm`（例：`2026-04-08 01:03` → `202604080103`）。
|
||
2. 拼串：`HJC_Official_Website` + `vQ8$kR3#mW6@xP2!nF` + `202604080103`。
|
||
3. 对该字符串做 MD5，转小写，得到 `sign`。
|
||
4. 将 `appKey`、`timestamp`、`sign` 放入请求头发出。
|
||
|
||
---
|
||
|
||
## 4. 校验规则（一站式平台服务端）
|
||
|
||
收请求后按以下顺序校验，任一步不通过即拒绝（建议返回 `401` / `400`，并附错误码与说明，便于排查）：
|
||
|
||
1. **校验 appKey**：`appKey` 是否等于已登记的应用标识 `HJC_Official_Website`。不等 → 拒绝。
|
||
2. **校验 timestamp 时效（防重放）**：`timestamp` 与**一站式服务器当前时间**之差是否在 **±10 分钟**以内（统一按北京时区、分钟精度）。超出窗口 → 拒绝，提示「时间戳失效」。
|
||
- 该窗口同时限制了重放窗口；如需更严可协商收紧到 ±3 分钟。
|
||
3. **校验签名**：用共享的 `password` 重算 `MD5(appKey + password + timestamp)`，与请求头 `sign` **不区分大小写**比较（统一小写后比较）。不一致 → 拒绝，提示「签名校验失败」。
|
||
4. 校验通过后，按请求体 `createPurchaseDetails` 的字段约定解析并落盘（业务字段见单独一节的「createPurchaseDetails 请求体字段表」）。
|
||
|
||
---
|
||
|
||
## 5. 幂等与重试约定（可选但强烈建议）
|
||
|
||
`createPurchaseDetails` 是「落盘」类写操作，本平台侧会做失败重试，因此建议一站式平台按业务主键幂等处理，避免重复落盘：
|
||
|
||
- 请求体需带唯一业务单号（如 `purchaseId` / `orderNo`），一站式平台以此作为去重键；**同一单号重复提交时应返回成功、不重复插入**（或返回「已存在」）。
|
||
- 本平台对失败的推送会按 `attempt` 递增重试（建议：1/2/4/8 分钟间隔），重试时 `timestamp/sign` 需要**重新计算**（每次请求都要以新时间重签）。
|
||
|
||
---
|
||
|
||
## 6. 双端示例
|
||
|
||
**官方网（请求方）**——以 Python 为例：
|
||
|
||
```python
|
||
import hashlib, time, requests
|
||
|
||
app_key = "HJC_Official_Website"
|
||
password = "vQ8$kR3#mW6@xP2!nF"
|
||
ts = time.strftime("%Y%m%d%H%M") # 202604080103
|
||
sign = hashlib.md5((app_key + password + ts).encode("utf-8")).hexdigest()
|
||
|
||
resp = requests.post(
|
||
"https://<一站式域名>/api/biz/createPurchaseDetails",
|
||
json={ ... 业务字段 ... },
|
||
headers={
|
||
"appKey": app_key,
|
||
"timestamp": ts,
|
||
"sign": sign,
|
||
"Content-Type": "application/json",
|
||
},
|
||
timeout=15,
|
||
)
|
||
```
|
||
|
||
**一站式（校验方）**——以 Java 为例：
|
||
|
||
```java
|
||
String appKey = req.getHeader("appKey");
|
||
String ts = req.getHeader("timestamp");
|
||
String sign = req.getHeader("sign");
|
||
|
||
if (!"HJC_Official_Website".equals(appKey)) return 401; // 1
|
||
if (Math.abs(System.currentTimeMillis() / 60000 - parseMinute(ts)) > 10)
|
||
return 401; // 2
|
||
String expect = md5("HJC_Official_Website" + SECRET + ts); // 3
|
||
if (!expect.equalsIgnoreCase(sign)) return 401;
|
||
|
||
// 4. 解析 body，按 createPurchaseDetails 字段落盘（按 orderNo 幂等）
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 A：若一站式平台坚持「明文 password 头」的原始方案
|
||
|
||
原始需求表述为「请求头添加 appKey、password，appKey+年月日时分、password+年月日时分，MD5 加密」。若对方已按此固定算法实现，则采用：
|
||
|
||
- 请求头：`appKey=HJC_Official_Website`、`password=vQ8$kR3#mW6@xP2!nF`、`sign=MD5(password + yyyyMMddHHmm)`（小写）。
|
||
- 校验：`password` 需与约定值一致，且 `MD5(password + timestamp) == sign`，同时 `timestamp` 在 ±10 分钟内。
|
||
|
||
> 该方案会把 `password` 以明文形式暴露在报文中，安全性差；**仅作兼容退路，不作为默认推荐**。若对方无法确认固定算法，请首选第 1–6 节的方案。
|
||
|
||
---
|
||
|
||
## 附：需要一站式平台确认/提供的信息
|
||
|
||
1. 上述 `sign` 拼接顺序是否与合作方既有算法一致（`appKey+password+timestamp`）。
|
||
2. 时间戳格式 `yyyyMMddHHmm` 与北京时区是否认可。
|
||
3. 校验窗口 ±10 分钟是否可接受。
|
||
4. `createPurchaseDetails` 请求体字段表（本平台另一份文档，见需求/接口清单）的具体入参名与必填项，需对方给出或双方对齐，以免字段名不一致导致落盘失败。
|