# 三方仓 SDK 操作手册(业务开发版) > 面向 OMS 业务开发:**你要做的事怎么做**。 > 不需要了解 SDK 内部分层,照着抄就能跑。 > > 版本 1.0.0-SNAPSHOT · JDK 1.8 --- ## 快速导航 | 我要… | 看这节 | |---|---| | 把 SDK 跑起来 | [一、5 分钟上手](#一5-分钟上手) | | 知道某个仓支不支持我要的功能 | [二、我要做的事能不能做](#二我要做的事能不能做) | | 发货 / 打面单 | [3.1](#31-发货建出库单--拿面单) | | 查包裹到哪了 | [3.2](#32-查物流轨迹) | | 取消订单 | [3.3](#33-取消出库单) | | 处理买家退货 | [3.4](#34-退货) | | 同步库存 | [3.5](#35-库存同步) | | 建商品 / 查商品 | [3.6](#36-商品主数据) | | 拉费用对账 | [3.7](#37-对账拉费用明细) | | 打箱唛 / 提货单 | [3.8](#38-打单箱唛--bol) | | 单位 / SKU / 分页 / 金额怎么传 | [四、贯穿全局的规则](#四几条贯穿全局的规则) | | 报错了 / 要不要重试 | [五、出错了怎么办](#五出错了怎么办) | --- # 一、5 分钟上手 ## 1.1 引入依赖 ```xml ecommerce warehouse-sdk-core 1.0.0-SNAPSHOT ecommerce warehouse-sdk-edayun 1.0.0-SNAPSHOT ecommerce warehouse-sdk-yqn 1.0.0-SNAPSHOT ecommerce warehouse-sdk-xincang 1.0.0-SNAPSHOT ecommerce warehouse-sdk-hengjian 1.0.0-SNAPSHOT ``` 需要 **JDK 1.8**。日志实现(logback / log4j2)宿主要自己提供。 ## 1.2 一次性配置 **这一步整个应用只做一次**,之后复用这个 `sdk`。 ### 你只需要实现两个东西 **① 告诉 SDK「仓编码对应哪家仓」** ```java import common.ecommerce.warehouse.spi.WarehouseRepository; import common.ecommerce.warehouse.spi.WarehouseAccount; import java.util.*; public class MyWarehouseRepository implements WarehouseRepository { private final Map 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 findByWarehouseCode(String warehouseCode) { WarehouseAccount a = accounts.get(warehouseCode); return a == null ? Collections.emptyList() : Collections.singletonList(a); } @Override public Optional 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)。 ```java 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 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 ```java 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 **不保存**端点和凭据,每次调用由你传: ```java 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 拿到一个仓的操作入口 **所有业务接口都从这里进**: ```java import common.ecommerce.warehouse.sdk.WarehouseOperations; WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); ``` 后面所有示例里的 `wh` 都是这行拿到的。 ## 1.4 验证能跑通 在正式写业务前,先跑这一行——**只读,不改任何数据**: ```java import common.ecommerce.warehouse.model.WarehouseFacility; import java.util.List; List 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](#13-拿到一个仓的操作入口))。 > 所有代码都是**片段**,省略了 import 与 try-catch,完整写法见 [五](#五出错了怎么办)。 ## 3.1 发货:建出库单 → 拿面单 ### 第一步:建单 ```java 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(); // 仓侧单号,**保存下来**,后续查单/取消要用 ``` ### 第二步:拿面单 ```java List 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 查物流轨迹 ```java // 只要节点 List 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 取消出库单 ### 先问仓方能不能取消 ```java import common.ecommerce.warehouse.enums.CancelEligibility; CancelEligibility e = wh.outbound().checkCancel( OutboundRef.ofRequestNo("OB-20261117-001")); // FREE 可以免费取消 // CHARGED 取消要收钱 // BLOCKED 不能取消(已发货 / 已取消) ``` ### 再决定要不要取消 ```java 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 退货 ### 建退货单 ```java 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`——传了会直接报错。 ### 查退货进度 ```java WarehouseReturn detail = wh.returns().get("RMA2411053149"); // 仓侧 RMA 号 detail.status(); // DRAFT / RETURNING / PENDING_RECEIPT / COMPLETED / CLOSED ... detail.rawStatus(); // 仓方原文,排查时看这个 detail.lines(); // 明细:SKU / 数量 / 检验结果 ``` ### 分页查退货单 ```java Page 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()); ``` ### 取消退货单 ```java boolean ok = wh.returns().cancel("RMA2411053149"); ``` > 传的是**仓侧 RMA 号**,不是我们的单号。 > 仓方拒绝时**抛异常**,不返回 false。 --- ## 3.5 库存同步 ### 单次查询 ```java import common.ecommerce.warehouse.model.InventoryQuery; Page 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(); // 冻结 } ``` ### 全量同步怎么做 ```java // 先问这家仓支不支持增量 InventorySyncStrategy strategy = wh.inventorySyncStrategy(); // TIME_WINDOW 可以按 updatedAfter 增量 // FULL_PULL_DIFF 只能全量拉再自己比对 ``` ```java // 全量翻页模板 String cursor = null; do { Page 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 商品主数据 ### 建档 ```java 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` | > 不知道传哪个?**看目标仓是哪家,按那一列的要求传。** ### 查询 ```java Page 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 对账:拉费用明细 三个方法,看你要什么: ```java // ① 账户流水(充值 / 扣费 / 退费 + 余额) List 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 costs = wh.fees().orderCosts(FeeQuery.builder() .saleOrderNo("SO-20261117-001") .build()); // ③ 仓租(按 SKU + 计费日) List rents = wh.fees().storageRents(FeeQuery.builder() .settledAfter(Instant.parse("2026-10-01T00:00:00Z")) .settledBefore(Instant.parse("2026-10-31T00:00:00Z")) .build()); ``` **你会拿到什么** ```java d.documentNo(); // 单据号 d.feeName(); // 计费项名,如「尾程-燃油附加费」 d.feeType(); // OPERATION / STORAGE / VALUE_ADDED / LAST_MILE d.amount(); // Money(金额 + 币种) d.settledAt(); // 计费时间 d.estimated(); // true 预估 / false 实际 ``` ### 发货前算运费 ```java List 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 ### 箱唛(外箱标) ```java 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(提货单 / 签收凭证) ```java List 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`: ```java String cursor = null; do { Page 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 ```java Money.of("19.99", "USD") // ✅ 19.99 // ❌ ``` 裸 `double` 会丢币种,对账时美元和加元混在一起就完了。所有金额字段都是 `Money`,带 `amount()` 和 `currencyCode()`。 --- # 五、出错了怎么办 ## 5.1 五类异常 ```java 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 异常里有什么 ```java 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](#12-一次性配置) | | `该仓没有配置接入账户` | `warehouseCode` 对不上 | 检查 `WarehouseRepository` | | `WarehouseUnsupportedCapabilityException` | 这家仓没这个接口 | 看 [二](#二我要做的事能不能做) 的表 | | `http 401` / token 相关 | 凭据错 | 检查 `ChannelSecret` 的字段 | | `SKU 不存在` / 查不到数据 | SKU 用了 OMS 的而不是仓侧的 | 见 [4.2](#42-sku到底传哪一个最容易错) | | `查询无数据` | 时间窗不对(如易达云只查最近一月) | 显式给 `createdAfter/Before` | | `参数不能为空` | 必填字段漏了 | 看对应任务的「必填」段 | ## 5.4 幂等:重复调用安全吗 **写操作都安全**,同样的单号调两次不会重复下单: | 操作 | 幂等键 | |---|---| | 建出库单 | 仓编码 + `outboundRequestNo`(或 `orderRef`) | | 建入库单 | 仓编码 + `inboundRequestNo` | | 建退货单 | 仓编码 + `returnRequestNo` | | 取消退货单 | 仓编码 + 仓侧 RMA 号 | | 建调拨单 | 仓编码 + `transferRequestNo` | **重试策略建议**: ```java 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 里: ```java 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`(分层与能力位设计)