w百分比

墨家设备测量上传接口说明-V3.md

@@ -5,7 +5,12 @@
 
 ## 1. 接口用途
 
-墨家设备扫描柏悦唛头并上传当前箱子的测量结果。每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何保存、审核或计费。
+墨家设备扫描当前箱上的两张标签并上传测量结果：
+
+- 柏悦唛头二维码，扫描结果作为 `boxCode`；
+- 客户从 Amazon FBA 下载并贴在箱上的 FBA 标签，扫描其中的 Shipment ID，作为 `shipment_id`。
+
+每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何处理数据。
 
 唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如：
 
@@ -15,6 +20,8 @@ PCHK2608040174#19-1
 
 设备不需要解析或修改 `boxCode`。
 
+`shipment_id` 不是柏悦生成的内容，也不能从 `boxCode` 推导。设备必须从当前箱的 Amazon FBA 标签实际扫描并原样上传。
+
 ## 2. 接口地址
 
 ```text
@@ -41,6 +48,7 @@ POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
 ```json
 {
   "boxCode": "PCHK2608040174#19-1",
+  "shipment_id": "FBA19L5KMY2CU000002",
   "length": 100.1,
   "width": 100.2,
   "height": 100.3,
@@ -55,6 +63,7 @@ POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
 | 字段 | 必填 | 说明 |
 |---|---|---|
 | `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
+| `shipment_id` | 是 | 从当前箱 Amazon FBA 标签实际扫描得到的 Shipment ID，必须原样传输；兼容字段名 `shipmentId` |
 | `length` | 是 | 当前箱长度，单位 cm |
 | `width` | 是 | 当前箱宽度，单位 cm |
 | `height` | 是 | 当前箱高度，单位 cm |
@@ -76,20 +85,22 @@ data:image/jpeg;base64,<Base64内容>
 
 成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。联调期间，即使模拟箱码暂未匹配柏悦入库单，只要测量字段和图片已被柏悦完整接收并保存，也会返回成功；柏悦自行记录并排查匹配结果。
 
-失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`machineNo` 和响应信息，便于重试和排查。
+失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`shipment_id`、`machineNo` 和响应信息，便于重试和排查。
 
 ## 6. 重试约定
 
 网络超时或未收到响应时，设备可以重试同一次上传。当前按 `boxCode` 保存最新结果，同一个箱号重试不会新增多条当前记录。
 
-同一个 `boxCode` 后续再次上传时，以最新一次设备测量结果为准，设备无需额外传版本号。
+同一个 `boxCode` 后续再次上传时，以最新一次设备上传的测量结果和实扫 `shipment_id` 为准，设备无需额外传版本号。
 
 ## 7. 待墨家确认
 
-1. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
-2. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
-3. `weight` 的单位、精度和是否必传。
-4. `machineNo` 是否每台机器固定且唯一。
-5. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。
+1. 是否可以同时扫描柏悦唛头和 Amazon FBA 标签，并分别上传 `boxCode`、`shipment_id`。
+2. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
+3. `shipment_id` 是否可以原样上传，例如 `FBA19L5KMY2CU000002`。
+4. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
+5. `weight` 的单位、精度和是否必传。
+6. `machineNo` 是否每台机器固定且唯一。
+7. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。
 
 柏悦侧会另行提供正式接口地址、固定 AppKey 和测试箱码。首轮联调只校验固定 AppKey，不需要 Secret；本文不包含任何真实密钥或柏悦内部业务处理规则。