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.

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));
    }
}

必须满足的两条

  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

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() 面单文件地址,用来打印

⚠️ 坑

  1. 州名易达云要全称(California),运去哪要二字码(CA)。
  2. 平台面单要把 labelMode 设成 PLATFORM_LABEL,且易达云要的是 文件 URL 不是 base64——传 base64 会本地报错。
  3. 重复建单不会重复下单:幂等键是 orderRef(没有则用 outboundRequestNo),同样的键再调一次会返回上次结果。
  4. 保存 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.md
  • docs-warehouse/yqn/README.md
  • docs-warehouse/hengjian/README.md
  • docs-warehouse/architecture.md(分层与能力位设计)