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