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.

34 KiB

三方仓 SDK 操作手册

快速索引:从零开始看 一;查某个入参/出参看 二;要调某个能力看 三; 出问题先看 五、常见坑速查。

面向宿主(OMS)开发。所有示例基于 warehouse-sdk-core + 各仓适配器。 版本:1.0.0-SNAPSHOT · JDK 1.8


目录


一、SDK 怎么创建

1.1 依赖

<!-- 门面 + 统一模型 -->
<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(必需)

public interface WarehouseRepository {
    /** 按 OMS 仓编码取全部接入账户。 */
    List<WarehouseAccount> findByWarehouseCode(String warehouseCode);

    /** 按仓编码 + provider 取单个账户。 */
    Optional<WarehouseAccount> find(String warehouseCode, String provider);
}

WarehouseAccount(仓主数据)

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(写操作必需)

WarehouseSdk.builder()
        .idempotencyStore(myRedisOrDbImpl)   // 不注入则写操作直接抛异常
        .build();

没注入时调 outbound().create(...)、returns().create(...) 等会抛 IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations")。

CallObserver(可选,强烈建议)

.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))

每次门面调用结束回调一次,成功打 INFO、失败打 WARN。不注入时是空实现。

TokenStore / LockProvider(可选)

易达云、信仓需要换 token,注入后按 appKey + clientId 缓存;不注入则每次调用都重新登录。

1.3 构建门面

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 不保存端点、不读环境变量。 每次调用都要由宿主传入。

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 取某个仓的操作视图

// 每次都传连接信息(端点与凭据随调用走,SDK 不缓存)
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);

warehouses() 做的事:

  1. 按 warehouseCode 查 WarehouseRepository → 拿 WarehouseAccount
  2. 按 provider 解析出适配器
  3. 组装 WarehouseContext(仓编码、provider、仓方 id、连接、requestId、clock)

拿不到账户时抛 IllegalStateException。

查能力位(不触发真实请求)

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 口径(最容易错的地方)

所有环节都用「建档时下发给仓方的那串」。

// 建档时
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 的转换:映射表在宿主手里。传错不报错,只会查不到。

金额

Money.of("19.99", "USD")    // 字符串构造,保留精度
Money.zero("USD")
money.add(other) / subtract / multiply / round()

2.2 分页入参 / 出参 Page<T>

入参(每个 Query 都有)

.pageSize(100)      // 单页条数;各仓有上限,适配器会截断
.cursor(null)       // 第一页传 null

出参

Page<ProductInfo> page = ...;

page.items();        // List<T>,不可变
page.size();
page.hasMore();      // 由 nextCursor 推导,不要从 items 数量猜
page.nextCursor();   // null = 没有下一页

翻页模板

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

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

receipt.outboundRequestNo();   // 回显我们传入的单号
receipt.providerOrderId();     // 仓侧单号(幂等重试时靠它定位)
receipt.rawStatus();           // 仓方原文

2.4 库存入参 InventoryQuery

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>

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。

同步策略

wh.inventorySyncStrategy();   // TIME_WINDOW / FULL_PULL_DIFF

FULL_PULL_DIFF 表示没有时间维度,updatedAfter 不生效,必须全量拉再 diff。

2.5 入库入参 InboundCommand

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(创建)

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(查询)

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

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(已发生的账单)

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>

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(发货前报价)

FeeEstimateQuery.builder()
        .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
        .receiveCountry("US").receivePostal("91761").receiveCity("...")
        .warehouseCode("EDY-USLA")
        .logisticsServiceCode("80")        // 指定渠道;空则返回全部
        .build();

出参 List<FeeEstimateResult>

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(查询)

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 商品

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 出库

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 库存

// 策略
InventorySyncStrategy s = wh.inventorySyncStrategy();

// 查询
Page<InventorySnapshot> page = wh.inventory().query(
        InventoryQuery.builder().sku("SKU").pageSize(100).build());

3.5 入库

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 退货

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 费用

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 基础资料(仓库 / 承运商 / 物流产品)

// 仓库(只返回有权限的)
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 / 轨迹 / 箱唛)

// 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 调拨 / 销毁 / 物流异动

// 调拨(写)
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)

取值

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 才跑,不会误连生产

附:日志

.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, 并对仓方文案做去换行 + 截断(防日志注入)。日志不含凭据与报文。