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

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

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

## 1. 接口用途

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

- 柏悦唛头二维码，扫描结果作为 `boxCode`；
- 如果当前箱贴有客户从 Amazon FBA 下载的 FBA 标签，则扫描其中的 Shipment ID，作为 `shipment_id`；非 FBA 货物可以不传。

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

唛头二维码内容由柏悦生成，设备应原样读取并作为 `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,
  "machineNo": "MJ20210327",
  "picture": "data:image/jpeg;base64,/9j..."
}
```

字段说明：

| 字段 | 必填 | 说明 |
|---|---|---|
| `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
| `shipment_id` | 否 | 当前箱存在 Amazon FBA 标签时，上传实际扫描得到的 Shipment ID；非 FBA 货物可省略或传空；兼容字段名 `shipmentId` |
| `length` | 是 | 当前箱长度，单位 cm |
| `width` | 是 | 当前箱宽度，单位 cm |
| `height` | 是 | 当前箱高度，单位 cm |
| `weight` | 不再接收 | 墨家接口只上传尺寸；货物毛重、托盘皮重和净重统一由称重图片确认链路维护 |
| `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 标签时，是否可以同时扫描柏悦唛头和 Amazon FBA 标签，并分别上传 `boxCode`、`shipment_id`。
2. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
3. 有 Amazon FBA 标签时，`shipment_id` 是否可以原样上传，例如 `FBA19L5KMY2CU000002`；非 FBA 货物允许不传。
4. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
5. 称重图片 OCR 与人工确认不走墨家尺寸上传接口。
6. `machineNo` 是否每台机器固定且唯一。
7. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。

柏悦侧会另行提供正式接口地址、固定 AppKey 和测试箱码。首轮联调只校验固定 AppKey，不需要 Secret；本文不包含任何真实密钥或柏悦内部业务处理规则。