优化
This commit is contained in:
+156
@@ -0,0 +1,156 @@
|
||||
# 墨家设备测量回传接口对接说明
|
||||
|
||||
版本：V1
|
||||
适用对象：墨家箱体测量设备服务
|
||||
|
||||
## 1. 对接结论
|
||||
|
||||
柏悦提供一个第三方测量开放接口。推荐所有墨家设备共用一组固定的 `AppKey` 和 `Secret`，每台设备通过 `deviceCode` 区分。
|
||||
|
||||
这里的“固定 key”指 `X-App-Key` 和用于计算 HMAC 的 `Secret` 固定不变；`X-Signature` 不能固定，必须根据每次请求的时间戳、随机数、请求内容重新计算。
|
||||
|
||||
多台设备共用凭据时，以下字段必须在整个设备群内全局唯一，不能只保证单台设备内唯一：
|
||||
|
||||
- `eventNo`
|
||||
- `Idempotency-Key`
|
||||
- `X-Nonce`
|
||||
|
||||
建议格式为 `设备编号-日期-流水号`，例如 `MJ-DEVICE-001-20260807-000001`。
|
||||
|
||||
## 2. 接口地址
|
||||
|
||||
将 `<GATEWAY_HOST>` 替换为柏悦提供的 Gateway 地址：
|
||||
|
||||
```text
|
||||
POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
|
||||
GET <GATEWAY_HOST>/openapi/v1/inbound-measurements/events/{eventNo}
|
||||
```
|
||||
|
||||
该接口不使用登录 JWT，但必须通过下述 HMAC 请求认证。
|
||||
|
||||
## 3. POST 请求
|
||||
|
||||
请求头：
|
||||
|
||||
| Header | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `X-App-Key` | 是 | 柏悦分配的固定应用标识，墨家设备群共用 |
|
||||
| `X-Timestamp` | 是 | Unix 毫秒时间戳，服务端默认允许上下偏差 5 分钟 |
|
||||
| `X-Nonce` | 是 | 每次请求唯一的随机字符串，最长 128 个字符 |
|
||||
| `X-Signature` | 是 | HMAC-SHA256 小写十六进制签名 |
|
||||
| `Idempotency-Key` | 是 | 本次写入请求的全局唯一幂等键，最长 128 个字符 |
|
||||
| `Content-Type` | 是 | `multipart/form-data` |
|
||||
|
||||
请求体包含两个 multipart 部分：
|
||||
|
||||
- `data`：原始 UTF-8 JSON 文本；不要先格式化或重新序列化后再签名。
|
||||
- `image`：本次测量对应的图片，最大 5 MB。
|
||||
|
||||
`data` 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"eventNo": "MJ-DEVICE-001-20260807-000001",
|
||||
"externalDetailNo": "MJ-DEVICE-001-BOX-000001",
|
||||
"warehouseCode": "CN-YW-01",
|
||||
"inboundCode": "RK202608010001",
|
||||
"inboundDetailId": "190000000000000001",
|
||||
"deviceCode": "MJ-DEVICE-001",
|
||||
"measuredAt": "2026-08-07T10:30:00+08:00",
|
||||
"lengthCm": 50.20,
|
||||
"widthCm": 40.10,
|
||||
"heightCm": 30.00,
|
||||
"packageCount": 5,
|
||||
"unitWeightKg": 12.5,
|
||||
"boxSpecification": "50.2x40.1x30cm",
|
||||
"remark": ""
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
- `inboundCode` 是柏悦入仓码。
|
||||
- `inboundDetailId` 是柏悦订单货物明细 ID，必须是柏悦提供的有效 ID，不能填墨家自己的箱号。
|
||||
- `lengthCm`、`widthCm`、`heightCm` 单位为厘米，必须大于 0。
|
||||
- `packageCount` 为本次箱规对应的箱数。
|
||||
- `unitWeightKg` 可不传；长宽高是必传字段。
|
||||
|
||||
## 4. 签名算法
|
||||
|
||||
先计算图片内容摘要：
|
||||
|
||||
```text
|
||||
imageSha256 = SHA256(image二进制内容)
|
||||
signedBody = data原始文本 + "\\n" + imageSha256
|
||||
bodySha256 = SHA256(signedBody UTF-8字节)
|
||||
```
|
||||
|
||||
再生成六行规范串，最后一行后不追加换行：
|
||||
|
||||
```text
|
||||
METHOD
|
||||
原始PATH
|
||||
X-Timestamp
|
||||
X-Nonce
|
||||
Idempotency-Key
|
||||
bodySha256
|
||||
```
|
||||
|
||||
例如 POST 的原始 PATH 必须是：
|
||||
|
||||
```text
|
||||
/openapi/v1/inbound-measurements
|
||||
```
|
||||
|
||||
签名：
|
||||
|
||||
```text
|
||||
X-Signature = HMAC-SHA256(Secret, 规范串)
|
||||
```
|
||||
|
||||
输出为小写十六进制字符串。
|
||||
|
||||
## 5. 返回结果
|
||||
|
||||
HTTP 业务响应通常为 200，必须检查 JSON 响应体中的 `code` 字段；只有 `code == "200"` 才表示业务成功。
|
||||
|
||||
成功示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "200",
|
||||
"message": "success",
|
||||
"data": {
|
||||
"eventNo": "MJ-DEVICE-001-20260807-000001",
|
||||
"inboundCode": "RK202608010001",
|
||||
"inboundDetailId": "190000000000000001",
|
||||
"measurementId": "...",
|
||||
"measurementItemId": "...",
|
||||
"imageFileId": "...",
|
||||
"accepted": true,
|
||||
"status": "RECEIVED",
|
||||
"receivedAt": "2026-08-07T02:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
接口接收后只保存测量数据和图片，不会自动审核、计费或完成入库；柏悦平台后续会进行测量审核。
|
||||
|
||||
## 6. 重试规则
|
||||
|
||||
- 网络超时可以使用同一个 `Idempotency-Key` 重试，但请求内容必须完全一致。
|
||||
- 同一个 `Idempotency-Key` 如果请求内容不同，服务端会拒绝。
|
||||
- 同一个 `eventNo` 如果长宽高或图片不同，服务端会拒绝。
|
||||
- 每次重试都应使用新的 `X-Nonce` 和新的时间戳；签名也必须重新计算。
|
||||
|
||||
## 7. 开通前需要墨家确认的信息
|
||||
|
||||
请墨家确认：
|
||||
|
||||
1. 设备服务是否支持 HMAC-SHA256 动态签名，而不是只发送静态 key。
|
||||
2. 是否可以保证 `eventNo`、`Idempotency-Key`、`X-Nonce` 在多台设备之间全局唯一。
|
||||
3. 是否可以上传每条测量明细对应的图片。
|
||||
4. `deviceCode` 的固定格式和设备清单。
|
||||
5. 是否可以使用柏悦提供的 `inboundDetailId`。
|
||||
|
||||
柏悦侧开通时会另行提供：`GATEWAY_HOST`、固定 `X-App-Key`、`Secret`、可用 `warehouseCode` 和测试入仓数据。本文不包含任何真实密钥。
|
||||
Reference in New Issue
Block a user