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

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

1. 接口用途

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

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

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

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

PCHK2608040174#19-1

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

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

2. 接口地址

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：

{
  "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. 图片格式

图片格式：

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. 待墨家确认

是否可以同时扫描柏悦唛头和 Amazon FBA 标签，并分别上传 boxCode、shipment_id。
boxCode 是否可以原样上传完整二维码文本，例如 PCHK2608040174#19-1。
shipment_id 是否可以原样上传，例如 FBA19L5KMY2CU000002。
picture 是否可以按 data:image/jpeg;base64,... 格式上传。
weight 的单位、精度和是否必传。
machineNo 是否每台机器固定且唯一。
首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。

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

4.1 KiB Raw Blame History Unescape Escape