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.

8.8 KiB

易达云(EDAYUN)接入

当前状态:骨架

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

骨架阶段的行为:任何业务调用都会抛 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)标准模型没有对应字段,暂不下发。

本期未接的出库能力

get / query / cancel / packages 都显式抛 WarehouseUnsupportedCapabilityException——文档还没给这几个接口。

待确认(问易达云)

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