You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
chenchuchuan b5e94c1157 feat: 运去哪 / 易达云 商品查询接口 3 days ago
..
README.md feat: 运去哪 / 易达云 商品查询接口 3 days ago

README.md

运去哪(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 解释,不猜成北京时间。

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. 联调探针

两个探针,默认跳过:

# 只读(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 与分页
出库列表 / 时间窗查询 只有按单号查