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.

33 KiB

易达云(EDAYUN)接入

当前状态:骨架

项 状态
模块 ✅ warehouse-sdk-edayun 已建、已注册
适配器 / 工厂 ✅ 类型就绪,能力位为空
获取 token ✅ 已对接(POST /oauth/token)
创建产品 ✅ 已对接(POST /webApi/skuInfo/v1/createProduct)
创建出库单 ✅ 已对接(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)
其它业务接口 ⬜ 等文档
回调 ⬜ 等文档
真机验证 ⬜ 等测试环境

骨架阶段的行为:任何业务调用都会抛 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/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

保价(is_insurance)标准模型没有对应字段,暂不下发。

查询出库单 / 面单

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 按文档当总行数用,缺失时按满页判断

未映射的字段

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]

待确认(问易达云)

# 要确认
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) 一起带出去