docs/墨家设备测量接口对接说明-V2.md

墨家设备测量回传接口对接说明（V2）

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

1. 业务流程

柏悦在头程下单完成后，按订单箱规分段生成唛头，并为每个实际箱子生成固定二维码。二维码内容格式为：

入库码#总箱数-箱下标

示例：

PCHK2608040174#19-1
PCHK2608040174#19-2

柏悦会在首次打印前保存 boxCode 与箱规/订单货物明细的对应关系。重复打印或部分补打均沿用原二维码，不重新分配箱号。订单打印后箱规明细不可直接修改，如需变更须取消并重新生成唛头。

墨家设备每次只上传当前扫描到的一个实际箱子的测量结果。一次测量不会覆盖订单中的其他箱规或其他箱子。

2. 上传内容

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

字段说明：

字段	必填	说明
boxCode	是	扫描唛头二维码得到的完整内容；格式为入库码#总箱数-箱下标
length	是	当前箱长度，单位 cm
width	是	当前箱宽度，单位 cm
height	是	当前箱高度，单位 cm
weight	是	当前箱重量，单位 kg；如设备不提供需另行确认
machineNo	是	墨家设备编号，多台设备各自固定
picture	是	Data URL 格式的 JPEG Base64 图片，前缀为 data:image/jpeg;base64,

墨家不需要传柏悦内部的 inboundDetailId、客户 ID、仓库 ID 或箱规名称；柏悦服务端根据 boxCode 查询已保存的箱号映射。

3. 测量记录规则

首次扫描

当前 boxCode 没有测量记录时，新增一条记录：

• 保存本次长、宽、高、重量、图片、机器编号和测量时间；
• 人工确认箱数初始为 1；
• 该记录只代表当前扫描箱，不能自动套用到其他箱子。

同箱重新扫描

同一个 boxCode 再次扫描时，不新增记录，直接覆盖当前设备测量数据：

• 长、宽、高；
• 重量；
• 图片；
• 机器编号；
• 测量时间。

人工已经填写的确认箱数保持不变。旧图片同步替换/清理，当前一个箱号只保留一张有效图片和一条当前记录。

多箱抽样

扫几箱就保留几条独立测量记录。相同箱规抽测多箱时，不在设备回传阶段自动合并；由平台人员逐条确认每条测量数据分别代表多少箱。

例如 100 箱 A 规格抽测两箱：

实际箱	实测数据	人工确认箱数
...#100-1	第一箱的尺寸、重量和图片	60
...#100-35	第二箱的尺寸、重量和图片	40

提交审核

人工确认箱数之和必须等于入库单原始总箱数，才允许正常提交审核。不一致时服务端阻止提交；有权限人员填写异常原因后，才允许异常放行。

4. 状态和覆盖限制

• WAIT_MEASURE、MEASURE_REJECTED：允许新增或覆盖同一 boxCode；
• 测量已提交审核：墨家再次上传直接拒绝；
• 审核通过、计费或入库后：禁止设备覆盖；
• 如需重新测量，必须由平台人员退回测量修正；
• 退回后才重新允许墨家上传。

5. 图片要求

picture 必须为：

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

服务端会去除 Data URL 前缀、解码并校验 JPEG 内容，按解码后的实际图片大小限制最大 5 MB，然后保存到文件中心。接口不接受图片 URL 或文件 ID。

6. 认证方式（待墨家确认）

业务字段和处理流程已确定，认证方式需要墨家确认设备能力。推荐使用：

• 固定 X-App-Key；
• 固定 Secret；
• 每次动态生成 X-Timestamp、X-Nonce 和 X-Signature；
• X-Signature 使用 HMAC-SHA256，根据本次请求原文计算。

如果设备只能发送一个永远不变的静态 Key，无法计算动态 HMAC 签名，请墨家明确说明。届时需要另行评估固定 API Key、HTTPS、防重和 IP 白名单方案，不能直接套用动态签名协议。

7. 需要墨家确认

1. boxCode 是否可以直接作为上传字段，并保持完整二维码文本不变。
2. picture 是否可以按 Data URL JPEG Base64 发送。
3. weight 的单位是否为 kg，精度和是否必传。
4. machineNo 是否每台设备固定且唯一。
5. 设备是否支持动态 HMAC-SHA256 签名。
6. 网络重试时是否可以携带同一个业务请求标识，避免重复处理。

柏悦侧会另行提供正式接口地址、固定 AppKey、Secret、测试入库单和测试唛头。本文不包含任何真实密钥。