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.

24 KiB

三方仓 SDK 使用说明(源码集成版)

源码已随交付提供,直接在本项目里使用即可。

JDK 1.8;需要 jackson-databind 2.13.5、slf4j-api 1.7.36、okhttp 4.12.0 (或自己实现 HttpTransport 替换 OkHttp)。

想用 jar 引入的话,看同目录的 SDK使用说明-Jar引入.md。


快速导航

我要… 看这节
配好 SPI / SDK / 连接 一、配置
确认能跑通 二、快速上手
知道某仓支不支持某功能 三、我要做的事能不能做
发货 / 面单 4.1
查轨迹 / 取消订单 4.2 · 4.3
退货 / 库存 / 商品 / 对账 4.4 · 4.5 · 4.6 · 4.7
打箱唛 / BOL 4.8
单位 / SKU / 分页 / 金额 五、贯穿全局的规则
报错 / 重试 六、出错了怎么办

一、配置

1.1 实现两个 SPI

① 仓编码 → 哪家仓

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

providerWarehouseId 各仓填什么

仓 填什么 例子
易达云 数字仓 id "2"
运去哪 仓编码 "RF_NY_US"
信仓 仓编码
恒健 仓编码

② 写操作怎么防重复

只要你们有建单 / 取消这类写操作就必须实现。核心是**「查 + 写」必须原子**。

下面代码里的 loadFromRedisOrDb / reclaimable / writeInProgress / markStatus 是示意方法名,按你们自己的存储实现。 结构可以照抄 sdk-testkit/InMemoryIdempotencyStore(如果拷了的话)。

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

        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 用唯一索引
  2. complete / fail 只能由当前 owner 写,否则过期 owner 会覆盖新抢占者的结果

只做查询可以先不实现;一旦建单会抛 IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations。

1.2 组装 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);前两个可传 null(则每次重登)
YqnAdapterFactory (Clock)
XincangAdapterFactory (TokenStore, LockProvider, Clock)
HengjianAdapterFactory 无参

务必做成单例。 适配器里缓存了 token 与限流器,每次 new 会重复登录。

1.3 连接信息(端点 + 凭据)

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 算签名

二、快速上手

2.1 拿到仓的操作入口

import common.ecommerce.warehouse.sdk.WarehouseOperations;

WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);

后面所有 wh.xxx() 都从这个对象出发。

2.2 验证能跑通

只读,不改任何数据:

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

能打出仓,说明凭据、端点、配置全对。跑不通时:

现象 原因
该仓没有配置接入账户 warehouseCode 和 WarehouseRepository 对不上
WarehouseUnsupportedCapabilityException 该仓没有仓库清单接口(看 五)
http 401 / token 错误 ChannelSecret 字段填错
超时 端点不通;易达云首次调用慢,重试一次


三、我要做的事能不能做?

业务动作 方法 易达云 运去哪 信仓 恒健
建出库单 / 打面单 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 已就绪(见 2.1)。代码为片段,省略 import 与 try-catch。

4.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")       // ⚠️ 易达云要全称、运去哪要 CA
                .city("Escondido")
                .addressLine1("1308 E Washington Ave")
                .postalCode("92027")
                .build())
        .line(OutboundLine.builder()
                .lineNo("1")
                .omsSku("SKU-001")
                .providerSku("AP0000X9US0010601")    // ⚠️ 见 6.2 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();
}

⚠️ 坑

  1. 州名:易达云要 California,运去哪要 CA
  2. 平台面单把 labelMode 设为 PLATFORM_LABEL;易达云要文件 URL 不是 base64
  3. 重复建单不会重复下单(幂等键 = orderRef,没有则 outboundRequestNo)
  4. 保存 providerOrderId,后续查单 / 取消能少一次请求

4.2 查物流轨迹

List<TrackEvent> events = wh.track("1Z999AA10123456784");

TrackingInfo info = wh.trackShipment("1Z999AA10123456784");
info.firstOnlineAt();   // 上网时间(为空 = 物流还没启动)
info.deliveredAt();     // 妥投时间(为空 = 未签收)
info.signedBy();        // 签收人(未签收 = null)
info.events();

⚠️ 坑:查不到不报错 —— track() 返回空列表、trackShipment() 返回 null。

4.3 取消出库单

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)
            .build());
    r.cancelled();
}

⚠️ 坑:CHARGED + acceptCharge(false) 抛 OutboundCancelChargeRequiredException; BLOCKED 抛 OutboundCancelBlockedException。

4.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")
        .build());

r.providerReturnId();   // 仓侧 RMA 号,**保存下来**

查进度 / 取消:

WarehouseReturn detail = wh.returns().get("RMA2411053149");
detail.status();       // 统一状态
detail.rawStatus();    // 仓方原文
detail.lines();

boolean ok = wh.returns().cancel("RMA2411053149");   // 传仓侧 RMA 号

⚠️ 坑:易达云只支持「自行退回」,且拒绝 lineName / estimatedReceiveDate / returnReason(传了直接报错)。

4.5 库存同步

Page<InventorySnapshot> page = wh.inventory().query(
        InventoryQuery.builder()
                .sku("AP0000X9US0010601")
                .includeZeroStock(true)
                .pageSize(500)
                .build());

for (InventorySnapshot s : page.items()) {
    s.available(); s.onHand(); s.inTransit(); s.reserved();
}

// 先问支不支持增量
InventorySyncStrategy strategy = wh.inventorySyncStrategy();
// TIME_WINDOW 可按 updatedAfter 增量 / FULL_PULL_DIFF 只能全量拉再比对

⚠️ 坑

  • -1 是「仓方没给」不是 0(pendingOutbound / alertQuantity 常为 null → 映射成 -1)
  • 易达云没有时间维度,updatedAfter 不生效

4.6 商品主数据

WarehouseProduct p = WarehouseProduct.builder()
        .omsSku("SKU-001")
        .name("蓝牙音箱")
        .lengthCm(12).widthCm(10).heightCm(8)
        .weightGrams(500)
        .providerSku("AP0000X9US0010601")
        .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").build());

⚠️ 坑

  • 易达云是「创建」不是 upsert,同 SKU 重复建档会报错
  • 易达云不带时间窗只查最近一个月
  • 运去哪不支持条码 / 时间窗过滤,传了本地报错

4.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"))
        .build());

// ② 按订单拆的费用
List<BillingDocument> costs = wh.fees().orderCosts(FeeQuery.builder()
        .saleOrderNo("SO-20261117-001").build());

// ③ 仓租
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());

// 发货前算运费
List<FeeEstimateResult> quotes = wh.fees().estimate(FeeEstimateQuery.builder()
        .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
        .receiveCountry("US").receivePostal("91761")
        .logisticsServiceCode("80")
        .build());

单据字段:documentNo() / feeName() / feeType() / amount() / settledAt() / estimated()

⚠️ 坑:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。

4.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

枚举按实测尺寸命名。仓方文档标的与实际印出来的对不上,以枚举名为准。

BOL(提货单 / 签收凭证):

List<BolDocument> bols = wh.orderBols("FBA473182144");
b.fileUrl();      // BOL 文件
b.podFileUrl();   // 签收凭证
b.statusName();   // 如「已妥投」

五、几条贯穿全局的规则

5.1 单位:尺寸 cm、重量 g

字段名带 Cm / Grams 后缀。不要自己换算——易达云内部要 kg,适配器会转。

5.2 SKU:到底传哪一个(最容易错)

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

建档时:providerSku 有值 → 仓方存它
                  没值 → 仓方存 omsSku
                    ↓
之后:查商品 / 下单 / 查库存 都用同一串
建档时 仓方存的 之后必须传
传了 providerSku(如 AP0000X9US0010601) 它 它(≠ OMS SKU)
没传 omsSku omsSku

SDK 不做 OMS→仓侧 SKU 转换(映射表在你们手里)。传错不报错,只会查不到。

5.3 分页

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() 猜

5.4 金额

一律 Money.of("19.99", "USD"),不要传裸 double——会丢币种,对账时美元和加元混在一起就完了。


六、出错了怎么办

6.1 五类异常

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 不能取消 ❌

6.2 异常里有什么

catch (WarehouseException e) {
    e.operation();          // "warehouse.outbound.create"
    e.warehouseCode();      // 哪个仓
    e.requestId();          // 我们的链路 ID
    e.platformCode();       // 仓方业务码
    e.platformRequestId();  // 仓方链路 ID,问仓方时给这个
    e.retryable();
    e.getMessage();
}

rawResponse() 有完整报文,可能含买家地址电话。别直接落日志。

6.3 常见报错对照

报错 原因 怎么办
requires an idempotencyStore 没配 见 1.1
该仓没有配置接入账户 仓编码对不上 检查 WarehouseRepository
WarehouseUnsupportedCapabilityException 该仓没这接口 看 五
http 401 / token 错误 凭据错 检查 ChannelSecret
SKU 不存在 / 查不到 用了 OMS SKU 而不是仓侧的 见 5.2
查询无数据 时间窗不对 显式给 createdAfter/Before

6.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。日志不含凭据与完整报文。

附录 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:各仓接口细节

文档与真机的差异、码表、已知问题都在源码的 docs-warehouse/ 目录:

  • docs-warehouse/edayun/README.md、docs-warehouse/edayun/TODO.md
  • docs-warehouse/yqn/README.md
  • docs-warehouse/hengjian/README.md
  • docs-warehouse/architecture.md(分层与能力位设计)

字段的完整语义在每个模型的 javadoc 里(IDE 里 Ctrl+点击看)。