|
|
|
|
|
# 三方仓 SDK 使用说明(源码集成版)
|
|
|
|
|
|
|
|
|
|
|
|
> 源码已随交付提供,直接在本项目里使用即可。
|
|
|
|
|
|
>
|
|
|
|
|
|
> JDK 1.8;需要 `jackson-databind 2.13.5`、`slf4j-api 1.7.36`、`okhttp 4.12.0`
|
|
|
|
|
|
> (或自己实现 `HttpTransport` 替换 OkHttp)。
|
|
|
|
|
|
>
|
|
|
|
|
|
> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 快速导航
|
|
|
|
|
|
|
|
|
|
|
|
| 我要… | 看这节 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 配好 SPI / SDK / 连接 | [一、配置](#一配置) |
|
|
|
|
|
|
| 确认能跑通 | [二、快速上手](#二快速上手) |
|
|
|
|
|
|
| 知道某仓支不支持某功能 | [三、我要做的事能不能做](#三我要做的事能不能做) |
|
|
|
|
|
|
| 发货 / 面单 | [4.1](#41-发货建出库单--拿面单) |
|
|
|
|
|
|
| 查轨迹 / 取消订单 | [4.2](#42-查物流轨迹) · [4.3](#43-取消出库单) |
|
|
|
|
|
|
| 退货 / 库存 / 商品 / 对账 | [4.4](#44-退货) · [4.5](#45-库存同步) · [4.6](#46-商品主数据) · [4.7](#47-对账拉费用明细) |
|
|
|
|
|
|
| 打箱唛 / BOL | [4.8](#48-打单箱唛--bol) |
|
|
|
|
|
|
| 单位 / SKU / 分页 / 金额 | [五、贯穿全局的规则](#五几条贯穿全局的规则) |
|
|
|
|
|
|
| 报错 / 重试 | [六、出错了怎么办](#六出错了怎么办) |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 一、配置
|
|
|
|
|
|
|
|
|
|
|
|
## 1.1 实现两个 SPI
|
|
|
|
|
|
|
|
|
|
|
|
### ① 仓编码 → 哪家仓
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.spi.WarehouseRepository;
|
|
|
|
|
|
import common.ecommerce.warehouse.spi.WarehouseAccount;
|
|
|
|
|
|
import java.util.*;
|
|
|
|
|
|
|
|
|
|
|
|
public class MyWarehouseRepository implements WarehouseRepository {
|
|
|
|
|
|
|
|
|
|
|
|
private final Map<String, WarehouseAccount> accounts = new HashMap<>();
|
|
|
|
|
|
|
|
|
|
|
|
public MyWarehouseRepository() {
|
|
|
|
|
|
// 从你们的仓主数据表加载
|
|
|
|
|
|
accounts.put("EDY-USLA", WarehouseAccount.builder()
|
|
|
|
|
|
.warehouseCode("EDY-USLA") // OMS 侧仓编码
|
|
|
|
|
|
.provider("EDAYUN") // 决定用哪个适配器
|
|
|
|
|
|
.providerWarehouseId("2") // 仓方仓 id
|
|
|
|
|
|
.credentialRef("kms://edayun") // 只是个标识,SDK 不会去取
|
|
|
|
|
|
.timeZone("America/Los_Angeles")
|
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
|
|
accounts.put("YQN-NY", WarehouseAccount.builder()
|
|
|
|
|
|
.warehouseCode("YQN-NY")
|
|
|
|
|
|
.provider("YQN")
|
|
|
|
|
|
.providerWarehouseId("RF_NY_US") // 运去哪用仓编码
|
|
|
|
|
|
.credentialRef("kms://yqn")
|
|
|
|
|
|
.timeZone("America/New_York")
|
|
|
|
|
|
.build());
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public List<WarehouseAccount> findByWarehouseCode(String warehouseCode) {
|
|
|
|
|
|
WarehouseAccount a = accounts.get(warehouseCode);
|
|
|
|
|
|
return a == null ? Collections.<WarehouseAccount>emptyList()
|
|
|
|
|
|
: Collections.singletonList(a);
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public Optional<WarehouseAccount> find(String warehouseCode, String provider) {
|
|
|
|
|
|
WarehouseAccount a = accounts.get(warehouseCode);
|
|
|
|
|
|
return a != null && a.provider().equals(provider) ? Optional.of(a) : Optional.empty();
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**`providerWarehouseId` 各仓填什么**
|
|
|
|
|
|
|
|
|
|
|
|
| 仓 | 填什么 | 例子 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| 易达云 | 数字仓 id | `"2"` |
|
|
|
|
|
|
| 运去哪 | 仓编码 | `"RF_NY_US"` |
|
|
|
|
|
|
| 信仓 | 仓编码 | |
|
|
|
|
|
|
| 恒健 | 仓编码 | |
|
|
|
|
|
|
|
|
|
|
|
|
### ② 写操作怎么防重复
|
|
|
|
|
|
|
|
|
|
|
|
只要你们有建单 / 取消这类写操作就必须实现。核心是**「查 + 写」必须原子**。
|
|
|
|
|
|
|
|
|
|
|
|
> 下面代码里的 `loadFromRedisOrDb` / `reclaimable` / `writeInProgress` / `markStatus`
|
|
|
|
|
|
> 是**示意方法名**,按你们自己的存储实现。
|
|
|
|
|
|
> 结构可以照抄 `sdk-testkit/InMemoryIdempotencyStore`(如果拷了的话)。
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.shared.spi.*;
|
|
|
|
|
|
import java.time.Instant;
|
|
|
|
|
|
import java.util.Optional;
|
|
|
|
|
|
|
|
|
|
|
|
public class MyIdempotencyStore implements IdempotencyStore {
|
|
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
|
* 抢占。四种返回:
|
|
|
|
|
|
* acquire() 抢占成功 → 去调仓
|
|
|
|
|
|
* of(SUCCEEDED, record) 之前做过了 → 用 record.resultRef() 回放
|
|
|
|
|
|
* of(IN_PROGRESS, record) 别人正在做 → 等一下或报冲突
|
|
|
|
|
|
* of(FAILED_FINAL, record) 之前终态失败 → 人工介入
|
|
|
|
|
|
*/
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public IdempotencyClaim claim(String key, String owner, String provider,
|
|
|
|
|
|
Instant now, long ttlSeconds) {
|
|
|
|
|
|
IdempotencyRecord existing = loadFromRedisOrDb(key);
|
|
|
|
|
|
|
|
|
|
|
|
if (existing == null || reclaimable(existing, now, ttlSeconds)) {
|
|
|
|
|
|
writeInProgress(key, owner, provider, now);
|
|
|
|
|
|
return IdempotencyClaim.acquire();
|
|
|
|
|
|
}
|
|
|
|
|
|
switch (existing.status()) {
|
|
|
|
|
|
case SUCCEEDED: return IdempotencyClaim.of(IdempotencyClaim.Outcome.SUCCEEDED, existing);
|
|
|
|
|
|
case FAILED_FINAL: return IdempotencyClaim.of(IdempotencyClaim.Outcome.FAILED_FINAL, existing);
|
|
|
|
|
|
default: return IdempotencyClaim.of(IdempotencyClaim.Outcome.IN_PROGRESS, existing);
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public void complete(String key, String owner, String resultRef, Instant now) {
|
|
|
|
|
|
markStatus(key, owner, IdempotencyStatus.SUCCEEDED, resultRef, now);
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public void fail(String key, String owner, boolean retryable, Instant now) {
|
|
|
|
|
|
markStatus(key, owner,
|
|
|
|
|
|
retryable ? IdempotencyStatus.FAILED_RETRYABLE : IdempotencyStatus.FAILED_FINAL,
|
|
|
|
|
|
null, now);
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
|
public Optional<IdempotencyRecord> get(String key) {
|
|
|
|
|
|
return Optional.ofNullable(loadFromRedisOrDb(key));
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**必须满足两条**
|
|
|
|
|
|
|
|
|
|
|
|
1. `claim()` 的「查 + 写」要原子:Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引
|
|
|
|
|
|
2. `complete` / `fail` 只能由当前 owner 写,否则过期 owner 会覆盖新抢占者的结果
|
|
|
|
|
|
|
|
|
|
|
|
> 只做查询可以先不实现;一旦建单会抛
|
|
|
|
|
|
> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。
|
|
|
|
|
|
|
|
|
|
|
|
## 1.2 组装 SDK
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseSdk;
|
|
|
|
|
|
import common.ecommerce.shared.audit.Slf4jCallObserver;
|
|
|
|
|
|
import common.ecommerce.edayun.adapter.EdayunAdapterFactory;
|
|
|
|
|
|
import common.ecommerce.yqn.adapter.YqnAdapterFactory;
|
|
|
|
|
|
import java.time.Clock;
|
|
|
|
|
|
import java.time.ZoneId;
|
|
|
|
|
|
|
|
|
|
|
|
// Spring 里定义成单例 Bean
|
|
|
|
|
|
WarehouseSdk sdk = WarehouseSdk.builder()
|
|
|
|
|
|
.warehouseRepository(new MyWarehouseRepository()) // 必需
|
|
|
|
|
|
.idempotencyStore(myIdempotencyStore) // 写操作必需
|
|
|
|
|
|
.clock(Clock.systemUTC())
|
|
|
|
|
|
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
|
|
|
|
|
|
.register(new EdayunAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
|
|
|
|
|
|
.register(new YqnAdapterFactory(Clock.systemUTC()))
|
|
|
|
|
|
.build();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**各仓工厂的构造参数**
|
|
|
|
|
|
|
|
|
|
|
|
| 工厂 | 构造参数 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `EdayunAdapterFactory` | `(TokenStore, LockProvider, Clock)`;前两个可传 `null`(则每次重登) |
|
|
|
|
|
|
| `YqnAdapterFactory` | `(Clock)` |
|
|
|
|
|
|
| `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` |
|
|
|
|
|
|
| `HengjianAdapterFactory` | 无参 |
|
|
|
|
|
|
|
|
|
|
|
|
> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。
|
|
|
|
|
|
|
|
|
|
|
|
## 1.3 连接信息(端点 + 凭据)
|
|
|
|
|
|
|
|
|
|
|
|
SDK 不保存端点和凭据,每次调用由你们传:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseConnection;
|
|
|
|
|
|
import common.ecommerce.shared.spi.ChannelSecret;
|
|
|
|
|
|
|
|
|
|
|
|
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` | 前两个算签名,后两个换 token |
|
|
|
|
|
|
| 运去哪 | `appSecret` | 组织级 token,直接放 `appSecret` |
|
|
|
|
|
|
| 信仓 | `appKey` `appSecret` | 换 token |
|
|
|
|
|
|
| 恒健 | `appSecret` | 算签名 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 二、快速上手
|
|
|
|
|
|
|
|
|
|
|
|
## 2.1 拿到仓的操作入口
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseOperations;
|
|
|
|
|
|
|
|
|
|
|
|
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
后面所有 `wh.xxx()` 都从这个对象出发。
|
|
|
|
|
|
|
|
|
|
|
|
## 2.2 验证能跑通
|
|
|
|
|
|
|
|
|
|
|
|
**只读,不改任何数据**:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.model.WarehouseFacility;
|
|
|
|
|
|
import java.util.List;
|
|
|
|
|
|
|
|
|
|
|
|
List<WarehouseFacility> warehouses = wh.warehouses();
|
|
|
|
|
|
System.out.println("该账户有权限的仓:" + warehouses.size());
|
|
|
|
|
|
for (WarehouseFacility w : warehouses) {
|
|
|
|
|
|
System.out.println(" " + w.warehouseCode() + " " + w.name());
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
能打出仓,说明凭据、端点、配置全对。跑不通时:
|
|
|
|
|
|
|
|
|
|
|
|
| 现象 | 原因 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 |
|
|
|
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#三我要做的事能不能做)) |
|
|
|
|
|
|
| `http 401` / token 错误 | `ChannelSecret` 字段填错 |
|
|
|
|
|
|
| 超时 | 端点不通;易达云首次调用慢,重试一次 |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 三、我要做的事能不能做?
|
|
|
|
|
|
|
|
|
|
|
|
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 |
|
|
|
|
|
|
|---|---|:---:|:---:|:---:|:---:|
|
|
|
|
|
|
| 建出库单 / 打面单 | `outbound().create` / `.packages` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 查出库单 | `outbound().get` / `.query` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 取消出库单 | `outbound().cancel` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 查库存 | `inventory().query` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 建入库单 | `inbound().create` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 退货(建单 / 查 / 取消) | `returns().create` / `.get` / `.cancel` | ✅ | ✅ | ❌ | ✅ |
|
|
|
|
|
|
| 退货检验后处理 | `returns().process` | ❌ | ✅ | ❌ | ❌ |
|
|
|
|
|
|
| 拉费用明细 | `fees().settlements` | ✅ | ✅ | ❌ | ✅ |
|
|
|
|
|
|
| 费用试算 | `fees().estimate` | ✅ | ✅ | ❌ | ✅ |
|
|
|
|
|
|
| 商品建档 | `createProduct` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 商品查询 | `queryProducts` | ✅ | ✅ | ❌ | ❌ |
|
|
|
|
|
|
| 物流轨迹 | `track` / `trackShipment` | ✅ | ✅ | ❌ | ❌ |
|
|
|
|
|
|
| 仓库清单 | `warehouses()` | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 承运商清单 | `carrierDirectory()` | ✅ | ❌ | ❌ | ❌ |
|
|
|
|
|
|
| 物流产品清单 | `logisticsProducts(code)` | ✅ | ✅ | ❌ | ✅ |
|
|
|
|
|
|
| BOL(平台仓订单) | `orderBols(no)` | ✅ | ❌ | ❌ | ❌ |
|
|
|
|
|
|
| 打印箱唛 | `printCaseMarks(cmd)` | ✅ | ❌ | ❌ | ❌ |
|
|
|
|
|
|
| 调拨 | `createTransfer` | ❌ | ✅ | ✅ | ✅ |
|
|
|
|
|
|
| 销毁 | `createDestruction` | ❌ | ✅ | ❌ | ✅ |
|
|
|
|
|
|
| 物流异动(召回 / 改址) | `createTrackingChange` | ❌ | ❌ | ❌ | ✅ |
|
|
|
|
|
|
|
|
|
|
|
|
> **不支持就是抛异常**,不返回空列表。
|
|
|
|
|
|
> 代码判断:`sdk.capabilities("EDY-USLA").supported().contains(WarehouseCapability.RETURN)`
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 四、按任务
|
|
|
|
|
|
|
|
|
|
|
|
> 以下假设 `wh` 已就绪(见 [2.1](#21-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。
|
|
|
|
|
|
|
|
|
|
|
|
## 4.1 发货:建出库单 → 拿面单
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.shared.model.Platform;
|
|
|
|
|
|
import common.ecommerce.shared.support.Money;
|
|
|
|
|
|
import common.ecommerce.warehouse.model.*;
|
|
|
|
|
|
|
|
|
|
|
|
OutboundCommand cmd = OutboundCommand.builder()
|
|
|
|
|
|
// ===== 必填 =====
|
|
|
|
|
|
.outboundRequestNo("OB-20261117-001")
|
|
|
|
|
|
.salesPlatform(Platform.AMAZON_SC)
|
|
|
|
|
|
.shipTo(ShipTo.builder()
|
|
|
|
|
|
.name("John Smith")
|
|
|
|
|
|
.phone("+1-555-0100")
|
|
|
|
|
|
.countryCode("US") // 二字码
|
|
|
|
|
|
.stateOrProvince("California") // ⚠️ 易达云要全称、运去哪要 CA
|
|
|
|
|
|
.city("Escondido")
|
|
|
|
|
|
.addressLine1("1308 E Washington Ave")
|
|
|
|
|
|
.postalCode("92027")
|
|
|
|
|
|
.build())
|
|
|
|
|
|
.line(OutboundLine.builder()
|
|
|
|
|
|
.lineNo("1")
|
|
|
|
|
|
.omsSku("SKU-001")
|
|
|
|
|
|
.providerSku("AP0000X9US0010601") // ⚠️ 见 6.2 SKU
|
|
|
|
|
|
.quantity(2)
|
|
|
|
|
|
.declareName("蓝牙音箱")
|
|
|
|
|
|
.declareValue(Money.of("19.99", "USD")) // 单价,不是总额
|
|
|
|
|
|
.build())
|
|
|
|
|
|
// ===== 强烈建议 =====
|
|
|
|
|
|
.orderRef("SO-20261117-001") // 平台单号,仓侧幂等键
|
|
|
|
|
|
.warehouseId("2")
|
|
|
|
|
|
.currency("USD")
|
|
|
|
|
|
.declaredTotal(Money.of("39.98", "USD"))
|
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
|
|
OutboundReceipt receipt = wh.outbound().create(cmd);
|
|
|
|
|
|
receipt.providerOrderId(); // 仓侧单号,**保存下来**
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
拿面单:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
List<PackageResult> pkgs = wh.outbound().packages(
|
|
|
|
|
|
OutboundRef.ofRequestNo("OB-20261117-001"));
|
|
|
|
|
|
for (PackageResult p : pkgs) {
|
|
|
|
|
|
p.trackingNumber(); // 跟踪号
|
|
|
|
|
|
p.labelRef(); // 面单 URL
|
|
|
|
|
|
p.carrier();
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**
|
|
|
|
|
|
|
|
|
|
|
|
1. 州名:易达云要 `California`,运去哪要 `CA`
|
|
|
|
|
|
2. 平台面单把 `labelMode` 设为 `PLATFORM_LABEL`;易达云要**文件 URL 不是 base64**
|
|
|
|
|
|
3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`)
|
|
|
|
|
|
4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求
|
|
|
|
|
|
|
|
|
|
|
|
## 4.2 查物流轨迹
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
List<TrackEvent> events = wh.track("1Z999AA10123456784");
|
|
|
|
|
|
|
|
|
|
|
|
TrackingInfo info = wh.trackShipment("1Z999AA10123456784");
|
|
|
|
|
|
info.firstOnlineAt(); // 上网时间(为空 = 物流还没启动)
|
|
|
|
|
|
info.deliveredAt(); // 妥投时间(为空 = 未签收)
|
|
|
|
|
|
info.signedBy(); // 签收人(未签收 = null)
|
|
|
|
|
|
info.events();
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。
|
|
|
|
|
|
|
|
|
|
|
|
## 4.3 取消出库单
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
CancelEligibility e = wh.outbound().checkCancel(
|
|
|
|
|
|
OutboundRef.ofRequestNo("OB-20261117-001"));
|
|
|
|
|
|
// FREE / CHARGED / BLOCKED
|
|
|
|
|
|
|
|
|
|
|
|
if (e == CancelEligibility.FREE) {
|
|
|
|
|
|
CancelResult r = wh.outbound().cancel(CancelCommand.builder()
|
|
|
|
|
|
.outboundRequestNo("OB-20261117-001")
|
|
|
|
|
|
.providerOrderId("ORD123")
|
|
|
|
|
|
.acceptCharge(false)
|
|
|
|
|
|
.build());
|
|
|
|
|
|
r.cancelled();
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`;
|
|
|
|
|
|
`BLOCKED` 抛 `OutboundCancelBlockedException`。
|
|
|
|
|
|
|
|
|
|
|
|
## 4.4 退货
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.enums.ReturnDealMethod;
|
|
|
|
|
|
|
|
|
|
|
|
WarehouseReturn r = wh.returns().create(ReturnCommand.builder()
|
|
|
|
|
|
.returnRequestNo("RT-20261117-001") // 幂等键
|
|
|
|
|
|
.saleOrderNo("SO-20261117-001")
|
|
|
|
|
|
.returnTrackingNo("1Z999AA10123456784")
|
|
|
|
|
|
.carrierCode("FedEx")
|
|
|
|
|
|
.line("AP0000X9US0010601", 1, ReturnDealMethod.WAREHOUSE_CONFIRM)
|
|
|
|
|
|
.warehouseId("2")
|
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
|
|
r.providerReturnId(); // 仓侧 RMA 号,**保存下来**
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
查进度 / 取消:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
WarehouseReturn detail = wh.returns().get("RMA2411053149");
|
|
|
|
|
|
detail.status(); // 统一状态
|
|
|
|
|
|
detail.rawStatus(); // 仓方原文
|
|
|
|
|
|
detail.lines();
|
|
|
|
|
|
|
|
|
|
|
|
boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` /
|
|
|
|
|
|
`returnReason`(传了直接报错)。
|
|
|
|
|
|
|
|
|
|
|
|
## 4.5 库存同步
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
Page<InventorySnapshot> page = wh.inventory().query(
|
|
|
|
|
|
InventoryQuery.builder()
|
|
|
|
|
|
.sku("AP0000X9US0010601")
|
|
|
|
|
|
.includeZeroStock(true)
|
|
|
|
|
|
.pageSize(500)
|
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
|
|
for (InventorySnapshot s : page.items()) {
|
|
|
|
|
|
s.available(); s.onHand(); s.inTransit(); s.reserved();
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
// 先问支不支持增量
|
|
|
|
|
|
InventorySyncStrategy strategy = wh.inventorySyncStrategy();
|
|
|
|
|
|
// TIME_WINDOW 可按 updatedAfter 增量 / FULL_PULL_DIFF 只能全量拉再比对
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**
|
|
|
|
|
|
|
|
|
|
|
|
- **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1)
|
|
|
|
|
|
- 易达云没有时间维度,`updatedAfter` 不生效
|
|
|
|
|
|
|
|
|
|
|
|
## 4.6 商品主数据
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
WarehouseProduct p = WarehouseProduct.builder()
|
|
|
|
|
|
.omsSku("SKU-001")
|
|
|
|
|
|
.name("蓝牙音箱")
|
|
|
|
|
|
.lengthCm(12).widthCm(10).heightCm(8)
|
|
|
|
|
|
.weightGrams(500)
|
|
|
|
|
|
.providerSku("AP0000X9US0010601")
|
|
|
|
|
|
.nameEn("Bluetooth Speaker")
|
|
|
|
|
|
.barcode("N94900373802")
|
|
|
|
|
|
.declaredValue(Money.of("19.99", "USD"))
|
|
|
|
|
|
.countryOfOrigin("CN")
|
|
|
|
|
|
.hsCode("8517.62")
|
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
|
|
wh.createProduct(p);
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**分仓必填差异**
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 易达云 | 运去哪 | 信仓 |
|
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
| `nameEn` | 可选 | **必填** | 不用 |
|
|
|
|
|
|
| `packingType` | 不用 | **必填**(0 原包装 / 1 重新打包) | 不用 |
|
|
|
|
|
|
| `hsCode` 三项 | 用 | **必填整组** | 只用 `declaredValue` |
|
|
|
|
|
|
|
|
|
|
|
|
查询:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
Page<ProductInfo> page = wh.queryProducts(
|
|
|
|
|
|
ProductQuery.builder().providerSku("AP0000X9US0010601").build());
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**
|
|
|
|
|
|
|
|
|
|
|
|
- 易达云是「创建」不是 upsert,同 SKU 重复建档会报错
|
|
|
|
|
|
- 易达云不带时间窗只查最近一个月
|
|
|
|
|
|
- 运去哪不支持条码 / 时间窗过滤,传了本地报错
|
|
|
|
|
|
|
|
|
|
|
|
## 4.7 对账:拉费用明细
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
// ① 账户流水
|
|
|
|
|
|
List<BillingDocument> flows = wh.fees().settlements(FeeQuery.builder()
|
|
|
|
|
|
.settledAfter(Instant.parse("2026-10-01T00:00:00Z"))
|
|
|
|
|
|
.settledBefore(Instant.parse("2026-11-01T00:00:00Z"))
|
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
|
|
// ② 按订单拆的费用
|
|
|
|
|
|
List<BillingDocument> costs = wh.fees().orderCosts(FeeQuery.builder()
|
|
|
|
|
|
.saleOrderNo("SO-20261117-001").build());
|
|
|
|
|
|
|
|
|
|
|
|
// ③ 仓租
|
|
|
|
|
|
List<BillingDocument> rents = wh.fees().storageRents(FeeQuery.builder()
|
|
|
|
|
|
.settledAfter(Instant.parse("2026-10-01T00:00:00Z"))
|
|
|
|
|
|
.settledBefore(Instant.parse("2026-10-31T00:00:00Z"))
|
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
|
|
// 发货前算运费
|
|
|
|
|
|
List<FeeEstimateResult> quotes = wh.fees().estimate(FeeEstimateQuery.builder()
|
|
|
|
|
|
.lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
|
|
|
|
|
|
.receiveCountry("US").receivePostal("91761")
|
|
|
|
|
|
.logisticsServiceCode("80")
|
|
|
|
|
|
.build());
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
单据字段:`documentNo()` / `feeName()` / `feeType()` / `amount()` / `settledAt()` / `estimated()`
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。
|
|
|
|
|
|
|
|
|
|
|
|
## 4.8 打单:箱唛 / BOL
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
import common.ecommerce.warehouse.enums.CaseMarkPaperSize;
|
|
|
|
|
|
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
|
|
|
|
|
|
|
|
|
|
|
|
WarehouseLabel label = wh.printCaseMarks(CaseMarkPrintCommand.builder()
|
|
|
|
|
|
.paperSize(CaseMarkPaperSize.SIZE_70_30)
|
|
|
|
|
|
.printSkuName(false)
|
|
|
|
|
|
.remark("Made in China")
|
|
|
|
|
|
.item("AP0000X9US0010601", 2) // SKU + 份数,最多 50 个
|
|
|
|
|
|
.build());
|
|
|
|
|
|
label.url(); // PDF 地址
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
| 纸张 | 实际尺寸 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `SIZE_70_30` | 70 × 30 mm |
|
|
|
|
|
|
| `SIZE_100_60` | 100 × 60 mm |
|
|
|
|
|
|
| `SIZE_100_150` | 100 × 150 mm |
|
|
|
|
|
|
| `SIZE_60_40` | 60 × 40 mm |
|
|
|
|
|
|
|
|
|
|
|
|
> 枚举按**实测尺寸**命名。仓方文档标的与实际印出来的对不上,以枚举名为准。
|
|
|
|
|
|
|
|
|
|
|
|
BOL(提货单 / 签收凭证):
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
List<BolDocument> bols = wh.orderBols("FBA473182144");
|
|
|
|
|
|
b.fileUrl(); // BOL 文件
|
|
|
|
|
|
b.podFileUrl(); // 签收凭证
|
|
|
|
|
|
b.statusName(); // 如「已妥投」
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 五、几条贯穿全局的规则
|
|
|
|
|
|
|
|
|
|
|
|
## 5.1 单位:尺寸 cm、重量 g
|
|
|
|
|
|
|
|
|
|
|
|
字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。
|
|
|
|
|
|
|
|
|
|
|
|
## 5.2 SKU:到底传哪一个(最容易错)
|
|
|
|
|
|
|
|
|
|
|
|
**所有地方都用「建档时下发给仓方的那一串」。**
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
建档时:providerSku 有值 → 仓方存它
|
|
|
|
|
|
没值 → 仓方存 omsSku
|
|
|
|
|
|
↓
|
|
|
|
|
|
之后:查商品 / 下单 / 查库存 都用同一串
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
| 建档时 | 仓方存的 | 之后必须传 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) |
|
|
|
|
|
|
| 没传 | `omsSku` | `omsSku` |
|
|
|
|
|
|
|
|
|
|
|
|
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。
|
|
|
|
|
|
|
|
|
|
|
|
## 5.3 分页
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
String cursor = null;
|
|
|
|
|
|
do {
|
|
|
|
|
|
Page<X> page = wh.xxx(Query.builder().cursor(cursor).pageSize(100).build());
|
|
|
|
|
|
// 处理 page.items()
|
|
|
|
|
|
cursor = page.nextCursor();
|
|
|
|
|
|
} while (cursor != null);
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
- 第一页 `cursor` 传 `null`
|
|
|
|
|
|
- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异
|
|
|
|
|
|
- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜
|
|
|
|
|
|
|
|
|
|
|
|
## 5.4 金额
|
|
|
|
|
|
|
|
|
|
|
|
一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# 六、出错了怎么办
|
|
|
|
|
|
|
|
|
|
|
|
## 6.1 五类异常
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
try {
|
|
|
|
|
|
wh.outbound().create(cmd);
|
|
|
|
|
|
} catch (OutboundCancelChargeRequiredException e) {
|
|
|
|
|
|
// 取消要收费,等用户确认
|
|
|
|
|
|
} catch (OutboundCancelBlockedException e) {
|
|
|
|
|
|
// 已发货不能取消
|
|
|
|
|
|
} catch (WarehouseUnsupportedCapabilityException e) {
|
|
|
|
|
|
// 该仓不支持,换方案
|
|
|
|
|
|
} catch (TransientException e) {
|
|
|
|
|
|
// 网络 / 超时,可重试
|
|
|
|
|
|
} catch (WarehouseException e) {
|
|
|
|
|
|
// 其它仓方错误
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
| 异常 | 含义 | 重试? |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| `TransientException` | 网络 / 超时 | ✅ |
|
|
|
|
|
|
| `WarehouseException`(`retryable=true`) | HTTP 5xx | ✅ |
|
|
|
|
|
|
| `WarehouseException`(`retryable=false`) | 业务错误(参数 / 单号) | ❌ |
|
|
|
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓不支持 | ❌ |
|
|
|
|
|
|
| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 |
|
|
|
|
|
|
| `OutboundCancelBlockedException` | 不能取消 | ❌ |
|
|
|
|
|
|
|
|
|
|
|
|
## 6.2 异常里有什么
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
catch (WarehouseException e) {
|
|
|
|
|
|
e.operation(); // "warehouse.outbound.create"
|
|
|
|
|
|
e.warehouseCode(); // 哪个仓
|
|
|
|
|
|
e.requestId(); // 我们的链路 ID
|
|
|
|
|
|
e.platformCode(); // 仓方业务码
|
|
|
|
|
|
e.platformRequestId(); // 仓方链路 ID,问仓方时给这个
|
|
|
|
|
|
e.retryable();
|
|
|
|
|
|
e.getMessage();
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。
|
|
|
|
|
|
|
|
|
|
|
|
## 6.3 常见报错对照
|
|
|
|
|
|
|
|
|
|
|
|
| 报错 | 原因 | 怎么办 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| `requires an idempotencyStore` | 没配 | 见 [1.1](#11-实现两个-spi) |
|
|
|
|
|
|
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` |
|
|
|
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#三我要做的事能不能做) |
|
|
|
|
|
|
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` |
|
|
|
|
|
|
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [5.2](#52-sku到底传哪一个最容易错) |
|
|
|
|
|
|
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` |
|
|
|
|
|
|
|
|
|
|
|
|
## 6.4 幂等:重复调用安全吗
|
|
|
|
|
|
|
|
|
|
|
|
写操作都安全,同样单号调两次不会重复下单:
|
|
|
|
|
|
|
|
|
|
|
|
| 操作 | 幂等键 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 建出库单 | 仓编码 + `outboundRequestNo`(或 `orderRef`) |
|
|
|
|
|
|
| 建入库单 | 仓编码 + `inboundRequestNo` |
|
|
|
|
|
|
| 建退货单 | 仓编码 + `returnRequestNo` |
|
|
|
|
|
|
| 取消退货单 | 仓编码 + 仓侧 RMA 号 |
|
|
|
|
|
|
| 建调拨单 | 仓编码 + `transferRequestNo` |
|
|
|
|
|
|
|
|
|
|
|
|
重试建议:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
int maxRetry = 3;
|
|
|
|
|
|
for (int i = 0; i < maxRetry; i++) {
|
|
|
|
|
|
try {
|
|
|
|
|
|
return wh.outbound().create(cmd);
|
|
|
|
|
|
} catch (WarehouseException e) {
|
|
|
|
|
|
if (!e.retryable() || i == maxRetry - 1) throw e;
|
|
|
|
|
|
Thread.sleep(1000L << i); // 1s / 2s / 4s
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 附录 A:日志
|
|
|
|
|
|
|
|
|
|
|
|
配了 `Slf4jCallObserver` 后每次调用打一行:
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
sdk-call at=2026-11-17 10:00:00 op=warehouse.outbound.create provider=EDAYUN
|
|
|
|
|
|
requestId=xxx cost=812ms result=-1 failed=0 code=200 params={omsSku=SKU-001}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
失败时多带 `retryable` / `platformCode` / `error`。日志**不含凭据与完整报文**。
|
|
|
|
|
|
|
|
|
|
|
|
## 附录 B:枚举速查
|
|
|
|
|
|
|
|
|
|
|
|
| 枚举 | 取值 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `Platform` | `AMAZON_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `ALIEXPRESS` `TARGET` `BESTBUY` `WAYFAIR` `CUSTOM` |
|
|
|
|
|
|
| `LabelMode` | `WAREHOUSE_LABEL` / `PLATFORM_LABEL` |
|
|
|
|
|
|
| `CancelEligibility` | `FREE` / `CHARGED` / `BLOCKED` |
|
|
|
|
|
|
| `ReturnDealMethod` | `CUSTOMER_PICKUP` / `PHOTO_CONFIRM` / `DESTROY` / `WAREHOUSE_CONFIRM` |
|
|
|
|
|
|
| `ReturnStatus` | `DRAFT` / `PENDING_REVIEW` / `REJECTED` / `RETURNING` / `PENDING_RECEIPT` / `COMPLETED` / `CLOSED` / `UNKNOWN` |
|
|
|
|
|
|
| `WarehouseFeeType` | `OPERATION` / `STORAGE` / `VALUE_ADDED` / `LAST_MILE` |
|
|
|
|
|
|
| `InventorySyncStrategy` | `TIME_WINDOW` / `FULL_PULL_DIFF` |
|
|
|
|
|
|
| `AddressType` | `BUSINESS` / `RESIDENTIAL` / `MIXED` / `UNKNOWN` |
|
|
|
|
|
|
| `CaseMarkPaperSize` | `SIZE_70_30` / `SIZE_100_60` / `SIZE_100_150` / `SIZE_60_40` |
|
|
|
|
|
|
|
|
|
|
|
|
## 附录 C:各仓接口细节
|
|
|
|
|
|
|
|
|
|
|
|
文档与真机的差异、码表、已知问题都在源码的 `docs-warehouse/` 目录:
|
|
|
|
|
|
|
|
|
|
|
|
- `docs-warehouse/edayun/README.md`、`docs-warehouse/edayun/TODO.md`
|
|
|
|
|
|
- `docs-warehouse/yqn/README.md`
|
|
|
|
|
|
- `docs-warehouse/hengjian/README.md`
|
|
|
|
|
|
- `docs-warehouse/architecture.md`(分层与能力位设计)
|
|
|
|
|
|
|
|
|
|
|
|
字段的完整语义在每个模型的 javadoc 里(IDE 里 Ctrl+点击看)。
|