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() 做的事:
- 按
warehouseCode查WarehouseRepository→ 拿WarehouseAccount - 按
provider解析出适配器 - 组装
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,
并对仓方文案做去换行 + 截断(防日志注入)。日志不含凭据与报文。