html/docs

Fork 0

Files

T

ouyangxq 2ac6f39057 优化

2026-08-07 14:46:59 +08:00

4.7 KiB

Raw Blame History

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

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

1. 对接结论

柏悦提供一个第三方测量开放接口。推荐所有墨家设备共用一组固定的 AppKey 和 Secret，每台设备通过 deviceCode 区分。

这里的“固定 key”指 X-App-Key 和用于计算 HMAC 的 Secret 固定不变；X-Signature 不能固定，必须根据每次请求的时间戳、随机数、请求内容重新计算。

多台设备共用凭据时，以下字段必须在整个设备群内全局唯一，不能只保证单台设备内唯一：

eventNo
Idempotency-Key
X-Nonce

建议格式为 设备编号-日期-流水号，例如 MJ-DEVICE-001-20260807-000001。

2. 接口地址

将 <GATEWAY_HOST> 替换为柏悦提供的 Gateway 地址：

POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
GET  <GATEWAY_HOST>/openapi/v1/inbound-measurements/events/{eventNo}

该接口不使用登录 JWT，但必须通过下述 HMAC 请求认证。

3. POST 请求

请求头：

Header	必填	说明
`X-App-Key`	是	柏悦分配的固定应用标识，墨家设备群共用
`X-Timestamp`	是	Unix 毫秒时间戳，服务端默认允许上下偏差 5 分钟
`X-Nonce`	是	每次请求唯一的随机字符串，最长 128 个字符
`X-Signature`	是	HMAC-SHA256 小写十六进制签名
`Idempotency-Key`	是	本次写入请求的全局唯一幂等键，最长 128 个字符
`Content-Type`	是	`multipart/form-data`

请求体包含两个 multipart 部分：

data：原始 UTF-8 JSON 文本；不要先格式化或重新序列化后再签名。
image：本次测量对应的图片，最大 5 MB。

data 示例：

{
  "eventNo": "MJ-DEVICE-001-20260807-000001",
  "externalDetailNo": "MJ-DEVICE-001-BOX-000001",
  "warehouseCode": "CN-YW-01",
  "inboundCode": "RK202608010001",
  "inboundDetailId": "190000000000000001",
  "deviceCode": "MJ-DEVICE-001",
  "measuredAt": "2026-08-07T10:30:00+08:00",
  "lengthCm": 50.20,
  "widthCm": 40.10,
  "heightCm": 30.00,
  "packageCount": 5,
  "unitWeightKg": 12.5,
  "boxSpecification": "50.2x40.1x30cm",
  "remark": ""
}

字段说明：

inboundCode 是柏悦入仓码。
inboundDetailId 是柏悦订单货物明细 ID，必须是柏悦提供的有效 ID，不能填墨家自己的箱号。
lengthCm、widthCm、heightCm 单位为厘米，必须大于 0。
packageCount 为本次箱规对应的箱数。
unitWeightKg 可不传；长宽高是必传字段。

4. 签名算法

先计算图片内容摘要：

imageSha256 = SHA256(image二进制内容)
signedBody = data原始文本 + "\\n" + imageSha256
bodySha256 = SHA256(signedBody UTF-8字节)

再生成六行规范串，最后一行后不追加换行：

METHOD
原始PATH
X-Timestamp
X-Nonce
Idempotency-Key
bodySha256

例如 POST 的原始 PATH 必须是：

/openapi/v1/inbound-measurements

签名：

X-Signature = HMAC-SHA256(Secret, 规范串)

输出为小写十六进制字符串。

5. 返回结果

HTTP 业务响应通常为 200，必须检查 JSON 响应体中的 code 字段；只有 code == "200" 才表示业务成功。

成功示例：

{
  "code": "200",
  "message": "success",
  "data": {
    "eventNo": "MJ-DEVICE-001-20260807-000001",
    "inboundCode": "RK202608010001",
    "inboundDetailId": "190000000000000001",
    "measurementId": "...",
    "measurementItemId": "...",
    "imageFileId": "...",
    "accepted": true,
    "status": "RECEIVED",
    "receivedAt": "2026-08-07T02:30:00Z"
  }
}

接口接收后只保存测量数据和图片，不会自动审核、计费或完成入库；柏悦平台后续会进行测量审核。

6. 重试规则

网络超时可以使用同一个 Idempotency-Key 重试，但请求内容必须完全一致。
同一个 Idempotency-Key 如果请求内容不同，服务端会拒绝。
同一个 eventNo 如果长宽高或图片不同，服务端会拒绝。
每次重试都应使用新的 X-Nonce 和新的时间戳；签名也必须重新计算。

7. 开通前需要墨家确认的信息

请墨家确认：

设备服务是否支持 HMAC-SHA256 动态签名，而不是只发送静态 key。
是否可以保证 eventNo、Idempotency-Key、X-Nonce 在多台设备之间全局唯一。
是否可以上传每条测量明细对应的图片。
deviceCode 的固定格式和设备清单。
是否可以使用柏悦提供的 inboundDetailId。

柏悦侧开通时会另行提供：GATEWAY_HOST、固定 X-App-Key、Secret、可用 warehouseCode 和测试入仓数据。本文不包含任何真实密钥。

4.7 KiB Raw Blame History