55 KiB
易达云(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。
接下来怎么推进
- 拿到文档后补
EdayunConstants的路径常量 - 按接口逐个补
dto/+adapter/XxxMapper+enums/(阶段 2 的 6 步) - 写只读探针 → 真机验证 → 全链路探针
- 补回调实现
- 更新本文档
已知的坑(从运去哪/信仓带来的经验)
| 坑 | 应对 |
|---|---|
文档参数名可能带 query. 前缀而实际不带 |
真机验证时必须核对 |
有些接口没有 code 只有 status |
信封校验要兼容两种 |
| 文档示例常是自动生成的占位符 | 不看示例值,看真机返回 |
| 单位可能未标注 | 真机验证量级(kg vs lb 差 2.2 倍) |
| 状态码可能依赖上下文(单据类型) | (type, status) 一起带出去 |