|
|
|
@ -20,6 +20,14 @@ |
|
|
|
| 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) | |
|
|
|
| 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) | |
|
|
|
| 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) | |
|
|
|
| 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) | |
|
|
|
| 查询入库单 / 入库状态 | ✅ 已对接(`POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail`) | |
|
|
|
| 查询入库单 / 入库状态 | ✅ 已对接(`POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail`) | |
|
|
|
|
|
|
|
| 创建退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/saveAndPublish`),仅「自行退回」 | |
|
|
|
|
|
|
|
| 退货单详情 | ✅ 已对接(`POST /webApi/rma/info/v1/getOrderDetail`) | |
|
|
|
|
|
|
|
| 取消退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/cancel`) | |
|
|
|
|
|
|
|
| 退货检验后处理 | ⬜ 等文档(缺行 id) | |
|
|
|
|
|
|
|
| BOL 查询(平台仓订单) | ✅ 已对接(`POST /webApi/fbaOrder/v1/getOrderBolList`) | |
|
|
|
|
|
|
|
| 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) | |
|
|
|
|
|
|
|
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | |
|
|
|
|
|
|
|
| 打印条码 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | |
|
|
|
| 其它业务接口 | ⬜ 等文档 | |
|
|
|
| 其它业务接口 | ⬜ 等文档 | |
|
|
|
| 回调 | ⬜ 等文档 | |
|
|
|
| 回调 | ⬜ 等文档 | |
|
|
|
| 真机验证 | ⬜ 等测试环境 | |
|
|
|
| 真机验证 | ⬜ 等测试环境 | |
|
|
|
@ -193,7 +201,8 @@ POST /webApi/order/v1/createOrder |
|
|
|
|---|---| |
|
|
|
|---|---| |
|
|
|
| `signatureRequired = true` | `is_signature` | |
|
|
|
| `signatureRequired = true` | `is_signature` | |
|
|
|
|
|
|
|
|
|
|
|
保价(`is_insurance`)标准模型没有对应字段,暂不下发。 |
|
|
|
保价:任意商品行带 `insuredAmount` 就整单下发 `is_insurance`——`addService` |
|
|
|
|
|
|
|
是订单级开关,易达云没有行级保价。 |
|
|
|
|
|
|
|
|
|
|
|
## 查询出库单 / 面单 |
|
|
|
## 查询出库单 / 面单 |
|
|
|
|
|
|
|
|
|
|
|
@ -799,9 +808,39 @@ POST /webApi/userSkuStock/v1/queryInventory → Page<InventorySnapshot> |
|
|
|
| `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) | |
|
|
|
| `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) | |
|
|
|
| 分页 | 游标是页码字符串;`total` 按文档当总行数用,缺失时按满页判断 | |
|
|
|
| 分页 | 游标是页码字符串;`total` 按文档当总行数用,缺失时按满页判断 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 真机验证(2026-11-13,PR 环境) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 场景 | 结果 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `warehouseIdList:[2]`,pageSize 100 | `total=339`,本页 100 条,翻页正常 | |
|
|
|
|
|
|
|
| 不传仓库过滤 | `total=436` | |
|
|
|
|
|
|
|
| `totalStockGreaterThanZero:false` | `total=2436` | |
|
|
|
|
|
|
|
| `pageSize` 传 501 / 2000 | **不报错,静默截断到 500** | |
|
|
|
|
|
|
|
| `pageSize` 传 0 / -1 | `total=0`、`rows` 为空(不是报错) | |
|
|
|
|
|
|
|
| 不传 `pageSize` | 服务端默认返回 **200** 条 | |
|
|
|
|
|
|
|
| 不传 `pageNum`,或传 0 | 按第 1 页返回 | |
|
|
|
|
|
|
|
| **页码超过最后一页** | **重复返回最后一页**,不是空列表 | |
|
|
|
|
|
|
|
| `skuCodeList` 101 个 | `code=500`「skuCode列表最大支持100」 | |
|
|
|
|
|
|
|
| `warehouseIdList:["USLA"]` | `code=500`「参数不符合文档规范…parseLong error」 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**页码越界重复返回最后一页**这点最坑:不能拿「本页为空」当循环终止条件, |
|
|
|
|
|
|
|
必须用 `total` 判断。实现里 `nextCursor` 就是这么做的。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 字段类型:数字全是字符串 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
真机返回的 `totalStock` / `stock` / `frozenStock` / `toDeliverStock` / |
|
|
|
|
|
|
|
`inTransitStock` / `safeStock` / `nonSaleStock` 全是 **字符串**(`"15499"`), |
|
|
|
|
|
|
|
`warehouseId` 也是字符串。DTO 用 `Integer` 由 Jackson 自动转换,没问题。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### `safeStock` 经常为 null |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
采样 500 行:**430 行的 `safeStock` 是 null**(`toDeliverStock` 则都有值)。 |
|
|
|
|
|
|
|
统一模型约定「仓方未给时为 -1」,所以这里映射成 **-1 而不是 0**, |
|
|
|
|
|
|
|
否则真实的「安全库存 0」和「没配安全库存」分不出来。 |
|
|
|
|
|
|
|
|
|
|
|
### 未映射的字段 |
|
|
|
### 未映射的字段 |
|
|
|
|
|
|
|
|
|
|
|
`nonSaleStock`(不可售库存)、`snInStock`、`barCode`、`goodsType`、`countryName` |
|
|
|
`nonSaleStock`(不可售库存)、`snInStock`、`barcode`、`goodsType`、`countryName` |
|
|
|
不在统一模型里。整行按 `inventoryType = 0`(可售)落,**不可售数量被丢弃**—— |
|
|
|
不在统一模型里。整行按 `inventoryType = 0`(可售)落,**不可售数量被丢弃**—— |
|
|
|
需要对账不可售库存时要扩展模型,见 TODO。 |
|
|
|
需要对账不可售库存时要扩展模型,见 TODO。 |
|
|
|
|
|
|
|
|
|
|
|
@ -820,6 +859,344 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ |
|
|
|
[-Dedayun.probe.zeroStock=true] [-Dedayun.probe.page=1] |
|
|
|
[-Dedayun.probe.zeroStock=true] [-Dedayun.probe.page=1] |
|
|
|
``` |
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 创建退货单 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 四种退货方式,我们只做「自行退回」 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| `returnType` | 含义 | 必填 | 我们的实现 | |
|
|
|
|
|
|
|
|---|---|---|---| |
|
|
|
|
|
|
|
| 0 | 未妥投退回(派送失败 / 拒收 / 拦截) | 关联单号 | ❌ | |
|
|
|
|
|
|
|
| 1 | 返邮退回(EDA 提供返邮面单) | 关联单号 + 退货人姓名/城市/地址/邮编 + 返邮标签 | ❌ | |
|
|
|
|
|
|
|
| **2** | **自行退回(买家自己寄回)** | **关联单号 + 跟踪号** | ✅ **唯一路径** | |
|
|
|
|
|
|
|
| 3 | FBA 退回 | 亚马逊单号 + 退货仓 + 承运商 + 跟踪号 + 标签数 | ❌ | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`ReturnCommand` 强制要求 `returnTrackingNo`,正好对上「自行退回」; |
|
|
|
|
|
|
|
另外三种要退货人地址或亚马逊单号,标准模型没有对应字段。见 TODO。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 响应 `data` 就是退货单号 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```json |
|
|
|
|
|
|
|
{"code":200,"msg":"操作成功","data":"RMA2411053149","traceId":"..."} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
和运去哪不同(那个只回 code/message,拿不到仓单号),这里能直接落 |
|
|
|
|
|
|
|
`providerReturnId`,后续查询 / 取消有单号可用。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
接口不回状态,所以 `status` 固定 `UNKNOWN`——**不要当成「已受理」**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 仓:数字优先 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`warehouseId`(数字)优先级高于 `warehouseCode`。取命令上的 `warehouseId`, |
|
|
|
|
|
|
|
没有再取账户配置的 `providerWarehouseId`;数字进 `warehouseId`,非数字进 |
|
|
|
|
|
|
|
`warehouseCode`(如 `USLA`)。两者都没有时不下发,由仓方按关联单号的仓处理。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 处理指令只有「销毁」能确定 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`skus[].command` 文档说是「1 上架 / 2 销毁」,但没有给码表。统一模型的 |
|
|
|
|
|
|
|
`ReturnDealMethod` 是另一套码(客户自提 / 拍照确认 / 销毁 / 仓库确认),映射: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| `ReturnDealMethod` | `command` | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `DESTROY` | **2 销毁** | |
|
|
|
|
|
|
|
| 其余三种 | 1 上架(都要先入库再处理) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
见 TODO。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 未实现的退货能力 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 方法 | 状态 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 | |
|
|
|
|
|
|
|
| `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 探针 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```bash |
|
|
|
|
|
|
|
# dry-run:只打印报文(不联网) |
|
|
|
|
|
|
|
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ |
|
|
|
|
|
|
|
-Dedayun.probe.return=true -Dtest=EdayunReturnProbeTest test |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 真发一次(会在测试仓建 RMA 单,relationNo 必须是真实出库单号) |
|
|
|
|
|
|
|
... -Dedayun.probe.return=true -Dedayun.probe.write=true \ |
|
|
|
|
|
|
|
-Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \ |
|
|
|
|
|
|
|
-Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \ |
|
|
|
|
|
|
|
-Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \ |
|
|
|
|
|
|
|
-Dedayun.probe.relationNo=ORD599493019 \ |
|
|
|
|
|
|
|
-Dedayun.probe.trackingNo=1Z84V7X00397803717 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
报文示例(dry-run 产出): |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```json |
|
|
|
|
|
|
|
{"returnType":2,"relationNo":"ORD599493019","carrierName":"Fedex","customerRemark":"probe", |
|
|
|
|
|
|
|
"skus":[{"skuCode":"ybtest","command":1,"skuNum":1}], |
|
|
|
|
|
|
|
"trackingNo":"1Z84V7X00397803717","warehouseId":2} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 退货单详情 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/rma/info/v1/getOrderDetail → WarehouseReturn |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
请求只有一个 `rmaCode`(**仓侧 RMA 号**,不是 OMS 单号)。响应七块,统一模型只承载 |
|
|
|
|
|
|
|
单头与明细行: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 响应块 | 用途 | 进统一模型 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| `basicInfo` | 状态、关联单号、仓库、退货方式、创建时间 | ✅ 单头 | |
|
|
|
|
|
|
|
| `skuList` | 预报要退的 SKU | ✅ 明细(兜底) | |
|
|
|
|
|
|
|
| `checkList` | 仓实际收货检验结果 | ✅ **明细(优先)** | |
|
|
|
|
|
|
|
| `logisticsInfo` | 退货人地址、返邮信息 | ❌ 标准模型无字段 | |
|
|
|
|
|
|
|
| `shipmentParcelList` | 预报包裹尺寸重量 | ❌ | |
|
|
|
|
|
|
|
| `packageList` | 跟踪号与包裹状态 | ❌ | |
|
|
|
|
|
|
|
| `shelfList` | 实际上架数量 | ❌ | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 明细行:检验优先,预报兜底 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`skuList` 是买家预报要退什么,`checkList` 是仓实际收到的(带异常原因与照片)。 |
|
|
|
|
|
|
|
对账以**实际收到**为准,所以 `checkList` 优先;没有检验记录(还没收货)才退回预报。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
两边字段类型还不一致:`skuNum` 在 `skuList` 是 **string**,在 `checkList` 是 **number**, |
|
|
|
|
|
|
|
所以分开映射,不合并成一个循环。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 状态:码表缺失,只能按中文名推断 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档只给 `status: 1` 这类示例,**没有码表**。`EdayunRmaStatus` 因此只按 |
|
|
|
|
|
|
|
`statusName` 中文名兜底,码值一个都没映射: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 中文名关键字 | 归一化 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 驳回 / 拒绝 / 不通过 | `REJECTED` | |
|
|
|
|
|
|
|
| 关闭 / 取消 / 作废 | `CLOSED` | |
|
|
|
|
|
|
|
| 完成 / 已上架 / 结案 | `COMPLETED` | |
|
|
|
|
|
|
|
| 审核 | `PENDING_REVIEW` | |
|
|
|
|
|
|
|
| 收货 / 检验 / 清点 | `PENDING_RECEIPT` | |
|
|
|
|
|
|
|
| 在途 / 退货中 / 运输 / 已发出 / 待收 | `RETURNING` | |
|
|
|
|
|
|
|
| 草稿 / 预报 | `DRAFT` | |
|
|
|
|
|
|
|
| 认不出 | `UNKNOWN`(原文进 `rawStatus`) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**否定语义先判**:「审核不通过」不能被「审核」命中成待审核。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 响应只有仓名,没有仓编码 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`basicInfo` 给的是 `warehouseId`(数字)+ `warehouseName`,没有仓编码。 |
|
|
|
|
|
|
|
`warehouseCode` 回退 OMS 仓编码。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### `data: null` 当作查不到 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
单号不存在时仓方回 `code=200` + `data: null`,适配器返回 `null`—— |
|
|
|
|
|
|
|
这是「接口通、单不存在」,不是失败,不当异常抛。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 取消退货单 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/rma/info/v1/cancel → boolean |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
请求同样只有 `rmaCode`。响应 `data` 是**布尔值**,不是单号: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```json |
|
|
|
|
|
|
|
{"code":200,"msg":"操作成功","data":true} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### `data=false` 是仓方拒绝,要抛异常 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`code=200` 只说明请求被接受,`data=false` 表示仓方拒绝(如已收货)。 |
|
|
|
|
|
|
|
取消是状态变更,**不能静默返回 false** 让调用方以为没事——适配器抛 |
|
|
|
|
|
|
|
`WarehouseException`,`msg` 里的原因原样带出。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`data` 缺失同样按失败处理。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 只认仓侧 RMA 号 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
幂等键 `warehouseCode + providerReturnNo + "cancel"`。传 OMS 单号仓方查不到, |
|
|
|
|
|
|
|
所以宿主必须先用创建 / 详情拿到 `providerReturnId`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## BOL 查询(平台仓订单) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/fbaOrder/v1/getOrderBolList → List<BolDocument> |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
店铺订单 / 平台仓订单共用,`orderNo` 传 EDA 的平台仓订单号(如 `FBA473182144`)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 与入库 BOL 不是一回事 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| | `inbound().bols()` | `orderBols()` | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| 对象 | 头程入库计划单 | 平台仓 / 店铺订单 | |
|
|
|
|
|
|
|
| 返回 | `List<String>` 文件地址 | 带提货状态、约定/实际提货量、POD | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
方法名带 `order` 前缀是因为 `InboundCapable.bols` 已有同签名同参数、 |
|
|
|
|
|
|
|
返回值不同的方法,同一适配器实现两者时擦除后无法区分。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 状态码表只有一个确认 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`status = 11 → 已妥投` 是文档响应示例确认的。其余状态 `EdayunBolStatus` |
|
|
|
|
|
|
|
按 `statusName` 中文名兜底,认不出归 `UNKNOWN`,原值留在 `BolDocument.rawStatus()`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 真机验证(2026-11-16) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`orderNo = FBA473182144` → `code=200, data.totalNum=null, bolList=null`。 |
|
|
|
|
|
|
|
**PR 环境没有 BOL 数据**,映射只被单测覆盖。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 物流产品清单 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/order/listByLogisticProductHasPerm → List<LogisticsProduct> |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### `-998` 是哨兵值,要跳过 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
最后一条常是 `productId = -998`、`productName = 使用分物流规则`, |
|
|
|
|
|
|
|
其余字段全 null。它不是可选的物流产品,映射时**跳过**, |
|
|
|
|
|
|
|
否则宿主的渠道清单里会多一个查不到的 id。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 入参 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 我们的值 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字时不传 | |
|
|
|
|
|
|
|
| `applicableBusiness` | 固定 **1 店铺订单**——统一模型不区分业务类型 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档说 `warehouseId` 必填,**实测不传会返回全部仓的产品**(162 条 vs 仓 2 的 36 条)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 统一模型只有 3 个字段 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`LogisticsProduct` 只有编码 / 名称 / 是否跨国;**易达云不回跨国标记**,恒 `false`。 |
|
|
|
|
|
|
|
承运商类型、派单方式、面单获取方式、增值服务选项、适用业务都在 DTO 里。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 真机验证(2026-11-16) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 场景 | 结果 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 仓 2 + 店铺订单 | 36 条 | |
|
|
|
|
|
|
|
| 仓 2 + 平台仓订单 | 23 条 | |
|
|
|
|
|
|
|
| 仓 2 + 退货单 | 35 条 | |
|
|
|
|
|
|
|
| 仓 2 不传业务类型 | 37 条(含 -998) | |
|
|
|
|
|
|
|
| 仓 98 + 店铺订单 | 22 条 | |
|
|
|
|
|
|
|
| 不传仓 | 162 条(全账号) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`-998` 每条都出现,确认是哨兵值。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 物流轨迹 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 请求体是**纯字符串数组** |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```json |
|
|
|
|
|
|
|
["1Z84V7X00397803717"] |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档把字段名留空了,示例写成 `[{"": ["aa","bb"]}]` 是自动生成的占位。 |
|
|
|
|
|
|
|
真机实测只有纯数组能通:嵌套对象会被静默忽略,返回空 body。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 「未匹配到轨迹」不是错误 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
查不到时仓方回 `code=500, msg=未匹配到轨迹`。但对调用方来说, |
|
|
|
|
|
|
|
这和「运单刚生成、还没揽收」是同一件事——适配器把它当**空结果**处理 |
|
|
|
|
|
|
|
(`track` 返回空列表,`trackShipment` 返回 `null`),不抛异常。 |
|
|
|
|
|
|
|
其它 500(如「系统异常」)仍然抛。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`msg=跟踪号为空` 同理按空结果处理。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 上网时间 / 妥投时间是**带时区的字符串** |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
文档说明「主要关注上网时间跟妥投时间」,所以统一模型的 `TrackingInfo` |
|
|
|
|
|
|
|
新增两个字段直接承载: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 易达云 | 统一模型 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `onlineTime`(`2025-08-19 08:17:00`) | `firstOnlineAt()`(Instant) | |
|
|
|
|
|
|
|
| `deliveredTime` | `deliveredAt()`(Instant) | |
|
|
|
|
|
|
|
| `timeZone`(`GMT-04:00`) | 解释上面两个时间用 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**同一个响应里时间口径混杂**:`onlineTime` / `deliveredTime` 是字符串, |
|
|
|
|
|
|
|
而节点时间 `recentDescribeTime` 是毫秒。字符串按 `timeZone` 解析,解析失败留 null。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
时区解析认 `GMT±HH:mm` / `UTC±HH:mm` / `±HH:mm`;认不出按 UTC, |
|
|
|
|
|
|
|
**不猜成仓所在时区**(那是另一个概念)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 节点状态优先 eventStatus |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
节点上的 `status` 是数字码(码表未给),`eventStatus` 是字符串。 |
|
|
|
|
|
|
|
映射时 `eventStatus` 优先,缺失才退回数字码的字符串形式。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 真机验证(2026-11-16) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 跟踪号 | 结果 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 文档示例 `LF-1741871641090` | `code=500 未匹配到轨迹` | |
|
|
|
|
|
|
|
| 出库单里的真实 `889542071709` | `code=500 未匹配到轨迹` | |
|
|
|
|
|
|
|
| `1Z84V7X00397803717` | 同上 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**PR 环境没有任何可查到的轨迹**,映射只被单测覆盖。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 打印条码 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 与入库 SKU 贴标不是一回事 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| | `inbound().printSkuLabel()` | `printBarcodes()` | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| 对象 | 入库计划单 | **任意 SKU** | |
|
|
|
|
|
|
|
| 绑定 | 必填入库单号 | 不绑单据 | |
|
|
|
|
|
|
|
| 纸张 | 14 种小尺寸 | **4 档** | |
|
|
|
|
|
|
|
| 返回 | 异步任务号 | **同步 PDF 地址** | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
因为纸张集合完全不同,新增了独立枚举 `BarcodePaperSize`(7×3cm / 10×6cm / 6×4cm / A4), |
|
|
|
|
|
|
|
没有复用 `SkuLabelSizeType`——那可是 14 个取值,混用会误导调用方。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 响应 `data` 是文件地址字符串 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```json |
|
|
|
|
|
|
|
{"code":200,"msg":"操作成功","data":"https://.../barcode123.pdf","traceId":null} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
不是对象、也不是任务号——仓方同步生成 PDF。映射到 `WarehouseLabel.url()`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 本地提前挡住的两条 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 约束 | 仓方提示 | 我们 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| SKU 数 > 50 | `最多打印50个SKU` | `BarcodePrintCommand` 构造期就拒 | |
|
|
|
|
|
|
|
| 份数 ≤ 0 | `内部服务器错误` | 同上 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
仓方对非法 `num` 回的是「内部服务器错误」,看不出原因,所以本地先挡。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 其它实测校验 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 场景 | 仓方返回 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 缺 `productInfos` / 空数组 | `产品信息不能为空` | |
|
|
|
|
|
|
|
| 缺 `pageSize` | `纸张尺寸不能为空` | |
|
|
|
|
|
|
|
| `pageSize=9`(非法) | `内部服务器错误` | |
|
|
|
|
|
|
|
| SKU 不存在 | `sku=NO-SUCH-SKU信息不存在` | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### `isPrintSkuName` 只在 true 时下发 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`false` 是仓方默认值,不下发,省得干扰它自己的默认。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 真机验证(2026-11-16) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
`ybtest` + A4 + `isPrintSkuName=true` → 拿到真实 PDF: |
|
|
|
|
|
|
|
`https://oss.edayun.com/test/2026/11/16/02/.../barcode7640824581948387426.pdf` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
四种纸张尺寸都返回 `code=200`。 |
|
|
|
|
|
|
|
|
|
|
|
## 待确认(问易达云) |
|
|
|
## 待确认(问易达云) |
|
|
|
|
|
|
|
|
|
|
|
| # | 要确认 | |
|
|
|
| # | 要确认 | |
|
|
|
|