# 三方仓 SDK 操作手册(业务开发版)
> 面向 OMS 业务开发:**你要做的事怎么做**。
> 不需要了解 SDK 内部分层,照着抄就能跑。
>
> 版本 1.0.0-SNAPSHOT · JDK 1.8
---
## 快速导航
| 我要… | 看这节 |
|---|---|
| 把 SDK 跑起来 | [一、5 分钟上手](#一5-分钟上手) |
| 知道某个仓支不支持我要的功能 | [二、我要做的事能不能做](#二我要做的事能不能做) |
| 发货 / 打面单 | [3.1](#31-发货建出库单--拿面单) |
| 查包裹到哪了 | [3.2](#32-查物流轨迹) |
| 取消订单 | [3.3](#33-取消出库单) |
| 处理买家退货 | [3.4](#34-退货) |
| 同步库存 | [3.5](#35-库存同步) |
| 建商品 / 查商品 | [3.6](#36-商品主数据) |
| 拉费用对账 | [3.7](#37-对账拉费用明细) |
| 打箱唛 / 提货单 | [3.8](#38-打单箱唛--bol) |
| 单位 / SKU / 分页 / 金额怎么传 | [四、贯穿全局的规则](#四几条贯穿全局的规则) |
| 报错了 / 要不要重试 | [五、出错了怎么办](#五出错了怎么办) |
---
# 一、5 分钟上手
## 1.1 引入依赖
```xml
ecommerce
warehouse-sdk-core
1.0.0-SNAPSHOT
ecommerce
warehouse-sdk-edayun
1.0.0-SNAPSHOT
ecommerce
warehouse-sdk-yqn
1.0.0-SNAPSHOT
ecommerce
warehouse-sdk-xincang
1.0.0-SNAPSHOT
ecommerce
warehouse-sdk-hengjian
1.0.0-SNAPSHOT
```
需要 **JDK 1.8**。日志实现(logback / log4j2)宿主要自己提供。
## 1.2 一次性配置
**这一步整个应用只做一次**,之后复用这个 `sdk`。
### 你只需要实现两个东西
**① 告诉 SDK「仓编码对应哪家仓」**
```java
import common.ecommerce.warehouse.spi.WarehouseRepository;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import java.util.*;
public class MyWarehouseRepository implements WarehouseRepository {
private final Map 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 findByWarehouseCode(String warehouseCode) {
WarehouseAccount a = accounts.get(warehouseCode);
return a == null ? Collections.emptyList()
: Collections.singletonList(a);
}
@Override
public Optional find(String warehouseCode, String provider) {
WarehouseAccount a = accounts.get(warehouseCode);
return a != null && a.provider().equals(provider) ? Optional.of(a) : Optional.empty();
}
}
```
**② 告诉 SDK「写操作怎么防重复」**
只要你有建单 / 取消这类写操作就必须实现。用 Redis 或 DB 都行,核心是**「查 + 写」必须原子**:
> 下面这段里的 `loadFromRedisOrDb` / `reclaimable` / `writeInProgress` /
> `markStatus` 是**示意方法名**,需要你按自己的存储实现。可参考
> `sdk-testkit` 里的 `InMemoryIdempotencyStore`(结构完全一样,只是把内存换成 Redis/DB)。
```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);
// 无记录 / 可重试失败 / IN_PROGRESS 已过 TTL → 可以抢占
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 get(String key) {
return Optional.ofNullable(loadFromRedisOrDb(key));
}
}
```
**必须满足的两条**
1. **`claim()` 的「查 + 写」要原子**。Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引 + `INSERT IGNORE`。先查再写会让并发穿透。
2. **`complete` / `fail` 只能由当前 owner 写**。否则过期的 owner 会覆盖新抢占者的结果。
> 只做查询的话可以暂时不实现;但一旦要建单就会抛
> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。
>
> **没有 Redis 可以先用内存版**(`InMemoryIdempotencyStore`,在 `sdk-testkit` 里),
> 但它只适合单实例测试,生产必须换成 Redis / DB。
### 组装 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)` |
| `YqnAdapterFactory` | `(Clock)` |
| `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` |
| `HengjianAdapterFactory` | 无参 |
> **务必做成单例。** 适配器里缓存了 token 和限流器,每次 `new` 会重复登录。
### 连接信息(端点 + 凭据)
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` | 算签名 |
## 1.3 拿到一个仓的操作入口
**所有业务接口都从这里进**:
```java
import common.ecommerce.warehouse.sdk.WarehouseOperations;
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
```
后面所有示例里的 `wh` 都是这行拿到的。
## 1.4 验证能跑通
在正式写业务前,先跑这一行——**只读,不改任何数据**:
```java
import common.ecommerce.warehouse.model.WarehouseFacility;
import java.util.List;
List warehouses = wh.warehouses();
System.out.println("该账户有权限的仓:" + warehouses.size());
for (WarehouseFacility w : warehouses) {
System.out.println(" " + w.warehouseCode() + " " + w.name() + " " + w.country());
}
```
能打出仓,说明**凭据、端点、配置全都对了**。
跑不通时的对照:
| 现象 | 原因 |
|---|---|
| `IllegalStateException: 该仓没有配置接入账户` | `warehouseCode` 和你的 `WarehouseRepository` 对不上 |
| `WarehouseUnsupportedCapabilityException` | 这家仓没有仓库清单接口(先看 [二](#二我要做的事能不能做)) |
| `WarehouseException ... http 401` | `appKey` / `appSecret` / `clientId` / `clientSecret` 有错 |
| 超时 | 端点不通;易达云首次调用较慢,建议重试一次 |
---
# 二、我要做的事能不能做?
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 |
|---|---|:---:|:---:|:---:|:---:|
| 建出库单 / 打面单 | `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` 已就绪(见 [1.3](#13-拿到一个仓的操作入口))。
> 所有代码都是**片段**,省略了 import 与 try-catch,完整写法见 [五](#五出错了怎么办)。
## 3.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") // ⚠️ 见下方坑 1
.city("Escondido")
.addressLine1("1308 E Washington Ave")
.postalCode("92027")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("SKU-001")
.providerSku("AP0000X9US0010601") // ⚠️ 见 [4.2 SKU](#42-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 pkgs = wh.outbound().packages(
OutboundRef.ofRequestNo("OB-20261117-001")); // 用我们自己的单号查
for (PackageResult p : pkgs) {
p.trackingNumber(); // 跟踪号
p.labelRef(); // 面单地址(URL)
p.carrier(); // 承运商
}
```
### 你会拿到什么
| 字段 | 用途 |
|---|---|
| `receipt.providerOrderId()` | 仓侧单号,落库 |
| `p.trackingNumber()` | 跟踪号,回填到订单 |
| `p.labelRef()` | 面单文件地址,用来打印 |
### ⚠️ 坑
1. **州名易达云要全称**(`California`),运去哪要二字码(`CA`)。
2. **平台面单**要把 `labelMode` 设成 `PLATFORM_LABEL`,且易达云要的是 **文件 URL 不是 base64**——传 base64 会本地报错。
3. **重复建单不会重复下单**:幂等键是 `orderRef`(没有则用 `outboundRequestNo`),同样的键再调一次会返回上次结果。
4. **保存 `providerOrderId`**,取消和查单时能少一次请求。
---
## 3.2 查物流轨迹
```java
// 只要节点
List events = wh.track("1Z999AA10123456784");
for (TrackEvent e : events) {
e.occurredAt(); // 时间
e.description(); // 如「上网」「已派送」
e.status(); // 仓方原值
}
// 要运单整体状态(推荐)
TrackingInfo info = wh.trackShipment("1Z999AA10123456784");
info.firstOnlineAt(); // 上网时间(承运商首次揽收)
info.deliveredAt(); // 妥投时间
info.carrier();
info.events(); // 节点列表
```
### 你会拿到什么
| 字段 | 含义 |
|---|---|
| `firstOnlineAt()` | **包裹到底有没有交给承运商** —— 为空说明物流还没启动 |
| `deliveredAt()` | 妥投时间,为空表示未签收 |
| `signedBy()` | 签收人;**未签收就是 null** |
### ⚠️ 坑
- **查不到不报错**:`track()` 返回空列表、`trackShipment()` 返回 `null`。这表示「还没轨迹」,不是失败。
- 易达云 PR 环境目前没有可查到的轨迹数据,接口通但返回空。
---
## 3.3 取消出库单
### 先问仓方能不能取消
```java
import common.ecommerce.warehouse.enums.CancelEligibility;
CancelEligibility e = wh.outbound().checkCancel(
OutboundRef.ofRequestNo("OB-20261117-001"));
// FREE 可以免费取消
// CHARGED 取消要收钱
// BLOCKED 不能取消(已发货 / 已取消)
```
### 再决定要不要取消
```java
if (e == CancelEligibility.FREE) {
CancelResult r = wh.outbound().cancel(CancelCommand.builder()
.outboundRequestNo("OB-20261117-001")
.providerOrderId("ORD123") // 有就一起给,定位更准
.acceptCharge(false) // 收费取消时传 false 会抛异常
.build());
r.cancelled(); // true = 取消成功
}
```
### ⚠️ 坑
- `CHARGED` 时如果 `acceptCharge=false`,抛 `OutboundCancelChargeRequiredException`——**先 catch 再跟用户确认**。
- `BLOCKED` 时抛 `OutboundCancelBlockedException`。
- 重复调用不会重复取消(幂等),可以放心重试。
---
## 3.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")
.remark("客户寄回")
.build());
r.providerReturnId(); // 仓侧 RMA 号,**保存下来**
```
**`ReturnDealMethod` 选哪个**
| 值 | 含义 |
|---|---|
| `WAREHOUSE_CONFIRM` | 仓库确认后处理(最常用) |
| `DESTROY` | 直接销毁 |
| `CUSTOMER_PICKUP` | 客户自提 |
| `PHOTO_CONFIRM` | 拍照确认后再定 |
> ⚠️ **易达云只支持「自行退回」**,且**拒绝** `lineName` / `estimatedReceiveDate` /
> `returnReason`——传了会直接报错。
### 查退货进度
```java
WarehouseReturn detail = wh.returns().get("RMA2411053149"); // 仓侧 RMA 号
detail.status(); // DRAFT / RETURNING / PENDING_RECEIPT / COMPLETED / CLOSED ...
detail.rawStatus(); // 仓方原文,排查时看这个
detail.lines(); // 明细:SKU / 数量 / 检验结果
```
### 分页查退货单
```java
Page page = wh.returns().query(ReturnQuery.builder()
.createdAfter(Instant.parse("2026-11-01T00:00:00Z"))
.createdBefore(Instant.parse("2026-11-18T00:00:00Z"))
.pageSize(100)
.build());
```
### 取消退货单
```java
boolean ok = wh.returns().cancel("RMA2411053149");
```
> 传的是**仓侧 RMA 号**,不是我们的单号。
> 仓方拒绝时**抛异常**,不返回 false。
---
## 3.5 库存同步
### 单次查询
```java
import common.ecommerce.warehouse.model.InventoryQuery;
Page page = wh.inventory().query(
InventoryQuery.builder()
.sku("AP0000X9US0010601") // 单个;多个用 .skus(list)
.warehouseCode("EDY-USLA")
.includeZeroStock(true) // 是否要零库存
.pageSize(500)
.build());
for (InventorySnapshot s : page.items()) {
s.providerSku();
s.available(); // 可用
s.onHand(); // 总库存
s.inTransit(); // 在途
s.reserved(); // 冻结
}
```
### 全量同步怎么做
```java
// 先问这家仓支不支持增量
InventorySyncStrategy strategy = wh.inventorySyncStrategy();
// TIME_WINDOW 可以按 updatedAfter 增量
// FULL_PULL_DIFF 只能全量拉再自己比对
```
```java
// 全量翻页模板
String cursor = null;
do {
Page p = wh.inventory().query(
InventoryQuery.builder().cursor(cursor).pageSize(500).build());
saveToDb(p.items());
cursor = p.nextCursor();
} while (cursor != null);
```
### ⚠️ 坑
- **`-1` 是「仓方没给」,不是 0**:`pendingOutbound` / `alertQuantity` 这类字段,仓方常返回 null,SDK 统一映射成 -1。展示时要区分。
- **易达云没有时间维度**,`updatedAfter` 不生效,只能全量。
- **零库存**:`includeZeroStock` 不传时由仓方默认(多数仓只返回 >0 的)。
---
## 3.6 商品主数据
### 建档
```java
WarehouseProduct p = WarehouseProduct.builder()
// ===== 必填 =====
.omsSku("SKU-001")
.name("蓝牙音箱")
.lengthCm(12).widthCm(10).heightCm(8)
.weightGrams(500)
// ===== 强烈建议 =====
.providerSku("AP0000X9US0010601") // ⚠️ 见 [4.2 SKU](#42-sku到底传哪一个最容易错)
.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 page = wh.queryProducts(
ProductQuery.builder()
.providerSku("AP0000X9US0010601") // 仓侧 SKU
.pageSize(100)
.build());
ProductInfo info = page.items().get(0);
info.lengthCm(); info.weightGrams(); // **实际值**,不是预报值
info.packedQuantity();
```
### ⚠️ 坑
- **易达云是「创建」不是「保存」**:同 SKU 重复建档会报错。运去哪才是 upsert。
- **易达云不带时间窗时只查最近一个月**,查老商品必须显式给 `createdAfter/Before`。
- **运去哪不支持条码和时间窗过滤**,传了会本地报错(不会静默忽略)。
---
## 3.7 对账:拉费用明细
三个方法,看你要什么:
```java
// ① 账户流水(充值 / 扣费 / 退费 + 余额)
List flows = wh.fees().settlements(FeeQuery.builder()
.settledAfter(Instant.parse("2026-10-01T00:00:00Z"))
.settledBefore(Instant.parse("2026-11-01T00:00:00Z"))
.pageSize(200)
.build());
// ② 按订单拆的费用(应收 / 折扣 / 实付 + 计费重)
List costs = wh.fees().orderCosts(FeeQuery.builder()
.saleOrderNo("SO-20261117-001")
.build());
// ③ 仓租(按 SKU + 计费日)
List rents = wh.fees().storageRents(FeeQuery.builder()
.settledAfter(Instant.parse("2026-10-01T00:00:00Z"))
.settledBefore(Instant.parse("2026-10-31T00:00:00Z"))
.build());
```
**你会拿到什么**
```java
d.documentNo(); // 单据号
d.feeName(); // 计费项名,如「尾程-燃油附加费」
d.feeType(); // OPERATION / STORAGE / VALUE_ADDED / LAST_MILE
d.amount(); // Money(金额 + 币种)
d.settledAt(); // 计费时间
d.estimated(); // true 预估 / false 实际
```
### 发货前算运费
```java
List quotes = wh.fees().estimate(FeeEstimateQuery.builder()
.lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
.receiveCountry("US").receivePostal("91761")
.logisticsServiceCode("80") // 指定渠道;空则返回所有渠道
.build());
for (FeeEstimateResult q : quotes) {
for (FeeEstimateResult.CarrierQuote c : q.carriers()) {
c.carrier(); // 渠道名
c.totalRate(); // 总价(Money)
c.costItems(); // 细分
}
}
```
### ⚠️ 坑
- **必须给成本类型或时间窗**,否则本地拒绝(防止拉全量把账户拉爆)。
- **易达云的「3 个月」时间窗阈值很怪**:同天数不同起点,结果可能一个通一个拒。超限时仓方返回明确错误,catch 后缩小窗口重试即可。
- **费用试算第一次常超时**,重试一次就好。
---
## 3.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 |
> ⚠️ **枚举是按实测尺寸命名的**。仓方文档标的和实际印出来的对不上(文档说第 2 档 6×4cm、第 3 档 A4,实际反过来),以枚举名为准。
### BOL(提货单 / 签收凭证)
```java
List bols = wh.orderBols("FBA473182144"); // EDA 平台仓订单号
for (BolDocument b : bols) {
b.bolCode();
b.fileUrl(); // BOL 文件
b.podFileUrl(); // 签收凭证 POD
b.statusName(); // 如「已妥投」
b.scheduledPickupQuantity();
}
```
---
# 四、几条贯穿全局的规则
## 4.1 单位:尺寸 cm、重量 g
| 项 | 单位 | 字段名 |
|---|---|---|
| 尺寸 | **cm** | 带 `Cm` 后缀 |
| 重量 | **g** | 带 `Grams` 后缀 |
**不要自己换算**——易达云内部要 kg,适配器会自己转。
## 4.2 SKU:到底传哪一个(最容易错)
**所有地方都用「建档时下发给仓方的那一串」。**
```
建档时:providerSku 有值 → 仓方存它
没值 → 仓方存 omsSku
↓
之后:查商品 / 下单 / 查库存 都用同一串
```
| 你建档时 | 仓方存的 | 之后必须传 |
|---|---|---|
| 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) |
| 没传 | `omsSku` | `omsSku` |
各仓字段名不同,但**值一样**:
| 场景 | 易达云字段 | 运去哪字段 |
|---|---|---|
| 建档 | `skuCode` | `sku` |
| 查商品 | `skuCode` | `skuList` |
| 下单 | `productSku` | `sku` |
| 查库存 | `skuCodeList` | `sku` |
> **SDK 不做 OMS→仓侧 SKU 转换**。映射表在你们手里。
> 传错不会报错,只会**查不到**——这是最难排查的坑之一。
## 4.3 分页:怎么翻页
每个查询都有 `pageSize` 和 `cursor`:
```java
String cursor = null;
do {
Page 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()` 去猜**
## 4.4 金额:为什么一定要用 Money
```java
Money.of("19.99", "USD") // ✅
19.99 // ❌
```
裸 `double` 会丢币种,对账时美元和加元混在一起就完了。所有金额字段都是 `Money`,带 `amount()` 和 `currencyCode()`。
---
# 五、出错了怎么办
## 5.1 五类异常
```java
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.shared.error.TransientException;
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` | 不能取消 | ❌ |
## 5.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()` 里有**完整原始报文**,可能含买家地址电话。
> **不要直接写进日志**,排查时临时看可以。
## 5.3 常见报错对照
| 报错 | 原因 | 怎么办 |
|---|---|---|
| `requires an idempotencyStore` | 没配 `IdempotencyStore` | 见 [1.2](#12-一次性配置) |
| `该仓没有配置接入账户` | `warehouseCode` 对不上 | 检查 `WarehouseRepository` |
| `WarehouseUnsupportedCapabilityException` | 这家仓没这个接口 | 看 [二](#二我要做的事能不能做) 的表 |
| `http 401` / token 相关 | 凭据错 | 检查 `ChannelSecret` 的字段 |
| `SKU 不存在` / 查不到数据 | SKU 用了 OMS 的而不是仓侧的 | 见 [4.2](#42-sku到底传哪一个最容易错) |
| `查询无数据` | 时间窗不对(如易达云只查最近一月) | 显式给 `createdAfter/Before` |
| `参数不能为空` | 必填字段漏了 | 看对应任务的「必填」段 |
## 5.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`:
```
sdk-call-failed at=... op=warehouse.outbound.create provider=EDAYUN
cost=200ms code=500 platformCode=500
error=WarehouseException: edayun outbound.create business error: ...
```
| 字段 | 含义 |
|---|---|
| `op` | 哪个操作 |
| `provider` | 哪家仓 |
| `requestId` | 我们的链路 ID |
| `cost` | 耗时 |
| `result` | 返回条数(-1 表示不适用) |
| `code` / `platformCode` | 业务码 / 仓方码 |
| `params` | 关键入参摘要(不含 PII) |
日志**不含凭据和完整报文**,可以放心长期保留。
---
## 附录 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:需要更细的字段说明?
本手册只覆盖**怎么用**。每个字段的完整语义在代码的 javadoc 里:
```java
OutboundCommand cmd = ...;
cmd.lines(); // IDE 里按住 Ctrl 点进去看注释
```
各仓的接口细节(文档与真机差异、码表、已知问题)在:
- `docs-warehouse/edayun/README.md`、`docs-warehouse/edayun/TODO.md`
- `docs-warehouse/yqn/README.md`
- `docs-warehouse/hengjian/README.md`
- `docs-warehouse/architecture.md`(分层与能力位设计)