|
|
|
|
# 易达云(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`) |
|
|
|
|
|
| 其它业务接口 | ⬜ 等文档 |
|
|
|
|
|
| 回调 | ⬜ 等文档 |
|
|
|
|
|
| 真机验证 | ⬜ 等测试环境 |
|
|
|
|
|
|
|
|
|
|
**骨架阶段的行为**:任何业务调用都会抛
|
|
|
|
|
`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 环境)**:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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` 上加字段。
|
|
|
|
|
|
|
|
|
|
### 探针
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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` 就判成已发货——**精确匹配,不做子串**。
|
|
|
|
|
|
|
|
|
|
### 面单:多包裹按位置对应
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
"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`——文档还没给。
|
|
|
|
|
|
|
|
|
|
## 待确认(问易达云)
|
|
|
|
|
|
|
|
|
|
| # | 要确认 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 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](../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)` 一起带出去 |
|