运去哪(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 传入:
WarehouseConnection.of(
YqnConstants.PR_BASE_URL,
ChannelSecret.builder().appSecret(token).build(),
ZoneId.of("America/New_York")); // ← 按仓所在地传
未指定时按 UTC 解释,不猜成北京时间。
10. 联调探针
两个探针,默认跳过:
# 只读(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 |
仓方无对应接口 |
| 退货查询列表 |
只有按单号查,无列表接口 |
| 出库列表 / 时间窗查询 |
只有按单号查 |