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

# 墨家设备测量上传接口说明

版本：V3  
适用对象：墨家箱体测量设备服务

## 1. 接口用途

墨家设备扫描当前箱上的两张标签并上传测量结果：

- 柏悦唛头二维码，扫描结果作为 `boxCode`；
- 客户从 Amazon FBA 下载并贴在箱上的 FBA 标签，扫描其中的 Shipment ID，作为 `shipment_id`。

每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何处理数据。

唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如：

```text
PCHK2608040174#19-1
```

设备不需要解析或修改 `boxCode`。

`shipment_id` 不是柏悦生成的内容，也不能从 `boxCode` 推导。设备必须从当前箱的 Amazon FBA 标签实际扫描并原样上传。

## 2. 接口地址

```text
POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
```

`<GATEWAY_HOST>` 由柏悦另行提供。

## 3. 请求格式

请求头：

| Header | 必填 | 说明 |
|---|---|---|
| `Content-Type` | 是 | `application/json` |
| `X-App-Key` | 是 | 柏悦分配的固定应用标识 |
| `X-Timestamp` | 否 | 首轮联调关闭签名，不传 |
| `X-Nonce` | 否 | 首轮联调关闭签名，不传 |
| `X-Signature` | 否 | 首轮联调关闭签名，不传 |
| `Idempotency-Key` | 否 | 当前同箱号重复上传直接覆盖，不要求设备生成 |

请求 JSON：

```json
{
  "boxCode": "PCHK2608040174#19-1",
  "shipment_id": "FBA19L5KMY2CU000002",
  "length": 100.1,
  "width": 100.2,
  "height": 100.3,
  "weight": 100.4,
  "machineNo": "MJ20210327",
  "picture": "data:image/jpeg;base64,/9j..."
}
```

字段说明：

| 字段 | 必填 | 说明 |
|---|---|---|
| `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
| `shipment_id` | 是 | 从当前箱 Amazon FBA 标签实际扫描得到的 Shipment ID，必须原样传输；兼容字段名 `shipmentId` |
| `length` | 是 | 当前箱长度，单位 cm |
| `width` | 是 | 当前箱宽度，单位 cm |
| `height` | 是 | 当前箱高度，单位 cm |
| `weight` | 待确认 | 当前箱重量，单位 kg；请确认精度和是否必传 |
| `machineNo` | 是 | 墨家设备编号，每台机器固定且唯一 |
| `picture` | 是 | JPEG 图片的 Data URL Base64 文本 |

## 4. 图片格式

图片格式：

```text
data:image/jpeg;base64,<Base64内容>
```

服务端会校验图片格式和大小。当前约定解码后的图片不超过 5 MB。接口不接受图片 URL 或图片 ID。

## 5. 返回结果

成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。联调期间，即使模拟箱码暂未匹配柏悦入库单，只要测量字段和图片已被柏悦完整接收并保存，也会返回成功；柏悦自行记录并排查匹配结果。

失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`shipment_id`、`machineNo` 和响应信息，便于重试和排查。

## 6. 重试约定

网络超时或未收到响应时，设备可以重试同一次上传。当前按 `boxCode` 保存最新结果，同一个箱号重试不会新增多条当前记录。

同一个 `boxCode` 后续再次上传时，以最新一次设备上传的测量结果和实扫 `shipment_id` 为准，设备无需额外传版本号。

## 7. 待墨家确认

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；本文不包含任何真实密钥或柏悦内部业务处理规则。