|
|
|
|
# 运去哪(YQN)接入汇总
|
|
|
|
|
|
|
|
|
|
## 1. 基本信息
|
|
|
|
|
|
|
|
|
|
| 项 | 值 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 适配器 ID | `yqn` |
|
|
|
|
|
| PR 环境 | `https://pr-hwc-open-api.yqn.com` |
|
|
|
|
|
| 轨迹接口 | `https://pr-ship-api.yqn.com`(**不同主机**) |
|
|
|
|
|
| 鉴权 | 组织级固定 token,请求头 `x-api-key` |
|
|
|
|
|
| 限流 | 保守默认 2 req/s/仓(仓方未公开) |
|
|
|
|
|
| ERP 后台 | `https://pr-erp.yqn.com` |
|
|
|
|
|
|
|
|
|
|
## 2. 接口清单(19 个已对接)
|
|
|
|
|
|
|
|
|
|
| # | 接口 | 路径 | 能力位 |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| 1 | 商品创建 / 编辑 | `POST /v1/product/save` | `PRODUCT` |
|
|
|
|
|
| 2 | 创建销售订单 | `POST /v1/saleOrder/create` | `OUTBOUND` |
|
|
|
|
|
| 3 | 订单详情 | `POST /v1/saleOrder/findOne` | `OUTBOUND` |
|
|
|
|
|
| 4 | 取消销售订单 | `POST /v1/saleOrder/cancel` | `OUTBOUND` |
|
|
|
|
|
| 5 | 库存查询 | `GET /v2/inventory/get_inventory_by_page` | `INVENTORY_QUERY` |
|
|
|
|
|
| 6 | 创建调拨单 | `POST /v2/transferOutboundPlan/create` | `TRANSFER` |
|
|
|
|
|
| 7 | 创建入库计划 | `POST /v1/inbound/createInboundPlan` | `INBOUND` |
|
|
|
|
|
| 8 | 查询入库计划 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` |
|
|
|
|
|
| 9 | 打印箱标 | `POST /v1/inbound/generateBoxLabel` | `BOX_LABEL` |
|
|
|
|
|
| 10 | 打印 SKU 标 | `POST /v1/inbound/generateItemLabel` | `SKU_LABEL` |
|
|
|
|
|
| 11 | 创建销售退货 | `POST /v3/saleReturn/createSaleReturnPlan` | `RETURN` |
|
|
|
|
|
| 12 | 退货计划查询 | `POST /v3/saleReturn/getInboundPlanInfo` | `RETURN` |
|
|
|
|
|
| 13 | 退货条目处理 | `POST /v3/saleReturn/addProcessMode` | `RETURN_DISPOSITION` |
|
|
|
|
|
| 14 | 创建销毁计划 | `POST /v1/destroyPlan/createDestroyPlan` | `DESTRUCTION` |
|
|
|
|
|
| 15 | 物流轨迹 | `GET ship-api/api/v2/orderShipment/track/{trackingNo}` | `TRACKING` |
|
|
|
|
|
| 16 | 结算明细 | `POST /v1/warehouse/operation/costs/detail` | `FEE_SETTLEMENT` |
|
|
|
|
|
| 17 | 运费试算 | `POST /v1/saleOrder/calculate` | `FEE_ESTIMATE` |
|
|
|
|
|
| 18 | 物流产品清单 | `GET /v2/sysCarrierGroup/getCarrierGroupList` | `LOGISTICS_PRODUCT` |
|
|
|
|
|
| 19 | 仓库目录 | `GET /v1/warehouse/findAll` | `WAREHOUSE_DIRECTORY` |
|
|
|
|
|
|
|
|
|
|
### 回调(4 个)
|
|
|
|
|
|
|
|
|
|
| 回调 | 触发时机 | 载荷 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| API 149 面单购买成功 | 面单出单后 | 运单号 / 承运商 / 发货方式 |
|
|
|
|
|
| API 154 业务单据变动 | 入库 / 调拨 / 出库 / 退货认领状态变更 | 状态码(含义随单据类型) |
|
|
|
|
|
| API 142 退货入库完成 | 退货上架 / 销毁后 | 处理方式 + 上架数量 + 批次 |
|
|
|
|
|
| API 150 库存变动 | 库存增减时 | 增量流水 |
|
|
|
|
|
|
|
|
|
|
## 3. 业务流程
|
|
|
|
|
|
|
|
|
|
### 出库
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
① 查物流产品(校验渠道可用) GET /v2/sysCarrierGroup/getCarrierGroupList
|
|
|
|
|
② 运费试算(可选) POST /v1/saleOrder/calculate
|
|
|
|
|
③ 下发出库单 POST /v1/saleOrder/create
|
|
|
|
|
└─ 平台面单时带 attachInfoItems(面单文件)
|
|
|
|
|
④ 查详情 / 拆单包裹 POST /v1/saleOrder/findOne
|
|
|
|
|
⑤ 取消(未发货时) POST /v1/saleOrder/cancel
|
|
|
|
|
⑥ 面单回调 API 149
|
|
|
|
|
⑦ 状态变更回调 API 154
|
|
|
|
|
⑧ 物流轨迹 GET ship-api/api/v2/orderShipment/track/{no}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 入库
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
① 创建入库计划 POST /v1/inbound/createInboundPlan
|
|
|
|
|
② 查询入库计划 POST /v1/inbound/getInboundPlanInfo
|
|
|
|
|
③ 打印箱标 / SKU 标 POST /v1/inbound/generateBoxLabel
|
|
|
|
|
POST /v1/inbound/generateItemLabel
|
|
|
|
|
④ 状态回调 API 154
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 退货
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
① 创建退货预约 POST /v3/saleReturn/createSaleReturnPlan
|
|
|
|
|
② 仓收货检验、上架 / 销毁
|
|
|
|
|
③ 退货入库回调 API 142(结果来源)
|
|
|
|
|
④ 查退货计划(拿明细行 id) POST /v3/saleReturn/getInboundPlanInfo
|
|
|
|
|
⑤ 按行设置处理方式 POST /v3/saleReturn/addProcessMode
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
> ④ 是必需的:API 77(退货条目处理)要传仓侧明细行 `id`,
|
|
|
|
|
> 只能从 ④ 的 `saleReturnOrderItems[].id` 拿。
|
|
|
|
|
|
|
|
|
|
### 调拨 / 库存 / 费用
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
创建调拨单 POST /v2/transferOutboundPlan/create
|
|
|
|
|
库存查询 GET /v2/inventory/get_inventory_by_page
|
|
|
|
|
库存变动回调 API 150
|
|
|
|
|
结算明细 POST /v1/warehouse/operation/costs/detail
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 4. 真机联调结论(PR 环境 2026-11-11)
|
|
|
|
|
|
|
|
|
|
用 RF_NY_US 仓、DM00001 SKU、WLC-FEDEX 发货方式跑全链路。
|
|
|
|
|
|
|
|
|
|
### 通过的
|
|
|
|
|
|
|
|
|
|
| 接口 | 实测 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 创建销售订单 | ✅ 返回 `providerOrderId=200171697` |
|
|
|
|
|
| 订单详情 | ✅ `rawStatus=unshipped` → `SUBMITTED` |
|
|
|
|
|
| 取消订单 | ✅ 「取消订单成功」 |
|
|
|
|
|
| 库存查询 | ✅ 2 条(可售 164 / 不可售 0) |
|
|
|
|
|
| 运费试算 | ✅ 返回 1 个仓 1 个渠道 |
|
|
|
|
|
| 创建入库计划 | ✅ `IP8826111100005` |
|
|
|
|
|
| 查询入库计划 | ✅ planned=1 packed=1 boxes=1 |
|
|
|
|
|
| 创建调拨单 | ✅ `UAT-TF2611110002` |
|
|
|
|
|
| 创建退货 | ✅ 提交成功 |
|
|
|
|
|
| 结算明细 | ✅ 接口通(新单无费用,返回 0 条) |
|
|
|
|
|
| 仓库目录 | ✅ 1 个仓 |
|
|
|
|
|
| 物流产品 | ✅ 100 个 |
|
|
|
|
|
|
|
|
|
|
### 文档与实际不符(已按实际修正)
|
|
|
|
|
|
|
|
|
|
| 接口 | 文档写的 | 实际 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 库存查询 | 参数名 `query.warehouseCodes` | **`warehouseCodes`**(扁平) |
|
|
|
|
|
| 物流产品 | 参数名 `query.warehouseCode` | **`warehouseCode`**(扁平) |
|
|
|
|
|
| 仓库目录 | 成功 `status: 1` | **`status: 200`** |
|
|
|
|
|
| 运费试算 | 有 `code` 字段 | **没有 `code`**,只有 `status: 200` |
|
|
|
|
|
|
|
|
|
|
### 仓方环境问题(非 SDK 问题)
|
|
|
|
|
|
|
|
|
|
| 接口 | 现象 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 打印箱标 / SKU 标 | 仓方内部 `Read timed out`(`HWC-OMS-ORDERCENTER` 超时) |
|
|
|
|
|
|
|
|
|
|
### 业务约束(非 SDK 问题)
|
|
|
|
|
|
|
|
|
|
| 接口 | 现象 | 原因 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 创建入库计划 | 传 `lineCode` 报「项目名称不存在」 | 仓方项目名要真实存在 |
|
|
|
|
|
| 创建销毁 | 「DM00001 库存不足」 | 需不可售库存,测试仓为 0 |
|
|
|
|
|
| 商品建档 | 「当前状态不能编辑商品」 | 测试 SKU 已存在且不可编辑 |
|
|
|
|
|
|
|
|
|
|
## 5. 平台限制(已知且无法解决)
|
|
|
|
|
|
|
|
|
|
| 接口 | 字段 | 情况 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 订单详情 `findOne` | `orderRef`(平台单号) | **不回传**,恒 null,宿主自行保存映射 |
|
|
|
|
|
| 订单详情 `findOne` | `requestedAt`(下单时间) | **不回传**,恒 null |
|
|
|
|
|
| 退货计划查询 | `createdAt` | **无创建时间** |
|
|
|
|
|
| 结算明细 | `documentNo`(单据号) | **不返回**,对账靠 `saleOrderNo + settledAt + feeName` |
|
|
|
|
|
| 结算明细 | `providerSku` | **不返回**,费用只到订单 / 仓粒度 |
|
|
|
|
|
| 退货条目处理 | `lineId` | 需先查 API 83 才能拿到 |
|
|
|
|
|
|
|
|
|
|
## 6. 字段口径(容易传错的)
|
|
|
|
|
|
|
|
|
|
| 字段 | 要传什么 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 结算明细 `saleOrderNo` | **数字单号**(创建返回的 `providerOrderId`,如 `200171697`),**不是**来源单号 |
|
|
|
|
|
| 退货条目处理 `lineId` | 来自 **退货计划查询**(API 83)的 `saleReturnOrderItems[].id`,不是回调里的 |
|
|
|
|
|
| 订单详情查询键 | **来源单号**(`outboundRequestNo`),不是 `providerOrderId` |
|
|
|
|
|
| 入库查询键 | 入库单号或来源单号(`orderNo` 两者均可) |
|
|
|
|
|
| 商品海关申报 | 币种**必须 USD**,非 USD 直接拒绝 |
|
|
|
|
|
|
|
|
|
|
## 7. 枚举映射(两套码表,别混)
|
|
|
|
|
|
|
|
|
|
### 退货的处理方式
|
|
|
|
|
|
|
|
|
|
| API 81 预约(`returnDealMethod`) | API 77 检验后(`goodsReturnType`) | API 142 回调(`processMode`) |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 0 客户自提 | 0 客户自提 | 2 销毁 |
|
|
|
|
|
| 1 拍照确认 | 2 销毁 | 3 不良品上架 |
|
|
|
|
|
| 2 销毁 | 3 上架(良品) | 4 换标上架 |
|
|
|
|
|
| 5 仓库确认 | 4 换标上架 | 5 良品上架 |
|
|
|
|
|
|
|
|
|
|
**三套码值不能互换。**
|
|
|
|
|
|
|
|
|
|
### 单据状态
|
|
|
|
|
|
|
|
|
|
API 154 回调的 `orderNoStatus` 含义**随 `orderNoType` 变化**:
|
|
|
|
|
|
|
|
|
|
| orderNoType | 5 的含义 | 80 的含义 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 1 入库计划单 | 审核通过 | — |
|
|
|
|
|
| 2/3 调拨 | 待审核 | 已完成 |
|
|
|
|
|
| 4 销售出库 | 已发货 | — |
|
|
|
|
|
| 5 退货认领 | 待处理 | — |
|
|
|
|
|
|
|
|
|
|
## 8. 单位
|
|
|
|
|
|
|
|
|
|
| 字段 | 单位 | 说明 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 库存 / 商品尺寸 | cm、g | 运去哪原值 |
|
|
|
|
|
| 调拨 `totalWeight` | **kg** | 真机确认(1 件 500g → 1000.0) |
|
|
|
|
|
| 调拨 `totalVolume` | m³ | 推测同口径 |
|
|
|
|
|
| 入库 `totalWeight` | kg | 文档明确 |
|
|
|
|
|
| 入库 `totalVolume` | CBM | 文档明确 |
|
|
|
|
|
| 轨迹 `parcel.weight` | oz → **已换算成 g** | 适配器内换算 |
|
|
|
|
|
| 轨迹 `parcel.length` | inch → **已换算成 cm** | 适配器内换算 |
|
|
|
|
|
|
|
|
|
|
## 9. 时区
|
|
|
|
|
|
|
|
|
|
仓方给的 `yyyy-MM-dd HH:mm:ss` **不带时区**,由调用方经 `WarehouseConnection` 传入:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
WarehouseConnection.of(
|
|
|
|
|
YqnConstants.PR_BASE_URL,
|
|
|
|
|
ChannelSecret.builder().appSecret(token).build(),
|
|
|
|
|
ZoneId.of("America/New_York")); // ← 按仓所在地传
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**未指定时按 UTC 解释,不猜成北京时间。**
|
|
|
|
|
|
|
|
|
|
## 9.5 商品查询(API 113)
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
POST /v1/product/findPage → Page<ProductInfo>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 页码从 0 开始
|
|
|
|
|
|
|
|
|
|
文档原文「起始页为从0开始」。统一模型的游标就是页码字符串,**不做 ±1 换算**——
|
|
|
|
|
空游标 = 第 0 页。这和运去哪其它分页接口(从 1 开始)不一致,容易踩。
|
|
|
|
|
|
|
|
|
|
### 单页上限 100,SKU 上限 100
|
|
|
|
|
|
|
|
|
|
`pageSize` 默认 100、最大 100;`skuList` 最大 100 个。超了各自本地拒绝。
|
|
|
|
|
|
|
|
|
|
### 只支持 SKU 过滤
|
|
|
|
|
|
|
|
|
|
运去哪这个接口没有条码 / 创建时间过滤,`ProductQuery` 里传了这两个会本地拒绝,
|
|
|
|
|
不静默忽略。
|
|
|
|
|
|
|
|
|
|
### 翻页优先看 `last`
|
|
|
|
|
|
|
|
|
|
响应是 Spring Data 风格,`last=true` 即末页。缺失时用 `number + 1 < totalPages`
|
|
|
|
|
推断,再缺失才按「本页是否满页」兜底。
|
|
|
|
|
|
|
|
|
|
### 成本要带币种才是 Money
|
|
|
|
|
|
|
|
|
|
`cost` 与 `currency` 是两列;没有币种时只保留数字会丢单位,所以
|
|
|
|
|
没有 `currency` 时 `cost()` 为 null。
|
|
|
|
|
|
|
|
|
|
## 10. 联调探针
|
|
|
|
|
|
|
|
|
|
两个探针,默认跳过:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 只读(7 个查询接口)
|
|
|
|
|
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
|
|
|
|
|
-Dyqn.probe=true \
|
|
|
|
|
-Dyqn.probe.token=<x-api-key> \
|
|
|
|
|
-Dyqn.probe.providerWarehouseId=RF_NY_US \
|
|
|
|
|
-Dtest=YqnReadOnlyProbeTest test
|
|
|
|
|
|
|
|
|
|
# 全链路(15 步,会真实创建单据,仅限 PR)
|
|
|
|
|
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
|
|
|
|
|
-Dyqn.probe.all=true \
|
|
|
|
|
-Dyqn.probe.token=<x-api-key> \
|
|
|
|
|
-Dyqn.probe.providerWarehouseId=RF_NY_US \
|
|
|
|
|
-Dtest=YqnFullFlowProbeTest test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
可选参数:`-Dyqn.probe.saleOrderNo` / `-Dyqn.probe.returnOrderNo` / `-Dyqn.probe.newSku`。
|
|
|
|
|
|
|
|
|
|
## 11. 未接入
|
|
|
|
|
|
|
|
|
|
| 项 | 原因 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 库存调整 | 运去哪无此接口 |
|
|
|
|
|
| 换货 / 无头件 / BOL | 仓方无对应接口 |
|
|
|
|
|
| 退货查询列表 | 只有按单号查,无列表接口 |
|
|
|
|
|
| 商品查询的条码 / 时间窗过滤 | API 113 只接受 skuList 与分页 |
|
|
|
|
|
| 出库列表 / 时间窗查询 | 只有按单号查 |
|