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.

15 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)
其它业务接口 ⬜ 等文档
回调 ⬜ 等文档
真机验证 ⬜ 等测试环境

骨架阶段的行为:任何业务调用都会抛 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()(变动后余额)。

待确认(问易达云)

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