33 KiB
三方仓 SDK 操作手册(业务开发版)
面向 OMS 业务开发:你要做的事怎么做。 不需要了解 SDK 内部分层,照着抄就能跑。
版本 1.0.0-SNAPSHOT · JDK 1.8
快速导航
| 我要… | 看这节 |
|---|---|
| 把 SDK 跑起来 | 一、5 分钟上手 |
| 知道某个仓支不支持我要的功能 | 二、我要做的事能不能做 |
| 发货 / 打面单 | 3.1 |
| 查包裹到哪了 | 3.2 |
| 取消订单 | 3.3 |
| 处理买家退货 | 3.4 |
| 同步库存 | 3.5 |
| 建商品 / 查商品 | 3.6 |
| 拉费用对账 | 3.7 |
| 打箱唛 / 提货单 | 3.8 |
| 单位 / SKU / 分页 / 金额怎么传 | 四、贯穿全局的规则 |
| 报错了 / 要不要重试 | 五、出错了怎么办 |
一、5 分钟上手
1.1 引入依赖
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-core</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<!-- 按需引入,用哪个仓加哪个 -->
<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>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-xincang</artifactId> <!-- 信仓 -->
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-hengjian</artifactId> <!-- 恒健 -->
<version>1.0.0-SNAPSHOT</version>
</dependency>
需要 JDK 1.8。日志实现(logback / log4j2)宿主要自己提供。
1.2 一次性配置
这一步整个应用只做一次,之后复用这个 sdk。
你只需要实现两个东西
① 告诉 SDK「仓编码对应哪家仓」
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();
}
}
② 告诉 SDK「写操作怎么防重复」
只要你有建单 / 取消这类写操作就必须实现。用 Redis 或 DB 都行,核心是**「查 + 写」必须原子**:
下面这段里的
loadFromRedisOrDb/reclaimable/writeInProgress/markStatus是示意方法名,需要你按自己的存储实现。可参考sdk-testkit里的InMemoryIdempotencyStore(结构完全一样,只是把内存换成 Redis/DB)。
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<IdempotencyRecord> get(String key) {
return Optional.ofNullable(loadFromRedisOrDb(key));
}
}
必须满足的两条
claim()的「查 + 写」要原子。Redis 用SET key value NX EX ttl,MySQL 用唯一索引 +INSERT IGNORE。先查再写会让并发穿透。complete/fail只能由当前 owner 写。否则过期的 owner 会覆盖新抢占者的结果。
只做查询的话可以暂时不实现;但一旦要建单就会抛
IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations。没有 Redis 可以先用内存版(
InMemoryIdempotencyStore,在sdk-testkit里), 但它只适合单实例测试,生产必须换成 Redis / DB。
组装 SDK
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 不保存端点和凭据,每次调用由你传:
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 拿到一个仓的操作入口
所有业务接口都从这里进:
import common.ecommerce.warehouse.sdk.WarehouseOperations;
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
后面所有示例里的 wh 都是这行拿到的。
1.4 验证能跑通
在正式写业务前,先跑这一行——只读,不改任何数据:
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() + " " + 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)。 所有代码都是片段,省略了 import 与 try-catch,完整写法见 五。
3.1 发货:建出库单 → 拿面单
第一步:建单
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(); // 仓侧单号,**保存下来**,后续查单/取消要用
第二步:拿面单
List<PackageResult> 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() |
面单文件地址,用来打印 |
⚠️ 坑
- 州名易达云要全称(
California),运去哪要二字码(CA)。 - 平台面单要把
labelMode设成PLATFORM_LABEL,且易达云要的是 文件 URL 不是 base64——传 base64 会本地报错。 - 重复建单不会重复下单:幂等键是
orderRef(没有则用outboundRequestNo),同样的键再调一次会返回上次结果。 - 保存
providerOrderId,取消和查单时能少一次请求。
3.2 查物流轨迹
// 只要节点
List<TrackEvent> 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 取消出库单
先问仓方能不能取消
import common.ecommerce.warehouse.enums.CancelEligibility;
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) // 收费取消时传 false 会抛异常
.build());
r.cancelled(); // true = 取消成功
}
⚠️ 坑
CHARGED时如果acceptCharge=false,抛OutboundCancelChargeRequiredException——先 catch 再跟用户确认。BLOCKED时抛OutboundCancelBlockedException。- 重复调用不会重复取消(幂等),可以放心重试。
3.4 退货
建退货单
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——传了会直接报错。
查退货进度
WarehouseReturn detail = wh.returns().get("RMA2411053149"); // 仓侧 RMA 号
detail.status(); // DRAFT / RETURNING / PENDING_RECEIPT / COMPLETED / CLOSED ...
detail.rawStatus(); // 仓方原文,排查时看这个
detail.lines(); // 明细:SKU / 数量 / 检验结果
分页查退货单
Page<WarehouseReturn> 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());
取消退货单
boolean ok = wh.returns().cancel("RMA2411053149");
传的是仓侧 RMA 号,不是我们的单号。 仓方拒绝时抛异常,不返回 false。
3.5 库存同步
单次查询
import common.ecommerce.warehouse.model.InventoryQuery;
Page<InventorySnapshot> 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(); // 冻结
}
全量同步怎么做
// 先问这家仓支不支持增量
InventorySyncStrategy strategy = wh.inventorySyncStrategy();
// TIME_WINDOW 可以按 updatedAfter 增量
// FULL_PULL_DIFF 只能全量拉再自己比对
// 全量翻页模板
String cursor = null;
do {
Page<InventorySnapshot> 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 商品主数据
建档
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 |
不知道传哪个?看目标仓是哪家,按那一列的要求传。
查询
Page<ProductInfo> 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 对账:拉费用明细
三个方法,看你要什么:
// ① 账户流水(充值 / 扣费 / 退费 + 余额)
List<BillingDocument> 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<BillingDocument> costs = wh.fees().orderCosts(FeeQuery.builder()
.saleOrderNo("SO-20261117-001")
.build());
// ③ 仓租(按 SKU + 计费日)
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());
你会拿到什么
d.documentNo(); // 单据号
d.feeName(); // 计费项名,如「尾程-燃油附加费」
d.feeType(); // OPERATION / STORAGE / VALUE_ADDED / LAST_MILE
d.amount(); // Money(金额 + 币种)
d.settledAt(); // 计费时间
d.estimated(); // true 预估 / false 实际
发货前算运费
List<FeeEstimateResult> 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
箱唛(外箱标)
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(提货单 / 签收凭证)
List<BolDocument> 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:
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()去猜
4.4 金额:为什么一定要用 Money
Money.of("19.99", "USD") // ✅
19.99 // ❌
裸 double 会丢币种,对账时美元和加元混在一起就完了。所有金额字段都是 Money,带 amount() 和 currencyCode()。
五、出错了怎么办
5.1 五类异常
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 异常里有什么
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 |
该仓没有配置接入账户 |
warehouseCode 对不上 |
检查 WarehouseRepository |
WarehouseUnsupportedCapabilityException |
这家仓没这个接口 | 看 二 的表 |
http 401 / token 相关 |
凭据错 | 检查 ChannelSecret 的字段 |
SKU 不存在 / 查不到数据 |
SKU 用了 OMS 的而不是仓侧的 | 见 4.2 |
查询无数据 |
时间窗不对(如易达云只查最近一月) | 显式给 createdAfter/Before |
参数不能为空 |
必填字段漏了 | 看对应任务的「必填」段 |
5.4 幂等:重复调用安全吗
写操作都安全,同样的单号调两次不会重复下单:
| 操作 | 幂等键 |
|---|---|
| 建出库单 | 仓编码 + outboundRequestNo(或 orderRef) |
| 建入库单 | 仓编码 + inboundRequestNo |
| 建退货单 | 仓编码 + returnRequestNo |
| 取消退货单 | 仓编码 + 仓侧 RMA 号 |
| 建调拨单 | 仓编码 + transferRequestNo |
重试策略建议:
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 里:
OutboundCommand cmd = ...;
cmd.lines(); // IDE 里按住 Ctrl 点进去看注释
各仓的接口细节(文档与真机差异、码表、已知问题)在:
docs-warehouse/edayun/README.md、docs-warehouse/edayun/TODO.mddocs-warehouse/yqn/README.mddocs-warehouse/hengjian/README.mddocs-warehouse/architecture.md(分层与能力位设计)