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: 运去哪 / 易达云 商品查询接口 4 days ago
..
README.md feat: 运去哪 / 易达云 商品查询接口 4 days ago
TODO.md docs: 同步 CR 修复后的文档 4 days ago

README.md

易达云(EDAYUN)接入

当前状态:骨架

项 状态
模块 ✅ warehouse-sdk-edayun 已建、已注册
适配器 / 工厂 ✅ 类型就绪,能力位为空
获取 token ✅ 已对接(POST /oauth/token)
创建产品 ✅ 已对接(POST /webApi/skuInfo/v1/createProduct)
商品查询 ✅ 已对接(POST /webApi/skuInfo/v1/listProductPage)
创建出库单 ✅ 已对接(POST /webApi/order/v1/createOrder)
查询出库单 ✅ 已对接(POST /webApi/order/v1/getOrderInfo)
查询面单 ✅ 已对接(POST /webApi/order/v1/getOrderLabel)
取消前校验 ✅ 已对接(POST /webApi/order/v1/checkCancelStatus)
取消订单 ✅ 已对接(POST /webApi/order/v1/cancelOrder)
交易明细(账户流水) ✅ 已对接(POST /webApi/accountFlow/list)
订单费用明细 ✅ 已对接(POST /webApi/order/cost/v1/selectOrderCostInfoList)
仓租费用明细 ✅ 已对接(POST /webApi/order/cost/v1/selectUserRentDetailList)
费用试算(预估) ✅ 已对接(POST /webApi/estimate/v1/trial)
库存查询 ✅ 已对接(POST /webApi/userSkuStock/v1/queryInventory)
创建 / 编辑自发入库单 ✅ 已对接(POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder)
查询入库单 / 入库状态 ✅ 已对接(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)
打印 SKU 标 ⚠️ 已实现(POST /webApi/entryInfo/v1/newPrintCaseMark),真机未启用
承运商清单(客户自有物流) ✅ 已对接(POST /webApi/carrier/v1/listCarrierByWarehouse)
仓库清单 ✅ 已对接(warehouse/listWarehouseHasPerm + warehouse/listActive)
其它业务接口 ⬜ 等文档
回调 ⬜ 等文档
真机验证 ⬜ 等测试环境

骨架阶段的行为:任何业务调用都会抛 WarehouseUnsupportedCapabilityException——这是有意为之,不返回空集合。

鉴权(已确认部分)

① POST /oauth/token
     body: { "client_id": "OMS授权用户名", "client_secret": "密码" }
     无业务请求头
     → 返回 token

② 业务请求头
     token      来自 ①
     appKey     测试: 7289ded35b198243883151876eaf3213
     timestamp  毫秒,5 分钟内有效
     sign       MD5(body + "." + appSecret),测试环境可传 openApiAdminSecret 免签

凭据映射(复用 ChannelSecret):

易达云 ChannelSecret
appKey(请求头) appKey()
appSecret(签名用) appSecret()
client_id(换 token) clientId()
client_secret(换 token) clientSecret()

代码位置:

类 职责
auth/EdayunTokenClient 换 token,兼容三种响应形态,按 code 区分可重试
http/EdayunRequestFactory 构造 token 请求与业务请求;sign() 算 MD5
adapter/EdayunAdapter.token(ctx) 走 TokenManager 缓存(按 appKey + clientId 维度)

真机验证(2026-11-12,PR 环境):

POST https://test.omniselling.com.cn/saas-service/openapi/microService/oauth/token
Content-Type: application/json
{"client_id":"openapi-test","client_secret":"123456"}

→ HTTP 200
{"access_token":"0dabff46-...","token_type":"bearer","scope":"server"}
之前不确定的 实测结论
响应体结构 扁平结构,没有 code、没有 data 包裹
业务码 不返回 code;HTTP 200 + 有 access_token 即成功
有效期 响应里没有有效期字段(文档说「永久,建议留窗口刷新」)
refreshToken 不返回

因此实现调整为:

  • 缺 code 不算失败,交给「有没有 access_token」判断
  • expiresAt 是估算值(按 2 小时兜底),作用只是让 TokenManager 定期重登一次,不是真的到期
  • 兼容分支(data.access_token / 顶层 token)保留,生产确认后可删

创建产品

POST /webApi/skuInfo/v1/createProduct
请求头:Authorization: Bearer <token> / appKey / timestamp / sign

三处反向标志(最容易错)

易达云的布尔字段是 0 是 / 1 否,与直觉相反:

字段 0 1
brandFlag 是品牌 非品牌
logisticsPackagingType 自带物流包装 不带
electricFlag 带电 不带电
isMetalMaterial 含钢铁铝 不含

统一封装在 EdayunYesNo,不要手写 x ? 0 : 1——方向很容易写反。

单位

项 标准模型 易达云
重量 克 千克
尺寸 cm cm

换算在 EdayunProductMapper.gramsToKg。

申报信息必须出口 + 进口各一条

文档:「进出口都要传:一个 sku 至少需要一个出口申报信息和一个进口申报信息」。

但标准模型只有一组申报字段(HS / 原产国 / 申报价值)。当前做法:

  • 出口:国家 = countryOfOrigin
  • 进口:国家默认 US(DEFAULT_IMPORT_COUNTRY,待业务确认)
  • 两者共用同一个申报价值

缺申报价值或原产国时整组不下发,由仓方报错,不在本地编造。

标准模型没有、暂时硬编码的字段

字段 当前值 说明
logisticsPackagingType 0 统一模型没有「是否自带物流包装」
pmFlag false 统一模型没有包材概念
electricFlag 1 统一模型没有带电信息(默认不带电)
brandFlag 按 customItemNo 有无推 有客户编码算品牌

这几项等业务确认后,可能要在 WarehouseProduct 上加字段。

探针

# dry-run:只打印要发的报文,不调用
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false     -Dedayun.probe.product=true -Dtest=EdayunCreateProductProbeTest test

# 真跑(会在测试仓建档,用 PROBE- 前缀的随机 SKU)
... -Dedayun.probe.write=true     -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...

商品查询

POST /webApi/skuInfo/v1/listProductPage → Page<ProductInfo>

三个坑

1. SKU 是逗号拼接的单个字符串,且一次最多 50 个。

req.skuCode = String.join(",", query.providerSkus());   // "A,B,C"

统一模型是 List<String>,超 50 本地拒绝(不截断)。

2. 没有数据时回 code=500, msg=查询无数据。

这是「查不到」不是「调用失败」,按空页处理——与轨迹接口的「未匹配到轨迹」同一处理。 其它 500 仍抛异常。

3. 查询条件全空时默认只查最近一个月。

ybtest 创建于 2021 年,不带时间窗就查不到。查老数据必须显式给时间窗。

尺寸取实际值,缺失才回落预报值

易达云 我们用的
length/width/height/weight 优先(仓方当前存的值)
forecastLength/... 实际值缺失时回落

真机对比很能说明问题:ybtest 的 length 是 55(实际量过), forecastLength 是 10(预报时填的)——两者差 5 倍,拿错会算错运费。

页码从 1 开始,单页最多 200

真机验证(2026-11-17)

场景 结果
只给 pageNum/pageSize(不带时间窗) total=52244(全量)
skuCode=ybtest total=1,实际尺寸 55×4×3、重量 1
skuCode=ybtest + 最近 30 天窗口 code=500 查询无数据(该 SKU 建于 2021)
不存在的 SKU / 条码 同样「查询无数据」
10 年窗口 + ybtest 1 行,createdAt=2021-02-04

SKU 是仓侧 SKU:ybtest 既是 OMS SKU 也是建档时下发的 providerSku, 所以看不出口径差异;若两者不同,必须传仓侧那串(见下方「SKU 口径」)。

创建出库单

POST /webApi/order/v1/createOrder
请求头:Authorization: Bearer <token> / appKey / timestamp / sign

幂等键是 poNumber

文档原话:「取消重推订单的话,请保证相同订单的平台单号(poNumber)跟之前的一样」。

映射:OutboundCommand.orderRef() 优先,缺失时退回 outboundRequestNo()。 不能为 null——它是仓侧唯一幂等依据。

时间戳是毫秒

promiseShipTime 是毫秒时间戳(文档示例 1777281423744),不是秒。

地址要州全称

字段 我们要传的
destProvinceName California,不是 CA

标准模型的 ShipTo.stateOrProvince 通常是二字码(CA)。当前原样透传, 所以调用方要么直接给全称,要么需要一张州码映射表——待业务确认。

面单:要 URL,不是 base64

文档要求「物流产品 + 面单信息(carrierName / trackingNo / labels)」两个条件缺一不可, 且 labels 是「完整的可访问文件 URL」。

我们的 labelContentBase64 语义是 base64 内容,所以:

  • 传 https://... → 透传到 labels
  • 传 base64 → 本地直接拒绝,提示先上传拿 URL

商品行 unitPrice 是单价

文档写 unitPrice,所以直接取 OutboundLine.declareValue(),不乘数量。 (注意:运去哪的 skuAmount 是总额,是反的。)

增值服务

标准模型 易达云 addService
signatureRequired = true is_signature

保价:任意商品行带 insuredAmount 就整单下发 is_insurance——addService 是订单级开关,易达云没有行级保价。

查询出库单 / 面单

POST /webApi/order/v1/getOrderInfo     → OutboundOrder
POST /webApi/order/v1/getOrderLabel    → List<PackageResult>(含 labelRef)

两个接口都是 orderNo(仓侧单号)与 poNumber(我们的来源单号)二选一。 实现优先用 outboundRequestNo 当 poNumber,没有才用 providerOrderId 当 orderNo。

状态映射(24 个取值折叠)

文档给了 24 个状态,按「宿主是否需要区分」折叠:

类别 易达云取值 统一状态
待发货 ReadyToShip SUBMITTED
发货中 Shipment PICKING
已发货 Shipped / Online / Delivered / Returns SHIPPED
已取消 Cancelled / InterceptSuccess CANCELLED
异常(19 个) DistrError / NoCarrier / InvError / StockLack … EXCEPTION

异常类全部归 EXCEPTION,具体原因看 exceptionCode()(来自 errorMsg)与 rawStatus。宿主对它们的处理都是「人工介入」,不需要 19 个细分状态。

注意 Shipment(发货中)不能因为含 Ship 就判成已发货——精确匹配,不做子串。

面单:多包裹按位置对应

"trackingNo": "1Z111,1Z222",
"labels":     "https://oss/1.png,https://oss/2.png"

一个包裹(trackingNo)对应一个面单 URL,按逗号位置一一匹配。 输出到 PackageResult.trackingNumber() 与 PackageResult.labelRef()。

地址:同时给了二字码和全称

getOrderInfo 的地址里两套都有:

字段 示例
destProvince CA
destProvinceName California

标准模型口径是二字码,所以优先取 destProvince,缺失才用全称。

取消前校验 / 取消

POST /webApi/order/v1/checkCancelStatus   → CancelEligibility
POST /webApi/order/v1/cancelOrder         → CancelResult

取消资格映射

易达云 data 含义 统一资格
Published 可直接取消,不收费 FREE
Shipment 可取消,收费 CHARGED
Cancelled / InterceptSuccess 已取消 / 拦截成功 BLOCKED
InterceptProcessing / InterceptFailure 拦截中 / 拦截失败 BLOCKED
UnableCancel 状态不允许 BLOCKED
未知值 — BLOCKED

未知一律归 BLOCKED:取消有代价(可能收费、不可逆),认不出时宁可拒绝。

文档笔误

响应说明里 InterceptSuccess 出现了两次(一次是「拦截取消成功」、 一次是「拦截取消失败」)。按订单状态字典的命名,失败按 InterceptFailure 处理。

请求体优先级

两个接口请求体相同:orderNo(仓侧 ORD 单号)优先级高于 poNumber(我们的来源单号)。 实现里两个都给,让仓方按优先级取。

不做「收费必须 acceptCharge」拦截

checkCancel 与 cancel 是两次调用,中间状态可能变化;是否在 CHARGED 时继续取消 由宿主决定。CancelResult.rawStatus() 回填仓方的 msg(如「订单已出库」)。

cancel 返回 data=false 时不是异常——表示仓侧拒绝,msg 带原因。

本期未接的出库能力

query(列表查询)显式抛 WarehouseUnsupportedCapabilityException——文档还没给。

交易明细(费用)

POST /webApi/accountFlow/list → List<BillingDocument>

三条与其它仓不同的口径

① 同一单号的同一计费项有多条数据——不去重

文档原文:「同一个单号(ORD-发货单 / REV-收货单)的某个计费项有多条数据」。

所以每条流水都映射成一条 BillingDocument,靠 serialNumber()(账户流水号)区分。 按单号去重会丢账。

② 金额是 string 且可为负

"billingAmount": "-0.500"

负数 = 扣费,正数 = 充值 / 退费。不能取绝对值——那会让扣费和退费变成同一笔。

③ 币种有两个,优先账户币种

字段 含义
accountCurrency 账户币种(优先)
originalCurrency 原币

跨币种账户时两者不同,exchangeRate 是汇率。

查询约束

约束 处理
没给业务单号时,时间段必填 不传 bizNo 又没有时间窗 → 本地拒绝
时间段不能超过 180 天 超过且没有 bizNo → 本地拒绝
pageNum / pageSize 必填 固定第 1 页、每页 200(上限)
bizNo 支持模糊匹配 文档标注「不建议」,我们按精确值传

分页:当前只取第一页(200 条),超过时截断。需要翻页的话要扩展——见 TODO。

计费项分类

billingCode 是编码(如 farawayFee)而不是分类码,只能按关键字推断:

关键字 归类
storage / warehouse STORAGE
operation / handle / handling OPERATION
freight / shipping / delivery / faraway / remote LAST_MILE
service / value / pack / label VALUE_ADDED
认不出 null(不猜)

对账时宁可不分类,也不能分错。

统一模型扩展

FeeQuery 新增 计费时间窗(settledAfter() / settledBefore()), 与已有的「快照日期」(snapshotStartDate,运去哪按仓储费快照查)语义不同:

字段 用于
snapshotStartDate/EndDate 运去哪仓储费的快照日期
settledAfter/Before 易达云按 billingTime 查

BillingDocument 新增 serialNumber()(流水号)与 accountBalance()(变动后余额)。

订单费用明细

POST /webApi/order/cost/v1/selectOrderCostInfoList → List<BillingDocument>

与交易明细的区别(两个都是费用,但口径完全不同):

交易明细 accountFlow/list 订单费用 selectOrderCostInfoList
视角 账户流水 按订单拆的费用报价
金额 billingAmount(string,可为负) 应收 / 折扣 / 实付 三个
粒度 一条流水一个计费项 一个订单展开成多条计费项
附带 账户余额、汇率 计费重、计费分区、是否偏远

金额取实付

每个计费项有三个金额:

"amountReceivable": 20.187,   // 应收
"discountPrice": 5.745,       // 折扣
"realPayPrice": 14.442        // 实付

落库金额取 realPayPrice——对账要以实际发生为准,应收只是报价。

一个订单展开成多条

响应结构是 rows[] → chargeDetails[] → feeDetails[],按计费项展开:

一个订单 → 「尾程-运费」「尾程-出库处理费」… 各一条 BillingDocument

多条记录的 documentNo 相同,靠 feeName 区分。

若某层只有 chargeDetails 汇总、没有 feeDetails,按汇总记一条「订单费用」。

单号类型要配合

"type": 0,        // 0 订单号 / 1 平台单号 / 2 追踪号
"orderNo": "..."

统一模型新增 FeeQuery.noType()(FeeQueryNoType 枚举)。 传了不支持的类型会显式拒绝——静默按别的口径查会让对账金额对不上。

时间窗 ≤ 3 个月

文档写明「最大查询 3 个月」。超过在本地拒绝。

既没有单号也没有时间窗时同样拒绝(避免拉全量)。

费用类型按中文名推断

billingName 是中文(如「尾程-出库处理费」),按关键字归类:

关键字 归类
仓储 / storage / 仓租 STORAGE
处理费 / operation / 操作 OPERATION
尾程 / 运费 / 燃油 / 附加费 LAST_MILE
增值 / 贴标 / 打包 VALUE_ADDED
认不出 null(不猜)

仓租费用明细

POST /webApi/order/cost/v1/selectUserRentDetailList → List<BillingDocument>

三个费用接口的分工

交易明细 accountFlow/list 订单费用 selectOrderCostInfoList 仓租 selectUserRentDetailList
视角 账户流水 按订单拆的费用报价 按 SKU + 计费日逐条
费用类型 全部 全部 只有仓储费
金额 billingAmount(string,可负) 应收 / 折扣 / 实付 rentPrice(实收)
独有 账户余额、汇率 计费重、计费分区 租期天数、库存件数、计费体积

时间窗:必填,且「3 个月」的阈值很怪

billDateBegin / billDateEnd 都必填(缺了报「请选择计费起止时间」)。 真机实测(2026-11-13)边界既不是自然月也不是固定天数:

窗口 天数 结果
6/1 ~ 10/1 122 ✅ 通过
6/2 ~ 10/2 122 ❌ 拒绝
7/2 ~ 10/31 121 ✅ 通过
7/1 ~ 10/31 122 ❌ 拒绝
6/1 ~ 11/1 153 ❌ 拒绝

同样的天数、不同的起点,结果不同——所以没法在本地精确复刻。

本地守卫(EdayunQueryWindows)因此只挡明显超限:超过「+4 个月」直接拒, 挡住「一次拉一年」这类错误;3~4 个月之间放行,由仓方返回 code=500, msg=计费时间范围不能超过3个月。订单费用明细用的是同一个守卫。

warehouseIds 是数字

providerWarehouseId 必须是易达云的数字仓 id(如 98)。配成 EDY-WH-1 这类 OMS 编码会在本地被拒绝——仓侧对非数字是静默查不到,不报错。

金额取 rentPrice,币种按原值

"originalPrice": 2.278, "discountPrice": 0, "currencyCode": "CAD", "rentPrice": 2.278

rentPrice 缺失时用 originalPrice - discountPrice 兜底,两者都没有才记 0。 币种按 currencyCode 原值(示例是 CAD),不默认 USD—— 易达云这里不写死币种。

翻页上限 200 页,超了显式失败

仓租按 SKU + 天出账,3 个月窗口下可能上万条。适配器一页 200 条、最多 20 页 (4000 条);拉满仍有剩余时抛异常而不是截断——少算仓租会让对账金额偏小。 遇到时请缩小时间窗再查。

终止条件只看「本页是否满 200 条」:不满即到底。文档里的 total 是总行数还是 总页数尚未确认,所以不拿它当终止条件。

费用类型固定 STORAGE

这是仓租专口,费用类型不按 billingName 猜,直接归 STORAGE。 若宿主传了别的 costType,或传了运去哪口径的快照日期,都显式拒绝。

独有字段不进统一模型

租期天数、库存件数、计费体积、单价这些只在 DTO 里(EdayunRentDetailDtos.RentDetailRow), BillingDocument 只落金额 / 计费日 / SKU / 单据号。也就是说统一模型拿不到 「这笔是不是按 CBFT 计的」——需要的话再扩展模型。

真机验证(2026-11-13,PR 环境)

POST /webApi/order/cost/v1/selectUserRentDetailList
{"pageNum":1,"pageSize":200,"billDateBegin":...,"billDateEnd":...}
结论 说明
接口通 任何窗口都返回 {"total":0,"rows":[],"code":200}
没有数据 2025-01 ~ 2026-12 逐季扫过,全部为空——映射未在真机验证
校验都在 pageSize>200 → 「每页数量最多200」;warehouseIds>20 → 「仓库最多20个」;起止反了 → 「起始计费时间应小于等于结束时间」
很慢 pageSize=200 单页 6~13 秒(45 天窗口 1.3 秒)。探针把读超时调到 120 秒
warehouseIds 容错 传 "98" 字符串也接受(文档写 num_array)

仓租 Mapping 目前只有单测覆盖(EdayunRentDetailTest 16 个)。等仓方在 PR 环境 造出仓租数据后,用探针跑一次拿到真实 rows 再校正。

探针

# dry-run:只打印报文(不联网)
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
    -Dedayun.probe.rent=true -Dtest=EdayunRentProbeTest test

# 真查(只读)
... -Dedayun.probe.rent=true -Dedayun.probe.call=true \
    -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
    -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
    -Dedayun.probe.warehouseId=98 [-Dedayun.probe.days=30] [-Dedayun.probe.bizNo=...]

费用试算(预估)

POST /webApi/estimate/v1/trial → List<FeeEstimateResult>

三种预估方式,我们只做「按包裹」

方式 触发条件 我们的实现
虚拟包裹 hasOutboundFeeInputSkuSwitch=true + virtualPackageDetails ❌ 不下发
按包裹 manualInputSwitch=true + packageDetails ✅ 唯一路径
按 SKU manualInputSwitch=false + skuInfoDetails ❌ 标准模型没有 SKU 清单

标准模型 FeeEstimateQuery 只带包裹尺寸重量,所以固定走「按包裹」。

三处定值

字段 值 原因
manualInputSwitch true 按 SKU 预估要 SKU 清单
estimatedGoodsType GENERAL_CARGO 真机实测:缺了报「手动输入时,货物类型[estimatedGoodsType]不能为空!」;标准模型没有带电信息
packageDetails 单元素数组 文档:目前仅支持单包裹

仓:id 或 code 二选一

warehouseId / warehouseCode 文档要求必填一个。providerWarehouseId 是数字就进 warehouseId,非数字(如 USLA)进 warehouseCode。 两者都没有时本地拒绝。

物流产品 id 只认数字

logisticsProductIds 要的是数字 id。统一模型的 logisticsServiceCode / logisticsProductCode 是字符串,非数字直接不下发——让仓方返回全部渠道报价, 比传一个查不到的字符串好。logisticsProductCode 优先。

响应:只取 successItems

{"data":{"successItems":[有报价的渠道],"failItems":[无报价的渠道],"showError":false,"errorInfo":null}}

真机(warehouseId=2, 91761, 22×22×22cm 1000g):successItems 4 条、 failItems 25 条(全是「不支持派送」)。

  • successItems → CarrierQuote(承运商名取 logisticProductName,渠道码取 logisticProductId)
  • failItems → 丢弃。它们没有金额,混进结果就是一堆假渠道
  • 全部失败时返回 carriers() 为空的仓结果——按能力接口约定表示「该仓无法承运」, 具体原因(errorInfo,如「没有物流产品符合预估!」)只在原报文里

重量单位:请求 g、响应 kg

请求 packageDetails[].weight 是克;响应 weight 是 kg (请求 1000g → 响应 1.000)。映射时不要把响应重量当克回写。

真机验证(2026-11-13,PR 环境)

场景 结果
warehouseId=2 + 91761 ✅ 4 个渠道,最低 5.315 USD(美国经济派送)
warehouseId=194 ✅ 同样 4 个渠道(首次跑超时,重试正常)
warehouseCode=USLA ✅ 与数字 id 等价
日本邮编 100-0001 + 仓 2 ✅ code=200,successItems 为空、errorInfo=没有物流产品符合预估!
200×200×200cm / 643kg ✅ code=200,全部失败(同上)
按 SKU 预估 ❌ sku[zicoyuio1]信息不存在,请确认!(PR 环境没建这个 SKU)
虚拟包裹 ❌ 内部服务器错误
estimatedGoodsType 传 FOO ❌ 被当成未填
缺 manualInputSwitch ❌ 当成按 SKU 预估

超时:首次调用常报 Read timed out executing POST http://eda-tms/..., 重试即好。探针读超时按 120 秒设,业务侧建议至少 30 秒以上并允许重试。

创建 / 编辑自发入库单

POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder
→ InboundReceipt(inboundRequestNo, entryCode)

自发入库单 = 卖家自己备货、自己找代理送到 EDA 仓,物流信息由卖家维护。

一个接口三种语义,靠 saveType

saveType 含义 SDK 入口
0 新增(草稿) 未暴露(探针可传)
1 更新 improve(ctx, entryCode, cmd)
2 保存并发布 create(ctx, cmd)

create 直接走 2(保存并发布),不复刻「存草稿 → 再发布」两步。

improve 必须给 仓侧 entryCode(如 REV25052032239),不是我们的来源单号; 缺了本地拒绝——否则会变成新建,把单子建重复。

只下发三组,四组服务块不下发

组 下发 说明
basicInfo ✅ 仓、柜型、头程运输方式
logisticsInfo ✅ 柜号、预计离港 / 到港
cargoInfos ✅ 箱规 + 箱内 SKU
domesticTrailerInfo(头程拖车) ❌ 标准模型无字段
customsDeclarationInfo(出口报关) ❌ 同上
customsClearanceInfo(进口清关) ❌ 同上
overseasTrailerInfo(海外拖车) ❌ 同上

这四组按「物流产品服务范围」条件必填。标准模型没有对应字段,不编造—— 需要时仓方报错,由宿主走人工。要支持得先扩 InboundCommand。

cargoInfos 只来自箱规

创建时 cargoInfos 是必填,但只有 InboundCarton 带箱长 / 宽 / 高 / 重。 只给 lines() 没有箱规 → 本地拒绝,不凭空编一个箱子。

一箱多 SKU:InboundCarton 里同一 sid 的多行按 sid 归并成一个 cargoInfo, 下面挂多条 boxSkuInfoList;sid 缺失时用箱码归并。

重量 g → kg(与创建产品口径一致,/1000)。尺寸 / 重量为 0 视为未填不下发。

快递类 / 卡车类的条件必填,我们没有

服务范围 仓方要求 标准模型
海快 / 空运 / 快递 shipCompany(承运商)+ waybill(跟踪单号) ❌ 无字段
卡车 estimatedDepartureTime(预计离港) ✅ predictionShipDate

快递类的两个字段不下发,发布时由仓方报错。不要把柜号塞进 waybill —— 那是两回事。

几个字段的本地约定

字段 来源 说明
customerOrderNo inboundRequestNo 上限 30,超了本地拒绝(不让仓方静默截断)
shelfWarehouseId / shelfWarehouseCode cmd.warehouseId() 优先,否则账户配置 数字走 id,非数字走 code
cabinetType cmd.cabinetType() 字符串码 → 数字,非数字视为未给
intShippingMethod cmd.transportType() 已经是仓方口径的码
shippingProductId — 来自「查询入库物流产品」,标准模型无字段

入库状态:靠 SKU 明细接口反推

创建只返回 entryCode,不带状态。状态从 POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail 拿(下文)。

入库单查询 / 状态

POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail → InboundOrder

按入库单号查 SKU 级的预报 / 清点 / 上架信息,一行一个 SKU。

只能按 entryCode 查

{"entryCode": "REV24050738176", "pageSize": 200, "pageNum": 1}

entryCode 是创建时返回的 REV 单号,不能按客户单号查。所以 get(ctx, inboundRef) 的入参必须是 REV 号;query(ctx, cursor) 同样把 cursor 当 REV 号用(接口没有列表 / 时间窗),传空直接拒绝,不假装支持增量同步。

创建返回的 entryCode 落库后就是查询键——这个要存好。

数量三层

易达云 统一模型 说明
forecastQuantity plannedQuantity 预报数量
actualCheckedQuantity packedQuantity 实际清点
shelvesQuantity receivedQuantity 上架数量

头级数量是各行求和。firstripQuantity(头程数量)没有对应字段,不映射。

单头状态由 SKU 状态汇总

接口只给 SKU 级 status / statusName,没有单头状态。汇总规则: 取最靠前的那个状态(InboundStatus.code() 数值小的优先), 即「还有 SKU 没上架,整单就不算完成」。全部认不出才归 UNKNOWN。

状态码表只确认了一个

码 状态名 统一状态
4 已上架 COMPLETED
其它 — 按中文名兜底推断,认不出 UNKNOWN

中文名兜底关键字:取消/作废/驳回 → CANCELLED;上架中 → STORING; 已上架/完成 → COMPLETED;清点/收货/卸柜/签收 → RECEIVING; 在途/运输/离港/到港 → IN_TRANSIT;待/预报/草稿 → PENDING_SHIPMENT。

中文名兜底是临时方案——名字随语言 / 配置变就会失效。拿到码表后要换成精确码值, 见 TODO #34。

接口回不了的字段

字段 情况
仓库 接口不回,用 OMS 配置的 warehouseCode
创建 / 到仓 / 上架时间 接口不回,全部为 null
箱明细 boxes 接口是 SKU 维度,没有箱号
承运商 / 柜号 / 批次 接口不回

所以 InboundOrder 只是「数量 + 状态 + SKU 行」的骨架,不是完整单据。 要完整信息需要 entryInfo 的单头查询接口(文档还没给)。

翻页

pageSize 固定 200(文档上限 1000),按「本页是否满页」判断到底,最多 20 页 (4000 个 SKU);超了显式失败而不是截断。

探针

# 只读,不加 write 也会真查
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
    -Dedayun.probe.inboundQuery=true -Dtest=EdayunInboundQueryProbeTest test

探针

# dry-run:只打印报文(不联网)
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
    -Dedayun.probe.inbound=true -Dtest=EdayunInboundProbeTest test

# 真发一次(写操作,会在测试仓建入库单,客户单号用 PROBE- 前缀)
... -Dedayun.probe.inbound=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.saveType=0]

库存查询

POST /webApi/userSkuStock/v1/queryInventory → Page<InventorySnapshot>

一行 = 一个 SKU 在一个仓的库存汇总。默认只返回总库存大于 0 的数据, 单页最多 500 条。

字段映射

易达云 统一模型 说明
stock available 可用库存
totalStock onHand 总库存
frozenStock reserved 冻结库存
toDeliverStock pendingOutbound 待出库
inTransitStock inTransit 在途
safeStock alertQuantity 安全库存(预警)
skuName productName
warehouseCode warehouseCode 缺失时回退 OMS 仓编码

零库存开关是反的

统一模型是「包含零库存」,仓方是「只查总库存大于 0」:

includeZeroStock totalStockGreaterThanZero
null 不下发(仓方默认 true)
true false
false true

同步策略:全量拉取

接口没有时间维度,syncStrategy() 固定 FULL_PULL_DIFF,updatedAfter 不生效。 响应也没有更新时间,asOfUtc 用调用方注入的时钟。

约束

约束 处理
skuCodeList 最多 100 个 超过本地拒绝
warehouseIdList 是数字 id 非数字本地拒绝(同仓租明细)
分页 游标是页码字符串;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 不在统一模型里。整行按 inventoryType = 0(可售)落,不可售数量被丢弃—— 需要对账不可售库存时要扩展模型,见 TODO。

探针

# dry-run:只打印报文(不联网)
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
    -Dedayun.probe.inventory=true -Dtest=EdayunInventoryProbeTest test

# 真查(只读)
... -Dedayun.probe.inventory=true -Dedayun.probe.call=true \
    -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
    -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
    [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.sku=ybtest] \
    [-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 就是退货单号

{"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(ReturnQuery) ✅ 已实现(selectRmaInfoList)
process(ctx, cmd) ❌ 要仓侧明细行 id,而详情响应里没有行 id(checkList / skuList / shelfList 都没有)

process 抛 WarehouseUnsupportedCapabilityException,不返回空列表。

探针

# 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 产出):

{"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 是布尔值,不是单号:

{"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

请求体是纯字符串数组

["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 环境没有任何可查到的轨迹,映射只被单测覆盖。

打印箱唛 / SKU 标

两个端点名与实际语义是反的

已与仓方确认:

端点 实际打印 我们的方法 能力位
/webApi/skuInfo/v2/printBarcode 箱唛(外箱标) printCaseMarks(...) CASE_MARK_PRINT
/webApi/entryInfo/v1/newPrintCaseMark SKU 标 printSkuLabel(...) 走入库 SKU_LABEL 语义

不要被路径名误导。代码里两个方法的 javadoc 都写了这条提醒。

箱唛(printBarcode)

POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel

请求体按 SKU 列表打,服务端把每个 SKU 的条码排版成箱唛 PDF。

四种纸张尺寸实测(MediaBox,单位 pt):

pageSize 文档标称 实测 MediaBox 折算
0 7×3cm 198 × 85 69.9 × 30.0 mm
1 10×6cm 284 × 170 100.2 × 60.0 mm
2 6×4cm 283 × 425 99.9 × 150.0 mm
3 A4 170 × 113 60.0 × 39.9 mm

pageSize=2 和 pageSize=3 的文档标称与实际相反:文档说 2 是「6×4cm」、 3 是「A4」,实际 2 打出来是 100×150mm、3 打出来是 60×40mm。 枚举按实测尺寸命名(SIZE_60_40 / SIZE_100_150),码值原样保留。

本地提前挡的两条(仓方都回「内部服务器错误」,看不出原因):

约束 本地行为
SKU 数 > 50 构造期拒绝(仓方提示「最多打印50个SKU」)
份数 ≤ 0 构造期拒绝

isPrintSkuName 只在 true 时下发,false 交给仓方默认。

真机(2026-11-16):ybtest 拿到真实 PDF,四种纸张都 code=200。 仓方其它校验:缺 productInfos →「产品信息不能为空」、缺 pageSize → 「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。

SKU 标(newPrintCaseMark)

POST /webApi/entryInfo/v1/newPrintCaseMark → WarehouseLabel

真机未启用:PR 环境该路径报「接口不存在或未启用」,去掉 ContentType 后缀的 newPrintCaseMark 能过参数校验(缺 pageSize 报 「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」),但补全后一律 「内部服务器错误」。所以本接口实现是按文档写的,映射只有单测覆盖。

纸张码值不连续:100×100=4 / 100×150=2 / A4=5。统一枚举 LabelSizeType 为此补了 A4。

统一模型的 BoxLabelCommand 没有「选哪些箱」,默认整单打印;部分箱用 printSkuLabel(ctx, cmd, CaseSelection) 重载(系统箱号 / SKU / 箱序号区间 / 客户箱号区间四选一,全空本地拒)。

madeInChina 与 separation 是易达云特有语义,统一模型没有对应概念 → 默认关。

承运商清单(客户自有物流服务)

POST /webApi/carrier/v1/listCarrierByWarehouse → List<WarehouseCarrier>

客户自有物流(自有物流 + 客户上传面单)下单时要用:carrierName 可以填承运商名, 也可以用某个下属物流服务的名字。

两层结构

承运商(carrierId / carrierNameEn / carrierNameCn)
  └── 物流服务(logisticId / logisticName)

统一模型新增 WarehouseCarrier(带 logists()),挂到 WarehouseDirectoryCapable.carrierDirectory(ctx),门面 carrierDirectory()。

原有的 carriers() 返回 List<String>(只有码),保留不动; carrierDirectory() 的默认实现会把 carriers() 的码包装成无名条目, 能给出结构的仓覆盖它。

ownLogisticList 文档写成对象、真机是数组

"ownLogisticList": [ {"logisticId":"583","logisticName":"..."}, ... ]

DTO 按 List 收。

入参

字段 我们的值
warehouseId 账户配置的 providerWarehouseId(数字);非数字/为空时不传
countryCode 本地不传(统一模型没有对应字段)

真机验证(2026-11-16)

场景 结果
仓 2 11 个承运商,FedEx 下有 12 个物流服务
不传仓 22 个承运商
countryCode=US 10 个承运商

仓库清单

见下面的「仓库清单」一节——warehouses() 现在有实现了。

仓库清单

两个接口用途完全不同,不要混用:

接口 含义 实测条数 我们的方法
warehouse/listWarehouseHasPerm 当前客户有权限的仓 69(跳过 -999 后 68) warehouses(ctx)
warehouse/listActive 平台全量激活仓 118 activeWarehouses(ctx, inbound)

listActive 含当前客户没授权的仓(68 个有权限的仓里,有 50 个不在里面), 所以给客户选仓必须用 warehouses()。

-999 是「智能分仓」哨兵值

listWarehouseHasPerm 最后一条固定是:

{"warehouseId":"-999","warehouseName":"使用分仓规则","warehouseNameEn":"divideWarehouse",
 "warehouseCode":"USMC", ...其余全 null}

不是真实仓,映射时跳过——和物流产品接口的 -998 是同一套路。

listActive 的 warehouseOperationType

值 含义 实测
0 尾程仓 111 条
1 头程仓 7 条
不传 两者之和 118 条

文档说必填,实测不传也能通。activeWarehouses(ctx, inboundWarehouse) 会明确传 0 或 1。

统一模型的口径

WarehouseFacility.warehouseCode() 放的是仓编码(USLA / USALA-Q031), 数字 id(2 / 40269)进 providerWarehouseId()——两者不能互换。

字段映射:

易达云 统一模型 备注
warehouseCode warehouseCode 下单用
warehouseId providerWarehouseId 数字,字符串形式
warehouseName name 缺失回退英文名
address address1 仓方只给单行地址
provinceCode province / state 两个字段都填
warehouseManagerName / Tel contactName / mobilePhone 仅 listActive 有

两个接口的字段数差很多

listActive 返回 47 个字段(容量、营业时间、负责人邮箱、地图链接等), listWarehouseHasPerm 只有 17 个。DTO 只声明统一模型用得上的十几个—— Jackson 会忽略未知字段。

SKU 口径:传的是 OMS SKU 还是仓侧 SKU?

结论:两边都必须是仓侧 SKU(建档时下发的那串)。

代码依据:

  • 建档:YqnProductMapper.skuOf() / EdayunProductMapper.skuOf() 都是 providerSku 优先,为空才回退 omsSku
  • 出库行:OutboundLine 同时有 omsSku 与 providerSku,映射时同样 providerSku 优先
  • 商品查询:ProductQuery.providerSkus() 是仓侧 SKU,SDK 不做 OMS→仓侧转换

所以仓方库里存的永远是「我们建档时下发的那串」。如果宿主给 providerSku 建了档,那么查询也必须用它;只有两者相同时(如 ybtest)才能混用。

SDK 不会静默转换的原因:OMS→仓侧 SKU 的映射表在宿主手里(供应商编码规则、 按仓不同的前缀等),SDK 猜不出来。查错了会拿到空结果或错的商品,比报错更难发现。

待确认(问易达云)

# 要确认
1 后续业务接口文档(出库 / 库存 / 费用 / 回调)
2 测试环境 ✅ 已确认:test.omniselling.com.cn + openapi-test
3 申报信息的进口国怎么取(当前默认 US,是猜的)
4 declarationType 的码值(0 出口 / 1 进口,是推断的)
5 统一模型缺的字段(带电 / 包材 / 物流包装)要不要加到 WarehouseProduct
4 限流:每秒许可数、单日配额
5 能否在 PR 环境走写操作(建单 / 取消 / 销毁),决定探针设计
6 回调:验签算法、时间戳单位、响应体格式、是否按路径区分
7 费用口径:是否有费用类型码(运去哪只有中文名)
8 库存同步:支持按时间增量还是只能全量

骨架已定的部分

warehouse-sdk-edayun/
├── pom.xml
└── src/main/java/common/ecommerce/edayun/
    ├── EdayunConstants.java          端点 / 路径 / 限流(带 TODO 占位)
    ├── adapter/
    │   ├── EdayunAdapter.java        能力位为空,未实现能力不声明
    │   └── EdayunAdapterFactory.java
    ├── dto/package-info.java         一个接口一个文件
    ├── enums/package-info.java       平台枚举约定
    ├── http/package-info.java        信封校验约定
    └── webhook/package-info.java     回调约定

测试:EdayunAdapterTest(5 个)验证类型接对、能力位为空、 未实现能力显式拒绝、注册后可解析、能力查询不触发真实 API。

接下来怎么推进

按 onboarding-checklist.md:

  1. 拿到文档后补 EdayunConstants 的路径常量
  2. 按接口逐个补 dto/ + adapter/XxxMapper + enums/(阶段 2 的 6 步)
  3. 写只读探针 → 真机验证 → 全链路探针
  4. 补回调实现
  5. 更新本文档

已知的坑(从运去哪/信仓带来的经验)

坑 应对
文档参数名可能带 query. 前缀而实际不带 真机验证时必须核对
有些接口没有 code 只有 status 信封校验要兼容两种
文档示例常是自动生成的占位符 不看示例值,看真机返回
单位可能未标注 真机验证量级(kg vs lb 差 2.2 倍)
状态码可能依赖上下文(单据类型) (type, status) 一起带出去