109 lines
4.6 KiB
Markdown
109 lines
4.6 KiB
Markdown
# 墨家设备测量上传接口说明
|
||
|
||
版本：V3
|
||
适用对象：墨家箱体测量设备服务
|
||
|
||
## 1. 接口用途
|
||
|
||
墨家设备扫描当前箱上的两张标签并上传测量结果：
|
||
|
||
- 柏悦唛头二维码，扫描结果作为 `boxCode`；
|
||
- 如果当前箱贴有客户从 Amazon FBA 下载的 FBA 标签，则扫描其中的 Shipment ID，作为 `shipment_id`；非 FBA 货物可以不传。
|
||
|
||
每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何处理数据。
|
||
|
||
墨家设备属于平台仓库设备，不固定绑定某个客户。柏悦根据全平台唯一的 `boxCode`
|
||
解析真实客户和入库单，并校验该入库单属于 `machineNo` 绑定的仓库；设备不能跨仓上传。
|
||
|
||
唛头二维码内容由柏悦生成，设备应原样读取并作为 `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；本文不包含任何真实密钥或柏悦内部业务处理规则。
|