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.
951 lines
34 KiB
951 lines
34 KiB
|
3 days ago
|
# 三方仓 SDK 操作手册
|
||
|
|
|
||
|
|
> 快速索引:从零开始看 **一**;查某个入参/出参看 **二**;要调某个能力看 **三**;
|
||
|
|
> 出问题先看 **五、常见坑速查**。
|
||
|
|
|
||
|
|
> 面向宿主(OMS)开发。所有示例基于 `warehouse-sdk-core` + 各仓适配器。
|
||
|
|
> 版本:1.0.0-SNAPSHOT · JDK 1.8
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 目录
|
||
|
|
|
||
|
|
- [一、SDK 怎么创建](#一sdk-怎么创建)
|
||
|
|
- [1.1 依赖](#11-依赖)
|
||
|
|
- [1.2 宿主必须先实现的 SPI](#12-宿主必须先实现的-spi)
|
||
|
|
- [1.3 构建门面](#13-构建门面)
|
||
|
|
- [1.4 连接信息(端点 + 凭据)](#14-连接信息端点--凭据)
|
||
|
|
- [1.5 取某个仓的操作视图](#15-取某个仓的操作视图)
|
||
|
|
- [二、入参怎么传、出参怎么取](#二入参怎么传出参怎么取)
|
||
|
|
- [2.1 通用约定(单位、时间、SKU、金额)](#21-通用约定单位时间sku金额)
|
||
|
|
- [2.2 分页入参 / 出参 `Page<T>`](#22-分页入参--出参-paget)
|
||
|
|
- [2.3 出库入参 `OutboundCommand`](#23-出库入参-outboundcommand)
|
||
|
|
- [2.4 库存入参 `InventoryQuery`](#24-库存入参-inventoryquery)
|
||
|
|
- [2.5 入库入参 `InboundCommand`](#25-入库入参-inboundcommand)
|
||
|
|
- [2.6 退货入参 `ReturnCommand` / `ReturnQuery`](#26-退货入参-returncommand--returnquery)
|
||
|
|
- [2.7 费用入参 `FeeQuery` / `FeeEstimateQuery`](#27-费用入参-feequery--feeestimatequery)
|
||
|
|
- [2.8 商品入参 `WarehouseProduct` / `ProductQuery`](#28-商品入参-warehouseproduct--productquery)
|
||
|
|
- [2.9 出参速查表](#29-出参速查表)
|
||
|
|
- [三、各能力怎么调用](#三各能力怎么调用)
|
||
|
|
- [3.0 视图结构](#30-视图结构)
|
||
|
|
- [3.1 能力矩阵](#31-能力矩阵)
|
||
|
|
- [3.2 商品](#32-商品)
|
||
|
|
- [3.3 出库](#33-出库)
|
||
|
|
- [3.4 库存](#34-库存)
|
||
|
|
- [3.5 入库](#35-入库)
|
||
|
|
- [3.6 退货](#36-退货)
|
||
|
|
- [3.7 费用](#37-费用)
|
||
|
|
- [3.8 基础资料(仓库 / 承运商 / 物流产品)](#38-基础资料仓库--承运商--物流产品)
|
||
|
|
- [3.9 单据与打印(BOL / 轨迹 / 箱唛)](#39-单据与打印bol--轨迹--箱唛)
|
||
|
|
- [3.10 调拨 / 销毁 / 物流异动](#310-调拨--销毁--物流异动)
|
||
|
|
- [四、异常与重试](#四异常与重试)
|
||
|
|
- [五、常见坑速查](#五常见坑速查)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
# 一、SDK 怎么创建
|
||
|
|
|
||
|
|
## 1.1 依赖
|
||
|
|
|
||
|
|
```xml
|
||
|
|
<!-- 门面 + 统一模型 -->
|
||
|
|
<dependency>
|
||
|
|
<groupId>ecommerce</groupId>
|
||
|
|
<artifactId>warehouse-sdk-core</artifactId>
|
||
|
|
<version>1.0.0-SNAPSHOT</version>
|
||
|
|
</dependency>
|
||
|
|
|
||
|
|
<!-- 按需引入适配器,每个仓一个 artifact -->
|
||
|
|
<dependency>
|
||
|
|
<groupId>ecommerce</groupId>
|
||
|
|
<artifactId>warehouse-sdk-edayun</artifactId>
|
||
|
|
<version>1.0.0-SNAPSHOT</version>
|
||
|
|
</dependency>
|
||
|
|
<dependency>
|
||
|
|
<groupId>ecommerce</groupId>
|
||
|
|
<artifactId>warehouse-sdk-yqn</artifactId>
|
||
|
|
<version>1.0.0-SNAPSHOT</version>
|
||
|
|
</dependency>
|
||
|
|
```
|
||
|
|
|
||
|
|
要求 **JDK 1.8**。SDK 不引入日志实现,宿主自己提供 `slf4j` 绑定。
|
||
|
|
|
||
|
|
## 1.2 宿主必须先实现的 SPI
|
||
|
|
|
||
|
|
SDK 是纯库:**不读数据库、不读配置、不启定时器、不监听端口**。以下由宿主提供。
|
||
|
|
|
||
|
|
### `WarehouseRepository`(必需)
|
||
|
|
|
||
|
|
```java
|
||
|
|
public interface WarehouseRepository {
|
||
|
|
/** 按 OMS 仓编码取全部接入账户。 */
|
||
|
|
List<WarehouseAccount> findByWarehouseCode(String warehouseCode);
|
||
|
|
|
||
|
|
/** 按仓编码 + provider 取单个账户。 */
|
||
|
|
Optional<WarehouseAccount> find(String warehouseCode, String provider);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### `WarehouseAccount`(仓主数据)
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseAccount.builder()
|
||
|
|
.warehouseCode("EDY-USLA") // OMS 侧仓编码
|
||
|
|
.provider("EDAYUN") // 决定用哪个适配器
|
||
|
|
.providerWarehouseId("2") // 仓方仓 id(数字)
|
||
|
|
.credentialRef("kms://edayun") // 只是标识,SDK 不会去取密钥
|
||
|
|
.timeZone("America/Los_Angeles")
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
| 字段 | 作用 | 易达云 | 运去哪 | 信仓 | 恒健 |
|
||
|
|
|---|---|---|---|---|---|
|
||
|
|
| `warehouseCode` | OMS 仓编码,所有调用的入参 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `provider` | 选适配器 | `EDAYUN` | `YQN` | `XINCANG` | `HENGJIAN` |
|
||
|
|
| `providerWarehouseId` | 仓方仓 id/编码 | 数字 id(`"2"`) | 仓编码(`"RF_NY_US"`) | 仓编码 | 仓编码 |
|
||
|
|
| `timeZone` | 时间窗解释 | 用 | 用 | 用 | 用 |
|
||
|
|
|
||
|
|
### `IdempotencyStore`(写操作必需)
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseSdk.builder()
|
||
|
|
.idempotencyStore(myRedisOrDbImpl) // 不注入则写操作直接抛异常
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
没注入时调 `outbound().create(...)`、`returns().create(...)` 等会抛
|
||
|
|
`IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations")`。
|
||
|
|
|
||
|
|
### `CallObserver`(可选,强烈建议)
|
||
|
|
|
||
|
|
```java
|
||
|
|
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
|
||
|
|
```
|
||
|
|
|
||
|
|
每次门面调用结束回调一次,成功打 INFO、失败打 WARN。不注入时是空实现。
|
||
|
|
|
||
|
|
### `TokenStore` / `LockProvider`(可选)
|
||
|
|
|
||
|
|
易达云、信仓需要换 token,注入后按 `appKey + clientId` 缓存;不注入则每次调用都重新登录。
|
||
|
|
|
||
|
|
## 1.3 构建门面
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseSdk sdk = WarehouseSdk.builder()
|
||
|
|
.warehouseRepository(repo) // 必需
|
||
|
|
.idempotencyStore(idempotencyStore) // 写操作必需
|
||
|
|
.clock(Clock.systemUTC()) // 可选,默认 UTC
|
||
|
|
.idempotencyOwner("oms-node-1") // 多实例部署时区分
|
||
|
|
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
|
||
|
|
.requestIdSupplier(() -> UUID.randomUUID().toString())
|
||
|
|
.register(new EdayunAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
|
||
|
|
.register(new YqnAdapterFactory(Clock.systemUTC()))
|
||
|
|
.register(new XincangAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
|
||
|
|
.register(new HengjianAdapterFactory())
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
**`build()` 立刻失败的情况**
|
||
|
|
|
||
|
|
| 缺失 | 异常 |
|
||
|
|
|---|---|
|
||
|
|
| `warehouseRepository` | `IllegalStateException: requires a warehouseRepository` |
|
||
|
|
| 一个适配器都没注册 | `IllegalStateException: requires at least one adapter or adapter factory` |
|
||
|
|
| 同一 provider 注册两次 | `IllegalStateException: duplicate warehouse adapter for ...` |
|
||
|
|
|
||
|
|
> **门面请做单例。** 适配器里缓存了限流器与 token,每次 `new` 会让缓存失效。
|
||
|
|
|
||
|
|
**各仓工厂的构造参数**
|
||
|
|
|
||
|
|
| 工厂 | 构造参数 |
|
||
|
|
|---|---|
|
||
|
|
| `EdayunAdapterFactory` | `(TokenStore, LockProvider, Clock)` |
|
||
|
|
| `YqnAdapterFactory` | `(Clock)` |
|
||
|
|
| `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` |
|
||
|
|
| `HengjianAdapterFactory` | 无参 |
|
||
|
|
|
||
|
|
## 1.4 连接信息(端点 + 凭据)
|
||
|
|
|
||
|
|
**SDK 不保存端点、不读环境变量。** 每次调用都要由宿主传入。
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseConnection conn = WarehouseConnection.of(
|
||
|
|
"https://test.omniselling.com.cn/saas-service/openapi/microService",
|
||
|
|
ChannelSecret.builder()
|
||
|
|
.appKey("...")
|
||
|
|
.appSecret("...")
|
||
|
|
.clientId("...") // 易达云换 token 用
|
||
|
|
.clientSecret("...")
|
||
|
|
.build());
|
||
|
|
```
|
||
|
|
|
||
|
|
**各仓需要的凭据字段**
|
||
|
|
|
||
|
|
| 仓 | 需要的字段 | 说明 |
|
||
|
|
|---|---|---|
|
||
|
|
| 易达云 | `appKey`、`appSecret`、`clientId`、`clientSecret` | `clientId/Secret` 换 token;`appKey/appSecret` 算签名 |
|
||
|
|
| 运去哪 | `appSecret` | 组织级 token 固定放请求头,复用 `appSecret` 承载 |
|
||
|
|
| 信仓 | `appKey`、`appSecret` | 换 token |
|
||
|
|
| 恒健 | `appSecret` | 签名 |
|
||
|
|
|
||
|
|
**安全要求**
|
||
|
|
|
||
|
|
- `ChannelSecret.toString()` 不打印密钥,日志里只用 `fingerprint()`
|
||
|
|
- 不要把 `ChannelSecret` 序列化进日志或异常
|
||
|
|
- 生产从 KMS / Vault 取,不要硬编码
|
||
|
|
|
||
|
|
## 1.5 取某个仓的操作视图
|
||
|
|
|
||
|
|
```java
|
||
|
|
// 每次都传连接信息(端点与凭据随调用走,SDK 不缓存)
|
||
|
|
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
|
||
|
|
```
|
||
|
|
|
||
|
|
`warehouses()` 做的事:
|
||
|
|
|
||
|
|
1. 按 `warehouseCode` 查 `WarehouseRepository` → 拿 `WarehouseAccount`
|
||
|
|
2. 按 `provider` 解析出适配器
|
||
|
|
3. 组装 `WarehouseContext`(仓编码、provider、仓方 id、连接、requestId、clock)
|
||
|
|
|
||
|
|
拿不到账户时抛 `IllegalStateException`。
|
||
|
|
|
||
|
|
**查能力位(不触发真实请求)**
|
||
|
|
|
||
|
|
```java
|
||
|
|
EnumSetView caps = sdk.capabilities("EDY-USLA");
|
||
|
|
boolean canReturn = caps.supported().contains(WarehouseCapability.RETURN);
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
# 二、入参怎么传、出参怎么取
|
||
|
|
|
||
|
|
## 2.1 通用约定(单位、时间、SKU、金额)
|
||
|
|
|
||
|
|
### 单位
|
||
|
|
|
||
|
|
| 项 | 统一模型 | 说明 |
|
||
|
|
|---|---|---|
|
||
|
|
| 尺寸 | **cm** | 字段名带 `Cm` |
|
||
|
|
| 重量 | **g** | 字段名带 `Grams` |
|
||
|
|
| 时间 | **`Instant`(UTC)** | SDK 内部一律 UTC,展示时区由宿主决定 |
|
||
|
|
| 金额 | **`Money`**(金额 + 币种) | 不允许裸数字,避免丢币种 |
|
||
|
|
|
||
|
|
适配器负责换算成仓方单位(易达云要 kg,会自己从 g 转)。
|
||
|
|
|
||
|
|
### SKU 口径(最容易错的地方)
|
||
|
|
|
||
|
|
**所有环节都用「建档时下发给仓方的那串」。**
|
||
|
|
|
||
|
|
```java
|
||
|
|
// 建档时
|
||
|
|
String sku = product.providerSku(); // 宿主给了就用它
|
||
|
|
sku = sku != null && !sku.isEmpty() ? sku : product.omsSku(); // 没给就用 OMS SKU
|
||
|
|
```
|
||
|
|
|
||
|
|
| 场景 | 仓方库里存的 | 之后要传 |
|
||
|
|
|---|---|---|
|
||
|
|
| 给了 `providerSku`(如 `AP0000X9US0010601`) | 它 | 它(**≠ OMS SKU**) |
|
||
|
|
| 没给(如 `ybtest`) | `omsSku` | `omsSku`(两者同名) |
|
||
|
|
|
||
|
|
涉及的字段名:
|
||
|
|
|
||
|
|
| 统一模型 | 易达云 | 运去哪 |
|
||
|
|
|---|---|---|
|
||
|
|
| `WarehouseProduct.providerSku`(建档) | `skuCode` | `sku` |
|
||
|
|
| `ProductQuery.providerSkus`(查商品) | `skuCode`(逗号拼接,≤50) | `skuList`(JSON 数组,≤100) |
|
||
|
|
| `OutboundLine.providerSku`(下单) | `productSku` | `sku` |
|
||
|
|
| `InventoryQuery.providerSkus`(查库存) | `skuCodeList` | `sku` |
|
||
|
|
|
||
|
|
**SDK 不做 OMS → 仓侧 SKU 的转换**:映射表在宿主手里。传错不报错,只会查不到。
|
||
|
|
|
||
|
|
### 金额
|
||
|
|
|
||
|
|
```java
|
||
|
|
Money.of("19.99", "USD") // 字符串构造,保留精度
|
||
|
|
Money.zero("USD")
|
||
|
|
money.add(other) / subtract / multiply / round()
|
||
|
|
```
|
||
|
|
|
||
|
|
## 2.2 分页入参 / 出参 `Page<T>`
|
||
|
|
|
||
|
|
**入参**(每个 Query 都有)
|
||
|
|
|
||
|
|
```java
|
||
|
|
.pageSize(100) // 单页条数;各仓有上限,适配器会截断
|
||
|
|
.cursor(null) // 第一页传 null
|
||
|
|
```
|
||
|
|
|
||
|
|
**出参**
|
||
|
|
|
||
|
|
```java
|
||
|
|
Page<ProductInfo> page = ...;
|
||
|
|
|
||
|
|
page.items(); // List<T>,不可变
|
||
|
|
page.size();
|
||
|
|
page.hasMore(); // 由 nextCursor 推导,不要从 items 数量猜
|
||
|
|
page.nextCursor(); // null = 没有下一页
|
||
|
|
```
|
||
|
|
|
||
|
|
**翻页模板**
|
||
|
|
|
||
|
|
```java
|
||
|
|
String cursor = null;
|
||
|
|
do {
|
||
|
|
Page<X> page = wh.xxx(Query.builder().cursor(cursor).pageSize(100).build());
|
||
|
|
for (X item : page.items()) { /* 处理 */ }
|
||
|
|
cursor = page.nextCursor();
|
||
|
|
} while (cursor != null);
|
||
|
|
```
|
||
|
|
|
||
|
|
> 各仓页码起点不同(易达云从 1、运去哪从 0),**游标已经屏蔽了差异**。
|
||
|
|
> 不要自己算 ±1,原样把 `nextCursor()` 传回去即可。
|
||
|
|
|
||
|
|
## 2.3 出库入参 `OutboundCommand`
|
||
|
|
|
||
|
|
### 必填
|
||
|
|
|
||
|
|
| 字段 | 类型 | 说明 |
|
||
|
|
|---|---|---|
|
||
|
|
| `outboundRequestNo` | String | 我们自己的出库单号 |
|
||
|
|
| `salesPlatform` | Platform | 销售平台,映射成仓方 `channelName` |
|
||
|
|
| `shipTo` | ShipTo | 收件地址 |
|
||
|
|
| `line(...)` | OutboundLine | 至少一条商品行 |
|
||
|
|
|
||
|
|
### 选填
|
||
|
|
|
||
|
|
| 字段 | 说明 |
|
||
|
|
|---|---|
|
||
|
|
| `orderRef` | **平台单号,仓侧幂等键**(强烈建议给) |
|
||
|
|
| `warehouseId` | 指定发货仓;空则用账户配置 |
|
||
|
|
| `labelMode` | `WAREHOUSE_LABEL`(仓出)/ `PLATFORM_LABEL`(我们传面单) |
|
||
|
|
| `carrier` / `carrierCode` | 承运商 |
|
||
|
|
| `trackingNumber` | 跟踪号(平台面单时用) |
|
||
|
|
| `labelContentBase64` | 面单内容;易达云要 **URL** 不是 base64 |
|
||
|
|
| `currency` | 币种 |
|
||
|
|
| `declaredTotal` | 申报总额(Money) |
|
||
|
|
| `latestShipDate` | 最晚发货时间 |
|
||
|
|
| `remark` | 备注 |
|
||
|
|
| `signatureRequired` | 是否需要签收 |
|
||
|
|
| `sfp` | 是否 SFP 订单 |
|
||
|
|
| `packages` | 包裹拆分(多箱时) |
|
||
|
|
|
||
|
|
### `OutboundLine`
|
||
|
|
|
||
|
|
| 字段 | 说明 |
|
||
|
|
|---|---|
|
||
|
|
| `lineNo` | 行号 |
|
||
|
|
| `omsSku` / `providerSku` | **providerSku 优先**(见 2.1) |
|
||
|
|
| `quantity` | 数量 |
|
||
|
|
| `declareName` / `declareNameEn` | 申报中/英文名 |
|
||
|
|
| `declareValue` | 申报单价(Money,**不是总额**) |
|
||
|
|
| `hsCode` / `countryOfOrigin` | 海关 |
|
||
|
|
| `insuredAmount` | 保价金额(易达云:任意行有值即整单保价) |
|
||
|
|
| `platformOrderItemId` | 平台子单号(亚马逊 `platformItemId`、eBay `ebayItemId`) |
|
||
|
|
|
||
|
|
### `ShipTo`
|
||
|
|
|
||
|
|
```java
|
||
|
|
ShipTo.builder()
|
||
|
|
.name("张三")
|
||
|
|
.phone("+1-555-0100")
|
||
|
|
.email("a@b.com")
|
||
|
|
.countryCode("US") // ISO 3166-1 alpha-2
|
||
|
|
.stateOrProvince("CA") // 二字码;易达云要全称,见坑表
|
||
|
|
.city("Escondido")
|
||
|
|
.addressLine1("1308 E Washington Ave")
|
||
|
|
.addressLine2("Unit B")
|
||
|
|
.postalCode("92027")
|
||
|
|
.build()
|
||
|
|
```
|
||
|
|
|
||
|
|
### 出参 `OutboundReceipt`
|
||
|
|
|
||
|
|
```java
|
||
|
|
receipt.outboundRequestNo(); // 回显我们传入的单号
|
||
|
|
receipt.providerOrderId(); // 仓侧单号(幂等重试时靠它定位)
|
||
|
|
receipt.rawStatus(); // 仓方原文
|
||
|
|
```
|
||
|
|
|
||
|
|
## 2.4 库存入参 `InventoryQuery`
|
||
|
|
|
||
|
|
```java
|
||
|
|
InventoryQuery.builder()
|
||
|
|
.sku("provider-sku") // 单个;.skus(List) 多个
|
||
|
|
.warehouseCode("EDY-USLA") // 可选,空则用账户仓
|
||
|
|
.inventoryType(0) // 0 可售 / 1 不可售;null 不限
|
||
|
|
.includeZeroStock(true) // 是否要零库存;null 由仓方默认
|
||
|
|
.updatedAfter(instant) // 增量起点;**多数仓不支持**
|
||
|
|
.pageSize(100)
|
||
|
|
.cursor(null)
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
出参 `Page<InventorySnapshot>`
|
||
|
|
|
||
|
|
```java
|
||
|
|
s.warehouseCode(); s.providerSku(); s.omsSku();
|
||
|
|
s.available(); // 可用
|
||
|
|
s.onHand(); // 总库存
|
||
|
|
s.inTransit(); // 在途
|
||
|
|
s.reserved(); // 冻结
|
||
|
|
s.pendingOutbound(); // 待出库;**仓方未给为 -1**
|
||
|
|
s.alertQuantity(); // 安全库存;**仓方未给为 -1**
|
||
|
|
s.asOfUtc(); // 快照时刻
|
||
|
|
s.inventoryType(); // 0 可售 / 1 不可售
|
||
|
|
s.sellable();
|
||
|
|
```
|
||
|
|
|
||
|
|
> **`-1` 是「仓方没给」,不是 0。** 易达云的 `safeStock` 大量为 null,映射成 -1。
|
||
|
|
|
||
|
|
**同步策略**
|
||
|
|
|
||
|
|
```java
|
||
|
|
wh.inventorySyncStrategy(); // TIME_WINDOW / FULL_PULL_DIFF
|
||
|
|
```
|
||
|
|
|
||
|
|
`FULL_PULL_DIFF` 表示**没有时间维度**,`updatedAfter` 不生效,必须全量拉再 diff。
|
||
|
|
|
||
|
|
## 2.5 入库入参 `InboundCommand`
|
||
|
|
|
||
|
|
```java
|
||
|
|
InboundCommand.builder()
|
||
|
|
.inboundRequestNo("IB-001") // 必填,幂等键
|
||
|
|
.warehouseId("2")
|
||
|
|
.predictionShipDate(LocalDate) // 预计发运
|
||
|
|
.estimateArriveDate(LocalDate) // 预计到仓
|
||
|
|
.line(InboundLine.builder().omsSku("SKU").quantity(10).build())
|
||
|
|
.carton(InboundCarton.builder()
|
||
|
|
.providerSku("SKU").quantity(10).cartonNo("BOX-1")
|
||
|
|
.lengthCm(50).widthCm(40).heightCm(30).weightGrams(10000)
|
||
|
|
.build())
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
出参 `InboundReceipt { inboundRequestNo(); providerInboundId(); }`
|
||
|
|
|
||
|
|
**查询**:`inbound().get(ref)` / `query(cursor)` / `queryInbounds(InboundQuery)`
|
||
|
|
|
||
|
|
## 2.6 退货入参 `ReturnCommand` / `ReturnQuery`
|
||
|
|
|
||
|
|
### `ReturnCommand`(创建)
|
||
|
|
|
||
|
|
```java
|
||
|
|
ReturnCommand.builder()
|
||
|
|
.returnRequestNo("RT-001") // 必填,幂等键
|
||
|
|
.saleOrderNo("SO-1") // 必填,关联原单
|
||
|
|
.returnTrackingNo("1Z999") // 必填,退货运单号
|
||
|
|
.carrierCode("FedEx") // 必填
|
||
|
|
.warehouseId("2")
|
||
|
|
.line("SKU", 1, ReturnDealMethod.DESTROY) // 必填,至少一行
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
`ReturnDealMethod`:`CUSTOMER_PICKUP` / `PHOTO_CONFIRM` / `DESTROY` / `WAREHOUSE_CONFIRM`
|
||
|
|
|
||
|
|
> **易达云只支持「自行退回」**(它要求退货运单号),且**拒绝** `lineName` /
|
||
|
|
> `estimatedReceiveDate` / `returnReason` —— 传了直接报错,不静默丢弃。
|
||
|
|
|
||
|
|
### `ReturnQuery`(查询)
|
||
|
|
|
||
|
|
```java
|
||
|
|
ReturnQuery.builder()
|
||
|
|
.createdAfter(...).createdBefore(...)
|
||
|
|
.orderNo("RMA1").orderNoType(ReturnQueryNoType.PROVIDER_RETURN_NO)
|
||
|
|
.trackingNo("1Z999")
|
||
|
|
.status(ReturnStatus.RETURNING) // 与 rawStatus 互斥
|
||
|
|
.rawStatus("20") // 仓方原值,需要精确筛时用
|
||
|
|
.providerSku("SKU")
|
||
|
|
.pageSize(100).cursor(null)
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
`ReturnStatus`:`DRAFT` / `PENDING_REVIEW` / `REJECTED` / `RETURNING` /
|
||
|
|
`PENDING_RECEIPT` / `COMPLETED` / `CLOSED` / `UNKNOWN`
|
||
|
|
|
||
|
|
### 出参 `WarehouseReturn`
|
||
|
|
|
||
|
|
```java
|
||
|
|
r.returnRequestNo(); // 我们传入的
|
||
|
|
r.providerReturnId(); // 仓侧 RMA 号
|
||
|
|
r.status(); // 统一状态
|
||
|
|
r.rawStatus(); // 仓方原文(中文名或码)
|
||
|
|
r.lines(); // 明细
|
||
|
|
r.createdAt();
|
||
|
|
r.sourceProvider();
|
||
|
|
```
|
||
|
|
|
||
|
|
`ReturnLine`:`providerSku` / `quantity` / `newSku` / `inventoryType` /
|
||
|
|
`processedQuantity` / `suggestedDisposition` / `pictureUrls` / `remark`
|
||
|
|
|
||
|
|
## 2.7 费用入参 `FeeQuery` / `FeeEstimateQuery`
|
||
|
|
|
||
|
|
### `FeeQuery`(已发生的账单)
|
||
|
|
|
||
|
|
```java
|
||
|
|
FeeQuery.builder()
|
||
|
|
.settledAfter(instant).settledBefore(instant) // 计费时间窗
|
||
|
|
.saleOrderNo("SO-1") // 或按单号
|
||
|
|
.externalOrderNo("60044642").noType(FeeQueryNoType.PLATFORM_ORDER_NO)
|
||
|
|
.costType(WarehouseFeeType.STORAGE) // 指定查哪一类
|
||
|
|
.providerSku("SKU")
|
||
|
|
.pageCursor(null).pageSize(100)
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
`WarehouseFeeType`:`OPERATION` / `STORAGE` / `VALUE_ADDED` / `LAST_MILE`
|
||
|
|
|
||
|
|
三个方法对应三种口径:
|
||
|
|
|
||
|
|
| 方法 | 口径 |
|
||
|
|
|---|---|
|
||
|
|
| `fees().settlements(query)` | 账户流水(充值 / 扣费 / 退费 + 余额) |
|
||
|
|
| `fees().orderCosts(query)` | 按订单拆的费用(应收 / 折扣 / 实付 + 计费重) |
|
||
|
|
| `fees().storageRents(query)` | 仓租(按 SKU + 计费日逐条) |
|
||
|
|
|
||
|
|
出参 `List<BillingDocument>`
|
||
|
|
|
||
|
|
```java
|
||
|
|
d.warehouseCode(); d.sourceProvider();
|
||
|
|
d.documentNo(); // 单据号
|
||
|
|
d.feeName(); // 计费项名
|
||
|
|
d.feeType();
|
||
|
|
d.estimated(); // true 预估 / false 实际
|
||
|
|
d.settledAt();
|
||
|
|
d.amount(); // Money
|
||
|
|
d.serialNumber(); // 流水号/去重键
|
||
|
|
d.accountBalance();
|
||
|
|
d.providerSku(); d.saleOrderNo();
|
||
|
|
```
|
||
|
|
|
||
|
|
### `FeeEstimateQuery`(发货前报价)
|
||
|
|
|
||
|
|
```java
|
||
|
|
FeeEstimateQuery.builder()
|
||
|
|
.lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
|
||
|
|
.receiveCountry("US").receivePostal("91761").receiveCity("...")
|
||
|
|
.warehouseCode("EDY-USLA")
|
||
|
|
.logisticsServiceCode("80") // 指定渠道;空则返回全部
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
出参 `List<FeeEstimateResult>`
|
||
|
|
|
||
|
|
```java
|
||
|
|
r.shipOrgWarehouseCode();
|
||
|
|
r.carriers(); // List<CarrierQuote>
|
||
|
|
q.carrier(); q.logisticsServiceCode();
|
||
|
|
q.totalRate(); // Money
|
||
|
|
q.costItems(); // 细分:costName + estimatedCost
|
||
|
|
```
|
||
|
|
|
||
|
|
## 2.8 商品入参 `WarehouseProduct` / `ProductQuery`
|
||
|
|
|
||
|
|
### `WarehouseProduct`(建档)
|
||
|
|
|
||
|
|
**必填**:`omsSku`、`name`、`lengthCm`、`widthCm`、`heightCm`、`weightGrams`
|
||
|
|
|
||
|
|
**强烈建议**:`providerSku`、`barcode`、`nameEn`、`declareValue` + `countryOfOrigin` + `hsCode`
|
||
|
|
|
||
|
|
**分仓必填差异**
|
||
|
|
|
||
|
|
| 字段 | 易达云 | 运去哪 | 信仓 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `nameEn` | 可选 | **必填** | 不支持 |
|
||
|
|
| `packingType` | 不用 | **必填**(0 原包装 / 1 重新打包) | 不支持 |
|
||
|
|
| `hsCode` 三项 | 用 | **必填整组** | 只用 `declaredValue` |
|
||
|
|
| `productCategory` | 不用 | 不用 | 用 |
|
||
|
|
| `imageUrls` | 不用 | 不用 | 用(尺寸复核图) |
|
||
|
|
|
||
|
|
### `ProductQuery`(查询)
|
||
|
|
|
||
|
|
```java
|
||
|
|
ProductQuery.builder()
|
||
|
|
.providerSku("SKU") // 仓侧 SKU
|
||
|
|
.barcode("N949...") // 运去哪不支持,传了本地报错
|
||
|
|
.createdAfter(...).createdBefore(...) // 运去哪不支持
|
||
|
|
.pageSize(100).cursor(null)
|
||
|
|
.build();
|
||
|
|
```
|
||
|
|
|
||
|
|
**支持的过滤维度**
|
||
|
|
|
||
|
|
| | 易达云 | 运去哪 |
|
||
|
|
|---|---|---|
|
||
|
|
| SKU 数量上限 | 50 | 100 |
|
||
|
|
| 条码 | ✅ | ❌ |
|
||
|
|
| 创建时间窗 | ✅ | ❌ |
|
||
|
|
| 不会默认时间窗 | 不带则**只查最近一个月** | 全量 |
|
||
|
|
|
||
|
|
## 2.9 出参速查表
|
||
|
|
|
||
|
|
| 出参类型 | 关键 getter |
|
||
|
|
|---|---|
|
||
|
|
| `OutboundReceipt` | `outboundRequestNo` `providerOrderId` `rawStatus` |
|
||
|
|
| `OutboundOrder` | `status` `rawStatus` `trackingNumber` `lines` `shipTo` `exceptionCode` `attachments` |
|
||
|
|
| `PackageResult` | `trackingNumber` `labelRef` |
|
||
|
|
| `CancelResult` | `cancelled` `eligibility` `rawStatus` |
|
||
|
|
| `InventorySnapshot` | 见 2.4 |
|
||
|
|
| `InboundReceipt` | `inboundRequestNo` `providerInboundId` |
|
||
|
|
| `InboundOrder` | `status` `lines` `boxes` `batches` |
|
||
|
|
| `WarehouseReturn` | 见 2.6 |
|
||
|
|
| `BillingDocument` | 见 2.7 |
|
||
|
|
| `FeeEstimateResult` | 见 2.7 |
|
||
|
|
| `ProductInfo` | `providerSku` `barcode` `lengthCm` `weightGrams` `packedQuantity` `productType` `createdAt` |
|
||
|
|
| `WarehouseFacility` | `warehouseCode` `providerWarehouseId` `name` `country` `city` `address1` |
|
||
|
|
| `WarehouseCarrier` | `carrierId` `nameEn` `nameCn` `logists()` |
|
||
|
|
| `LogisticsProduct` | `logisticsProductCode` `logisticsProductName` `crossCountry` |
|
||
|
|
| `BolDocument` | `bolCode` `fileUrl` `podFileUrl` `rawStatus` `scheduledPickupQuantity` |
|
||
|
|
| `TrackingInfo` | `status` `firstOnlineAt` `deliveredAt` `signedBy` `events()` |
|
||
|
|
| `TrackEvent` | `status` `description` `occurredAt` |
|
||
|
|
| `WarehouseLabel` | `labelId` `format` `url` `contentBase64` |
|
||
|
|
| `LabelPrintTask` | `taskNo` `providerInboundNo` `label()` |
|
||
|
|
| `Page<T>` | 见 2.2 |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
# 三、各能力怎么调用
|
||
|
|
|
||
|
|
## 3.0 视图结构
|
||
|
|
|
||
|
|
`WarehouseOperations` 是一组「视图」,每个视图负责一类能力:
|
||
|
|
|
||
|
|
| 视图 / 方法 | 负责 |
|
||
|
|
|---|---|
|
||
|
|
| `wh.outbound()` | 出库(创建 / 查询 / 面单 / 取消 / 附件) |
|
||
|
|
| `wh.inbound()` | 入库(创建 / 查询 / 补资料 / 提交 / 标签 / BOL) |
|
||
|
|
| `wh.inventory()` | 库存(查询 / 库龄 / 变动流水) |
|
||
|
|
| `wh.returns()` | 退货(创建 / 详情 / 列表 / 取消 / 处理) |
|
||
|
|
| `wh.fees()` | 费用(试算 / 结算 / 订单费用 / 仓租 / 推荐 / 地址属性) |
|
||
|
|
| `wh.createProduct(...)` / `wh.queryProducts(...)` | 商品 |
|
||
|
|
| `wh.track(...)` / `wh.trackShipment(...)` | 轨迹 |
|
||
|
|
| `wh.warehouses()` / `wh.carrierDirectory()` / `wh.logisticsProducts(...)` | 基础资料 |
|
||
|
|
| `wh.orderBols(...)` / `wh.printCaseMarks(...)` | 单据与打印 |
|
||
|
|
| `wh.createTransfer(...)` / `wh.createDestruction(...)` / `wh.createTrackingChange(...)` | 调拨 / 销毁 / 物流异动 |
|
||
|
|
|
||
|
|
> 视图是**每次调用现取的**,不是共享状态;`sdk.warehouses(code, conn)` 返回新对象。
|
||
|
|
|
||
|
|
## 3.1 能力矩阵
|
||
|
|
|
||
|
|
| 能力位 | 易达云 | 运去哪 | 信仓 | 恒健 |
|
||
|
|
|---|:---:|:---:|:---:|:---:|
|
||
|
|
| `PRODUCT` 商品 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `OUTBOUND` 出库 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `PLATFORM_LABEL_DELIVERY` | — | ✅ | — | ✅ |
|
||
|
|
| `INVENTORY_QUERY` 库存 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `INBOUND` 入库 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `RETURN` 退货 | ✅ | ✅ | — | ✅ |
|
||
|
|
| `RETURN_DISPOSITION` 退货处理 | — | ✅ | — | — |
|
||
|
|
| `FEE_SETTLEMENT` 费用 | ✅ | ✅ | — | ✅ |
|
||
|
|
| `FEE_ESTIMATE` 试算 | ✅ | ✅ | — | ✅ |
|
||
|
|
| `BOL` | ✅ | — | — | — |
|
||
|
|
| `TRACKING` 轨迹 | ✅ | ✅ | — | — |
|
||
|
|
| `TRACKING_CHANGE` 物流异动 | — | — | — | ✅ |
|
||
|
|
| `LOGISTICS_PRODUCT` | ✅ | ✅ | — | ✅ |
|
||
|
|
| `DIRECTORY` 仓/承运商 | ✅ | ✅ | ✅ | ✅ |
|
||
|
|
| `CASE_MARK_PRINT` 箱唛 | ✅ | — | — | — |
|
||
|
|
| `BOX_LABEL` 入库箱标 | — | ✅ | — | ✅ |
|
||
|
|
| `SKU_LABEL` | — | ✅ | — | — |
|
||
|
|
| `TRANSFER` 调拨 | — | ✅ | ✅ | ✅ |
|
||
|
|
| `DESTRUCTION` 销毁 | — | ✅ | — | ✅ |
|
||
|
|
| `SPLIT` 拆单 | — | — | ✅ | — |
|
||
|
|
| `CHANNEL_RECOMMEND` | — | — | ✅ | — |
|
||
|
|
| `ADDRESS_CLASSIFICATION` 地址属性 | — | — | — | ✅ |
|
||
|
|
| `WEBHOOK` 回调 | — | ✅ | — | — |
|
||
|
|
|
||
|
|
> 没声明的能力**门面会抛 `WarehouseUnsupportedCapabilityException`**,不返回空集合。
|
||
|
|
|
||
|
|
## 3.2 商品
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
|
||
|
|
|
||
|
|
// 建档(写)
|
||
|
|
WarehouseProductCapable.ProductResult saved = wh.createProduct(
|
||
|
|
WarehouseProduct.builder()
|
||
|
|
.omsSku("SKU-001")
|
||
|
|
.providerSku("AP0000X9US0010601")
|
||
|
|
.name("蓝牙音箱").nameEn("Bluetooth Speaker")
|
||
|
|
.lengthCm(12).widthCm(10).heightCm(8).weightGrams(500)
|
||
|
|
.barcode("N94900373802")
|
||
|
|
.declaredValue(Money.of("19.99", "USD"))
|
||
|
|
.countryOfOrigin("CN").hsCode("8517.62")
|
||
|
|
.build());
|
||
|
|
saved.providerSku(); // 仓侧 SKU
|
||
|
|
|
||
|
|
// 查询(只读)
|
||
|
|
Page<ProductInfo> page = wh.queryProducts(
|
||
|
|
ProductQuery.builder().providerSku("AP0000X9US0010601").build());
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3.3 出库
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseOutbounds out = wh.outbound();
|
||
|
|
|
||
|
|
// 建单(写,幂等键 = orderRef/outboundRequestNo)
|
||
|
|
OutboundReceipt r = out.create(cmd);
|
||
|
|
|
||
|
|
// 查单
|
||
|
|
OutboundOrder o = out.get(OutboundRef.ofRequestNo("OB-1")); // 用我们的单号
|
||
|
|
OutboundOrder o2 = out.get(OutboundRef.ofProviderOrderId("ORD123")); // 或用仓侧单号
|
||
|
|
|
||
|
|
// 分页查
|
||
|
|
// OutboundQuery 的时间 / 状态 / 排序端口径按仓定义,都是字符串
|
||
|
|
Page<OutboundOrder> list = out.query(OutboundQuery.builder()
|
||
|
|
.after(instant).before(instant)
|
||
|
|
.status("Shipped") // **仓侧原始状态字符串**,不是统一枚举
|
||
|
|
.pageSize(100).cursor(null)
|
||
|
|
.build());
|
||
|
|
|
||
|
|
// 面单
|
||
|
|
List<PackageResult> pkgs = out.packages(OutboundRef.ofRequestNo("OB-1"));
|
||
|
|
|
||
|
|
// 取消前校验 → 再取消
|
||
|
|
CancelEligibility e = out.checkCancel(OutboundRef.ofRequestNo("OB-1"));
|
||
|
|
if (e == CancelEligibility.FREE) {
|
||
|
|
CancelResult c = out.cancel(CancelCommand.builder()
|
||
|
|
.outboundRequestNo("OB-1").providerOrderId("ORD123").build());
|
||
|
|
}
|
||
|
|
|
||
|
|
// 附件
|
||
|
|
out.attachment(ref, attachments);
|
||
|
|
```
|
||
|
|
|
||
|
|
`CancelEligibility`:`FREE`(免费)/ `CHARGED`(收费)/ `BLOCKED`(不可取消)
|
||
|
|
|
||
|
|
> **`OutboundQuery.status(...)` 收的是仓侧原始状态字符串**(如易达云 `Shipped`),
|
||
|
|
> 不是统一的 `OutboundStatus` 枚举——各仓码表不同,适配器不归一。
|
||
|
|
> 想知道统一状态,用返回的 `OutboundOrder.status()`。
|
||
|
|
|
||
|
|
> 收费取消时 `acceptCharge=false` 会抛 `OutboundCancelChargeRequiredException`,
|
||
|
|
> 不可取消抛 `OutboundCancelBlockedException`。
|
||
|
|
|
||
|
|
## 3.4 库存
|
||
|
|
|
||
|
|
```java
|
||
|
|
// 策略
|
||
|
|
InventorySyncStrategy s = wh.inventorySyncStrategy();
|
||
|
|
|
||
|
|
// 查询
|
||
|
|
Page<InventorySnapshot> page = wh.inventory().query(
|
||
|
|
InventoryQuery.builder().sku("SKU").pageSize(100).build());
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3.5 入库
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseOperations.InboundView in = wh.inbound();
|
||
|
|
|
||
|
|
InboundReceipt r = in.create(cmd); // 写
|
||
|
|
InboundOrder o = in.get("IB-001"); // 按单号
|
||
|
|
Page<InboundOrder> list = in.query(cursor); // 按游标
|
||
|
|
Page<InboundOrder> adv = in.queryInbounds(InboundQuery.builder()...build());
|
||
|
|
in.improve("IB-001", cmd); // 写:补资料
|
||
|
|
in.submit("IB-001"); // 写:提交
|
||
|
|
List<String> bols = in.bols("IB-001"); // 入库计划 BOL 文件
|
||
|
|
LabelPrintTask box = in.printBoxLabel(boxLabelCmd); // 异步任务
|
||
|
|
LabelPrintTask sku = in.printSkuLabel(skuLabelCmd); // 异步任务
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3.6 退货
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseOperations.ReturnView rt = wh.returns();
|
||
|
|
|
||
|
|
WarehouseReturn r = rt.create(cmd); // 写,幂等键 = returnRequestNo
|
||
|
|
WarehouseReturn d = rt.get("RMA1001"); // 按仓侧 RMA 号
|
||
|
|
Page<WarehouseReturn> list = rt.query(ReturnQuery.builder()...build());
|
||
|
|
rt.process(processCmd); // 写:检验后处理(多数仓不支持)
|
||
|
|
boolean ok = rt.cancel("RMA1001"); // 写,幂等
|
||
|
|
```
|
||
|
|
|
||
|
|
> `cancel` 返回 `true` 表示成功;仓方拒绝时**抛 `WarehouseException`**,不返回 false。
|
||
|
|
|
||
|
|
## 3.7 费用
|
||
|
|
|
||
|
|
```java
|
||
|
|
WarehouseOperations.FeeView fee = wh.fees();
|
||
|
|
|
||
|
|
// 试算(发货前报价)
|
||
|
|
List<FeeEstimateResult> quotes = fee.estimate(FeeEstimateQuery.builder()...build());
|
||
|
|
|
||
|
|
// 结算明细(已发生)
|
||
|
|
List<BillingDocument> flows = fee.settlements(FeeQuery.builder()...build());
|
||
|
|
List<BillingDocument> costs = fee.orderCosts(FeeQuery.builder()...build());
|
||
|
|
List<BillingDocument> rents = fee.storageRents(FeeQuery.builder()...build());
|
||
|
|
|
||
|
|
// 最优渠道推荐(按 SKU + 邮编由仓择优)
|
||
|
|
ChannelRecommendResult best = fee.recommend(ChannelRecommendQuery.builder()...build());
|
||
|
|
|
||
|
|
// 地址属性识别(商业 / 住宅,影响附加费;恒健支持)
|
||
|
|
AddressType t = fee.classifyAddress(
|
||
|
|
"1308 E Washington Ave", null, "Escondido", "CA", "92027", "US");
|
||
|
|
// BUSINESS / RESIDENTIAL / MIXED / UNKNOWN
|
||
|
|
```
|
||
|
|
|
||
|
|
> 易达云三个费用方法都必须给**成本类型或时间窗**,否则本地拒绝(避免拉全量)。
|
||
|
|
|
||
|
|
## 3.8 基础资料(仓库 / 承运商 / 物流产品)
|
||
|
|
|
||
|
|
```java
|
||
|
|
// 仓库(只返回有权限的)
|
||
|
|
List<WarehouseFacility> whs = wh.warehouses();
|
||
|
|
|
||
|
|
// 承运商(带下属物流服务)
|
||
|
|
List<WarehouseCarrier> carriers = wh.carrierDirectory();
|
||
|
|
List<String> codes = wh.carriers(); // 只要码时用这个
|
||
|
|
|
||
|
|
// 物流产品
|
||
|
|
List<LogisticsProduct> products = wh.logisticsProducts("2"); // 数字仓 id
|
||
|
|
```
|
||
|
|
|
||
|
|
> - 易达云的仓库清单有**两个接口**:`warehouses()` 走「有权限」那个,
|
||
|
|
> `activeWarehouses(...)` 是平台全量(含未授权的,不要用来给客户选仓)。
|
||
|
|
> - 易达云承运商的 `carrierDirectory` 能给出两层结构;**只实现了 `carriers()` 的仓会抛不支持**,
|
||
|
|
> 不会把物流方式码硬凑成承运商名。
|
||
|
|
|
||
|
|
## 3.9 单据与打印(BOL / 轨迹 / 箱唛)
|
||
|
|
|
||
|
|
```java
|
||
|
|
// BOL(平台仓 / 店铺订单,带提货状态与 POD)
|
||
|
|
List<BolDocument> bols = wh.orderBols("FBA473182144");
|
||
|
|
|
||
|
|
// 轨迹
|
||
|
|
List<TrackEvent> events = wh.track("1Z111");
|
||
|
|
TrackingInfo info = wh.trackShipment("1Z111");
|
||
|
|
info.firstOnlineAt(); // 上网时间
|
||
|
|
info.deliveredAt(); // 妥投时间
|
||
|
|
|
||
|
|
// 箱唛(同步返回 PDF 地址;易达云支持)
|
||
|
|
WarehouseLabel label = wh.printCaseMarks(
|
||
|
|
CaseMarkPrintCommand.builder()
|
||
|
|
.paperSize(CaseMarkPaperSize.SIZE_70_30) // SIZE_70_30 / SIZE_100_60 / SIZE_100_150 / SIZE_60_40
|
||
|
|
.printSkuName(false)
|
||
|
|
.remark("Made in China")
|
||
|
|
.item("SKU", 1) // 仓侧 SKU + 份数,最多 50 个
|
||
|
|
.build());
|
||
|
|
label.url(); // PDF 地址
|
||
|
|
label.format(); // "PDF"
|
||
|
|
```
|
||
|
|
|
||
|
|
**易达云两个打印接口的语义是反的**(已与仓方确认):
|
||
|
|
|
||
|
|
| 端点 | 实际打印 | 方法 |
|
||
|
|
|---|---|---|
|
||
|
|
| `skuInfo/v2/printBarcode` | **箱唛** | `printCaseMarks(...)` |
|
||
|
|
| `entryInfo/v1/newPrintCaseMark` | SKU 标 | 未开放(仓方内部报错) |
|
||
|
|
|
||
|
|
> `track` 查不到返回**空列表**,`trackShipment` 返回 **null** —— 不抛异常。
|
||
|
|
> 易达云的 SKU 标(`printSkuLabel`)在 PR 环境仓方内部报错,未开放。
|
||
|
|
|
||
|
|
## 3.10 调拨 / 销毁 / 物流异动
|
||
|
|
|
||
|
|
```java
|
||
|
|
// 调拨(写)
|
||
|
|
TransferOrder t = wh.createTransfer(cmd);
|
||
|
|
wh.approveTransfer("T-001");
|
||
|
|
TransferOrder tg = wh.getTransfer("T-001");
|
||
|
|
Page<TransferOrder> tl = wh.queryTransfers(TransferQuery.builder()...build());
|
||
|
|
wh.deleteTransfer("T-001");
|
||
|
|
|
||
|
|
// 销毁(写)
|
||
|
|
DestructionOrder d = wh.createDestruction(cmd);
|
||
|
|
DestructionOrder dg = wh.getDestruction("D-001");
|
||
|
|
|
||
|
|
// 物流异动(写,恒健)
|
||
|
|
TrackingChangeOrder tc = wh.createTrackingChange(cmd);
|
||
|
|
TrackingChangeOrder tcg = wh.getTrackingChange("TC-001");
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
# 四、异常与重试
|
||
|
|
|
||
|
|
**异常层级**
|
||
|
|
|
||
|
|
```
|
||
|
|
ChannelException (RuntimeException) // 与渠道域共用基类
|
||
|
|
└── WarehouseException
|
||
|
|
├── WarehouseUnsupportedCapabilityException // 能力不支持,不要重试
|
||
|
|
├── WarehouseDuplicateOrderException // 重复下单
|
||
|
|
├── OutboundCancelBlockedException // 取消被拒
|
||
|
|
├── OutboundCancelChargeRequiredException // 取消要收费
|
||
|
|
└── WarehouseWebhookVerificationException // 回调验签失败(宿主返 4xx)
|
||
|
|
```
|
||
|
|
|
||
|
|
**取值**
|
||
|
|
|
||
|
|
```java
|
||
|
|
catch (WarehouseException e) {
|
||
|
|
e.operation(); // "warehouse.outbound.create"
|
||
|
|
e.warehouseCode();
|
||
|
|
e.provider();
|
||
|
|
e.requestId(); // 我们生成的链路 ID
|
||
|
|
e.platformCode(); // 仓方业务码
|
||
|
|
e.platformRequestId(); // 仓方链路 ID
|
||
|
|
e.retryable(); // true = 可重试
|
||
|
|
e.rawResponse(); // 原始报文(**含 PII,别直接落日志**)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**重试判定**
|
||
|
|
|
||
|
|
| 情况 | `retryable` |
|
||
|
|
|---|---|
|
||
|
|
| 网络 / 超时(`TransientException`) | `true` |
|
||
|
|
| HTTP 5xx | `true` |
|
||
|
|
| HTTP 4xx / 业务码非成功 | `false` |
|
||
|
|
| 能力不支持 | 不重试 |
|
||
|
|
|
||
|
|
**幂等**
|
||
|
|
|
||
|
|
写操作全部走幂等守卫,重复调用不会重复下单:
|
||
|
|
|
||
|
|
| 操作 | 幂等键 |
|
||
|
|
|---|---|
|
||
|
|
| `outbound().create` | `warehouseCode + outboundRequestNo + create` |
|
||
|
|
| `inbound().create` | `warehouseCode + inboundRequestNo + create` |
|
||
|
|
| `returns().create` | `warehouseCode + returnRequestNo + create` |
|
||
|
|
| `returns().cancel` | `warehouseCode + providerReturnNo + cancel` |
|
||
|
|
| `createTransfer` | `warehouseCode + transferRequestNo + create` |
|
||
|
|
|
||
|
|
重放时返回上次的结果引用,**不会真的再调一次仓方**。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
# 五、常见坑速查
|
||
|
|
|
||
|
|
| 坑 | 说明 |
|
||
|
|
|---|---|
|
||
|
|
| **SKU 用哪个** | 一律用「建档下发的 `providerSku`」,为空才是 `omsSku`。全程一致 |
|
||
|
|
| **易达云建档是「创建」** | 同 SKU 重复调用报错,不是 upsert。运去哪才是 upsert |
|
||
|
|
| **易达云布尔反着来** | `brandFlag` / `electricFlag` 是 0 是 / 1 否,别手写 `x ? 0 : 1` |
|
||
|
|
| **地址州名** | 运去哪要二字码 `CA`;易达云要全称 `California` |
|
||
|
|
| **面单格式** | 易达云要**文件 URL**,不是 base64 |
|
||
|
|
| **金额要带币种** | 一律 `Money`,裸数字会丢单位 |
|
||
|
|
| **`-1` 是「没给」** | `pendingOutbound` / `alertQuantity` 为 -1 表示仓方没返回,不是 0 |
|
||
|
|
| **翻页用 `nextCursor()`** | 各仓页码起点不同,游标已屏蔽差异,别自己 ±1 |
|
||
|
|
| **空结果不抛异常** | 查询类接口无数据返回空 `Page` / 空 List(易达云的「查询无数据」也算空) |
|
||
|
|
| **能力未声明会抛异常** | 不返回空集合,先 `sdk.capabilities()` 判断 |
|
||
|
|
| **门面要单例** | 每次 `new` 会丢 token 与限流状态 |
|
||
|
|
| **探针测试默认跳过** | 需要 `-Dxxx.probe=true` 才跑,不会误连生产 |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 附:日志
|
||
|
|
|
||
|
|
```java
|
||
|
|
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
|
||
|
|
```
|
||
|
|
|
||
|
|
输出形如:
|
||
|
|
|
||
|
|
```
|
||
|
|
sdk-call at=2026-11-17 10:00:00 op=warehouse.product.query provider=EDAYUN
|
||
|
|
requestId=xxx cost=812ms result=1 failed=0 code=200 params={skuCount=1}
|
||
|
|
```
|
||
|
|
|
||
|
|
失败时多带 `retryable` / `platformCode` / `platformRequestId` / `error`,
|
||
|
|
并对仓方文案做去换行 + 截断(防日志注入)。日志**不含凭据与报文**。
|