211 lines
5.7 KiB
Markdown
211 lines
5.7 KiB
Markdown
# 领星新品测量接口说明
|
||
|
||
> 依据开发环境实际成功请求整理。接口属于领星 WMS 内部网关接口，需要携带已经登录领星 WMS 后取得的 Token 和 Cookie。账号、密码、Token、Cookie 不写入本文档。
|
||
|
||
## 1. 业务流程
|
||
|
||
墨家上传不带 `#` 的 SKU 后，按以下流程处理：
|
||
|
||
```text
|
||
墨家 SKU 测量数据
|
||
↓
|
||
查询领星新品 SKU（US01、US02 分别查询）
|
||
↓
|
||
精确匹配 productSku 或 barcode
|
||
↓
|
||
maintained = 1：禁止再次维护，记录失败原因
|
||
maintained = 0：调用新品测量维护接口
|
||
↓
|
||
记录同步成功或失败
|
||
```
|
||
|
||
箱唛（`boxCode` 包含 `#`）继续走现有箱唛测量逻辑，不调用本文档接口。
|
||
|
||
## 2. 查询 SKU
|
||
|
||
### 请求
|
||
|
||
```http
|
||
POST https://wms.xlwms.com/gateway/wms/newProduct/page
|
||
Content-Type: application/json
|
||
Authorization: Bearer {token}
|
||
Cookie: {领星登录Cookie}
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"barcode": "A120133-A-TK",
|
||
"current": 1,
|
||
"customerCode": "",
|
||
"keyword": "A120133-A-TK",
|
||
"multiKeyword": "",
|
||
"searchType": "barcode",
|
||
"size": 20,
|
||
"whCode": "US01"
|
||
}
|
||
```
|
||
|
||
`US02` 查询时只替换：
|
||
|
||
```json
|
||
"whCode": "US02"
|
||
```
|
||
|
||
### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"tenantCode": "1189",
|
||
"whCode": "US01",
|
||
"customerCode": "1189060",
|
||
"customerName": "DF067",
|
||
"skuId": "",
|
||
"productSku": "A120133-A-TK",
|
||
"productName": "（压缩）2026新款30CM耶稣玩偶",
|
||
"productLname": "",
|
||
"barcode": "A120133-A-TK",
|
||
"length": 23.000,
|
||
"lengthBs": 9.055,
|
||
"width": 15.000,
|
||
"widthBs": 5.906,
|
||
"height": 3.500,
|
||
"heightBs": 1.378,
|
||
"sizeUnit": "cm",
|
||
"weight": 0.150,
|
||
"weightBs": 0.331,
|
||
"weightUnit": "kg",
|
||
"wmsLength": 0.000,
|
||
"wmsLengthBs": 0.000,
|
||
"wmsWidth": 0.000,
|
||
"wmsWidthBs": 0.000,
|
||
"wmsHeight": 0.000,
|
||
"wmsHeightBs": 0.000,
|
||
"wmsSizeUnit": "cm",
|
||
"wmsWeight": 0.000,
|
||
"wmsWeightBs": 0.000,
|
||
"wmsWeightUnit": "kg",
|
||
"wmsUnitMark": 0,
|
||
"maintainer": "",
|
||
"wmsMaintenanceTime": "",
|
||
"maintained": 0
|
||
}
|
||
],
|
||
"total": 1,
|
||
"size": 20,
|
||
"current": 1,
|
||
"pages": 1
|
||
},
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 查询规则
|
||
|
||
1. `code = 200` 且 `data.records` 有记录，才算查询成功。
|
||
2. 查询结果必须精确匹配墨家 SKU：`productSku` 或 `barcode` 等于墨家传入的 SKU。
|
||
3. `US01`、`US02` 分别查询，不能把一个仓库的匹配结果当作另一个仓库的结果。
|
||
4. 没有匹配记录时，记录失败原因“未匹配到领星 SKU”，不调用维护接口。
|
||
5. 保存 `tenantCode`、`whCode`、`customerCode`、`customerName`、`productSku`、`barcode`、`maintained` 和当前领星尺寸重量，供页面追踪。
|
||
|
||
## 3. 新品测量维护
|
||
|
||
### 请求
|
||
|
||
```http
|
||
POST https://wms.xlwms.com/gateway/wms/newProduct/measure
|
||
Content-Type: application/json
|
||
Authorization: Bearer {token}
|
||
Cookie: {领星登录Cookie}
|
||
```
|
||
|
||
维护请求以查询返回的 SKU 记录为基础，只把 `wmsLength`、`wmsWidth`、`wmsHeight`、`wmsWeight` 替换为墨家测量值，并保留领星返回的业务标识字段。
|
||
|
||
成功样例：
|
||
|
||
```json
|
||
{
|
||
"barcode": "A120133-A-TK",
|
||
"customerCode": "1189060",
|
||
"customerName": "DF067",
|
||
"height": 3.5,
|
||
"heightBs": 1.378,
|
||
"length": 23,
|
||
"lengthBs": 9.055,
|
||
"maintained": 0,
|
||
"maintainer": "",
|
||
"productLname": "",
|
||
"productName": "（压缩）2026新款30CM耶稣玩偶",
|
||
"productSku": "A120133-A-TK",
|
||
"sizeUnit": "in",
|
||
"skuId": "",
|
||
"tenantCode": "1189",
|
||
"weight": 0.15,
|
||
"weightBs": 0.331,
|
||
"weightUnit": "lb",
|
||
"whCode": "US01",
|
||
"width": 15,
|
||
"widthBs": 5.906,
|
||
"wmsHeight": "5",
|
||
"wmsHeightBs": 1.969,
|
||
"wmsLength": "24.5",
|
||
"wmsLengthBs": 9.646,
|
||
"wmsMaintenanceTime": "",
|
||
"wmsSizeUnit": "cm",
|
||
"wmsUnitMark": 0,
|
||
"wmsWeight": "0.15",
|
||
"wmsWeightBs": 0.331,
|
||
"wmsWeightUnit": "kg",
|
||
"wmsWidth": "18.5",
|
||
"wmsWidthBs": 7.283
|
||
}
|
||
```
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {},
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
`data` 为空对象时，只要 `code = 200`，即视为维护成功。
|
||
|
||
## 4. 单次维护限制
|
||
|
||
领星新品测量只能维护一次，不能重复覆盖：
|
||
|
||
- 查询结果 `maintained = 0`：允许调用 `/measure`。
|
||
- 查询结果 `maintained = 1`：禁止调用 `/measure`，记录失败原因“领星 SKU 已维护，不能重复维护”。
|
||
- 已经提交过维护但本地没有收到明确成功响应时，不应盲目重试；应重新查询确认 `maintained` 和 `wmsMaintenanceTime`。
|
||
- 本地页面保留墨家测量原始数据和同步失败原因，但不允许通过编辑或重推绕过领星的单次维护限制。
|
||
|
||
## 5. 单位处理
|
||
|
||
当前成功样例中，查询返回的基础字段和维护请求中的单位字段存在差异：
|
||
|
||
- 查询结果：`sizeUnit = cm`、`weightUnit = kg`；
|
||
- 成功维护请求样例：`sizeUnit = in`、`weightUnit = lb`；
|
||
- WMS 维护字段：`wmsSizeUnit = cm`、`wmsWeightUnit = kg`；
|
||
- `wmsLength`、`wmsWidth`、`wmsHeight`、`wmsWeight` 在样例中以字符串传递。
|
||
|
||
因此 Java 实现不能根据字段名自行换算或把所有字段统一成同一单位。应以查询返回的原始记录作为模板，仅按领星接口约定替换 WMS 维护字段；具体换算规则以领星成功请求和后续验证结果为准。
|
||
|
||
## 6. 本地同步状态建议
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| 待同步 | 墨家已接收，尚未完成查询和维护 |
|
||
| 同步成功 | `/measure` 返回 `code = 200` |
|
||
| 同步失败 | 未匹配 SKU、已维护、查询失败、维护失败或登录态失效 |
|
||
|
||
失败记录必须保存脱敏后的失败原因；不保存完整 Token、Cookie、账号、密码或验证码。
|
||
|