From 2ac6f3905741c1fec13b88484ecc95d23b1556c7 Mon Sep 17 00:00:00 2001
From: ouyangxq <775153912@qq.com>
Date: Fri, 7 Aug 2026 14:46:59 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 墨家设备测量接口对接说明.md | 156 ++++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 墨家设备测量接口对接说明.md

diff --git a/墨家设备测量接口对接说明.md b/墨家设备测量接口对接说明.md
new file mode 100644
index 0000000..bf2779f
--- /dev/null
+++ b/墨家设备测量接口对接说明.md
@@ -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` 和测试入仓数据。本文不包含任何真实密钥。