|
|
|
|
# 易达云(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 环境)**:
|
|
|
|
|
|
|
|
|
|
```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`——文档还没给。
|
|
|
|
|
|
|
|
|
|
## 交易明细(费用)
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
POST /webApi/accountFlow/list → List<BillingDocument>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 三条与其它仓不同的口径
|
|
|
|
|
|
|
|
|
|
**① 同一单号的同一计费项有多条数据——不去重**
|
|
|
|
|
|
|
|
|
|
文档原文:「同一个单号(ORD-发货单 / REV-收货单)的某个计费项有多条数据」。
|
|
|
|
|
|
|
|
|
|
所以每条流水都映射成一条 `BillingDocument`,靠 **`serialNumber()`**(账户流水号)区分。
|
|
|
|
|
按单号去重会丢账。
|
|
|
|
|
|
|
|
|
|
**② 金额是 string 且可为负**
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
"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,可为负) | `应收 / 折扣 / 实付` 三个 |
|
|
|
|
|
| 粒度 | 一条流水一个计费项 | 一个订单展开成多条计费项 |
|
|
|
|
|
| 附带 | 账户余额、汇率 | 计费重、计费分区、是否偏远 |
|
|
|
|
|
|
|
|
|
|
### 金额取**实付**
|
|
|
|
|
|
|
|
|
|
每个计费项有三个金额:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
"amountReceivable": 20.187, // 应收
|
|
|
|
|
"discountPrice": 5.745, // 折扣
|
|
|
|
|
"realPayPrice": 14.442 // 实付
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
落库金额取 **`realPayPrice`**——对账要以实际发生为准,应收只是报价。
|
|
|
|
|
|
|
|
|
|
### 一个订单展开成多条
|
|
|
|
|
|
|
|
|
|
响应结构是 `rows[] → chargeDetails[] → feeDetails[]`,按**计费项**展开:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
一个订单 → 「尾程-运费」「尾程-出库处理费」… 各一条 BillingDocument
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
多条记录的 `documentNo` 相同,靠 `feeName` 区分。
|
|
|
|
|
|
|
|
|
|
若某层只有 `chargeDetails` 汇总、没有 `feeDetails`,按汇总记一条「订单费用」。
|
|
|
|
|
|
|
|
|
|
### 单号类型要配合
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
"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`,币种按原值
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
"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` 再校正。
|
|
|
|
|
|
|
|
|
|
### 探针
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{"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` 查
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{"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);超了显式失败而不是截断。
|
|
|
|
|
|
|
|
|
|
### 探针
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 只读,不加 write 也会真查
|
|
|
|
|
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
|
|
|
|
|
-Dedayun.probe.inboundQuery=true -Dtest=EdayunInboundQueryProbeTest test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 探针
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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。
|
|
|
|
|
|
|
|
|
|
### 探针
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# 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](../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)` 一起带出去 |
|