diff --git a/docs-warehouse/SDK操作手册.md b/docs-warehouse/SDK操作手册.md index ea08ac1..618efd3 100644 --- a/docs-warehouse/SDK操作手册.md +++ b/docs-warehouse/SDK操作手册.md @@ -1,160 +1,209 @@ -# 三方仓 SDK 操作手册 +# 三方仓 SDK 操作手册(业务开发版) -> 快速索引:从零开始看 **一**;查某个入参/出参看 **二**;要调某个能力看 **三**; -> 出问题先看 **五、常见坑速查**。 - -> 面向宿主(OMS)开发。所有示例基于 `warehouse-sdk-core` + 各仓适配器。 -> 版本:1.0.0-SNAPSHOT · JDK 1.8 +> 面向 OMS 业务开发:**你要做的事怎么做**。 +> 不需要了解 SDK 内部分层,照着抄就能跑。 +> +> 版本 1.0.0-SNAPSHOT · JDK 1.8 --- -## 目录 - -- [一、SDK 怎么创建](#一sdk-怎么创建) - - [1.1 依赖](#11-依赖) - - [1.2 宿主必须先实现的 SPI](#12-宿主必须先实现的-spi) - - [1.3 构建门面](#13-构建门面) - - [1.4 连接信息(端点 + 凭据)](#14-连接信息端点--凭据) - - [1.5 取某个仓的操作视图](#15-取某个仓的操作视图) -- [二、入参怎么传、出参怎么取](#二入参怎么传出参怎么取) - - [2.1 通用约定(单位、时间、SKU、金额)](#21-通用约定单位时间sku金额) - - [2.2 分页入参 / 出参 `Page`](#22-分页入参--出参-paget) - - [2.3 出库入参 `OutboundCommand`](#23-出库入参-outboundcommand) - - [2.4 库存入参 `InventoryQuery`](#24-库存入参-inventoryquery) - - [2.5 入库入参 `InboundCommand`](#25-入库入参-inboundcommand) - - [2.6 退货入参 `ReturnCommand` / `ReturnQuery`](#26-退货入参-returncommand--returnquery) - - [2.7 费用入参 `FeeQuery` / `FeeEstimateQuery`](#27-费用入参-feequery--feeestimatequery) - - [2.8 商品入参 `WarehouseProduct` / `ProductQuery`](#28-商品入参-warehouseproduct--productquery) - - [2.9 出参速查表](#29-出参速查表) -- [三、各能力怎么调用](#三各能力怎么调用) - - [3.0 视图结构](#30-视图结构) - - [3.1 能力矩阵](#31-能力矩阵) - - [3.2 商品](#32-商品) - - [3.3 出库](#33-出库) - - [3.4 库存](#34-库存) - - [3.5 入库](#35-入库) - - [3.6 退货](#36-退货) - - [3.7 费用](#37-费用) - - [3.8 基础资料(仓库 / 承运商 / 物流产品)](#38-基础资料仓库--承运商--物流产品) - - [3.9 单据与打印(BOL / 轨迹 / 箱唛)](#39-单据与打印bol--轨迹--箱唛) - - [3.10 调拨 / 销毁 / 物流异动](#310-调拨--销毁--物流异动) -- [四、异常与重试](#四异常与重试) -- [五、常见坑速查](#五常见坑速查) +## 快速导航 + +| 我要… | 看这节 | +|---|---| +| 把 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 / 分页 / 金额怎么传 | [四、贯穿全局的规则](#四几条贯穿全局的规则) | +| 报错了 / 要不要重试 | [五、出错了怎么办](#五出错了怎么办) | --- -# 一、SDK 怎么创建 +# 一、5 分钟上手 -## 1.1 依赖 +## 1.1 引入依赖 ```xml - ecommerce warehouse-sdk-core 1.0.0-SNAPSHOT - + + + ecommerce + warehouse-sdk-edayun + 1.0.0-SNAPSHOT + ecommerce - warehouse-sdk-edayun + warehouse-sdk-yqn 1.0.0-SNAPSHOT ecommerce - warehouse-sdk-yqn + warehouse-sdk-xincang + 1.0.0-SNAPSHOT + + + ecommerce + warehouse-sdk-hengjian 1.0.0-SNAPSHOT ``` -要求 **JDK 1.8**。SDK 不引入日志实现,宿主自己提供 `slf4j` 绑定。 +需要 **JDK 1.8**。日志实现(logback / log4j2)宿主要自己提供。 -## 1.2 宿主必须先实现的 SPI +## 1.2 一次性配置 -SDK 是纯库:**不读数据库、不读配置、不启定时器、不监听端口**。以下由宿主提供。 - -### `WarehouseRepository`(必需) - -```java -public interface WarehouseRepository { - /** 按 OMS 仓编码取全部接入账户。 */ - List findByWarehouseCode(String warehouseCode); +**这一步整个应用只做一次**,之后复用这个 `sdk`。 - /** 按仓编码 + provider 取单个账户。 */ - Optional find(String warehouseCode, String provider); -} -``` +### 你只需要实现两个东西 -### `WarehouseAccount`(仓主数据) +**① 告诉 SDK「仓编码对应哪家仓」** ```java -WarehouseAccount.builder() - .warehouseCode("EDY-USLA") // OMS 侧仓编码 - .provider("EDAYUN") // 决定用哪个适配器 - .providerWarehouseId("2") // 仓方仓 id(数字) - .credentialRef("kms://edayun") // 只是标识,SDK 不会去取密钥 - .timeZone("America/Los_Angeles") - .build(); -``` +import common.ecommerce.warehouse.spi.WarehouseRepository; +import common.ecommerce.warehouse.spi.WarehouseAccount; +import java.util.*; -| 字段 | 作用 | 易达云 | 运去哪 | 信仓 | 恒健 | -|---|---|---|---|---|---| -| `warehouseCode` | OMS 仓编码,所有调用的入参 | ✅ | ✅ | ✅ | ✅ | -| `provider` | 选适配器 | `EDAYUN` | `YQN` | `XINCANG` | `HENGJIAN` | -| `providerWarehouseId` | 仓方仓 id/编码 | 数字 id(`"2"`) | 仓编码(`"RF_NY_US"`) | 仓编码 | 仓编码 | -| `timeZone` | 时间窗解释 | 用 | 用 | 用 | 用 | +public class MyWarehouseRepository implements WarehouseRepository { -### `IdempotencyStore`(写操作必需) - -```java -WarehouseSdk.builder() - .idempotencyStore(myRedisOrDbImpl) // 不注入则写操作直接抛异常 - .build(); -``` + private final Map accounts = new HashMap<>(); -没注入时调 `outbound().create(...)`、`returns().create(...)` 等会抛 -`IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations")`。 + 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()); -### `CallObserver`(可选,强烈建议) + 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(); + } +} +``` -```java -.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) +**② 告诉 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)); + } +} ``` -每次门面调用结束回调一次,成功打 INFO、失败打 WARN。不注入时是空实现。 +**必须满足的两条** -### `TokenStore` / `LockProvider`(可选) +1. **`claim()` 的「查 + 写」要原子**。Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引 + `INSERT IGNORE`。先查再写会让并发穿透。 +2. **`complete` / `fail` 只能由当前 owner 写**。否则过期的 owner 会覆盖新抢占者的结果。 -易达云、信仓需要换 token,注入后按 `appKey + clientId` 缓存;不注入则每次调用都重新登录。 +> 只做查询的话可以暂时不实现;但一旦要建单就会抛 +> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。 +> +> **没有 Redis 可以先用内存版**(`InMemoryIdempotencyStore`,在 `sdk-testkit` 里), +> 但它只适合单实例测试,生产必须换成 Redis / DB。 -## 1.3 构建门面 +### 组装 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(repo) // 必需 - .idempotencyStore(idempotencyStore) // 写操作必需 - .clock(Clock.systemUTC()) // 可选,默认 UTC - .idempotencyOwner("oms-node-1") // 多实例部署时区分 - .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) - .requestIdSupplier(() -> UUID.randomUUID().toString()) + .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())) - .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` 会让缓存失效。 - **各仓工厂的构造参数** | 工厂 | 构造参数 | @@ -164,13 +213,18 @@ WarehouseSdk sdk = WarehouseSdk.builder() | `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` | | `HengjianAdapterFactory` | 无参 | -## 1.4 连接信息(端点 + 凭据) +> **务必做成单例。** 适配器里缓存了 token 和限流器,每次 `new` 会重复登录。 + +### 连接信息(端点 + 凭据) -**SDK 不保存端点、不读环境变量。** 每次调用都要由宿主传入。 +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", + "https://test.omniselling.com.cn/saas-service/openapi/microService", // 端点 ChannelSecret.builder() .appKey("...") .appSecret("...") @@ -179,772 +233,729 @@ WarehouseConnection conn = WarehouseConnection.of( .build()); ``` -**各仓需要的凭据字段** +**各仓需要哪些凭据字段** -| 仓 | 需要的字段 | 说明 | +| 仓 | 必填字段 | 说明 | |---|---|---| -| 易达云 | `appKey`、`appSecret`、`clientId`、`clientSecret` | `clientId/Secret` 换 token;`appKey/appSecret` 算签名 | -| 运去哪 | `appSecret` | 组织级 token 固定放请求头,复用 `appSecret` 承载 | -| 信仓 | `appKey`、`appSecret` | 换 token | -| 恒健 | `appSecret` | 签名 | +| 易达云 | `appKey` `appSecret` `clientId` `clientSecret` | 前两个算签名,后两个换 token | +| 运去哪 | `appSecret` | 组织级 token,直接放 `appSecret` | +| 信仓 | `appKey` `appSecret` | 换 token | +| 恒健 | `appSecret` | 算签名 | -**安全要求** +## 1.3 拿到一个仓的操作入口 -- `ChannelSecret.toString()` 不打印密钥,日志里只用 `fingerprint()` -- 不要把 `ChannelSecret` 序列化进日志或异常 -- 生产从 KMS / Vault 取,不要硬编码 - -## 1.5 取某个仓的操作视图 +**所有业务接口都从这里进**: ```java -// 每次都传连接信息(端点与凭据随调用走,SDK 不缓存) +import common.ecommerce.warehouse.sdk.WarehouseOperations; + WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); ``` -`warehouses()` 做的事: +后面所有示例里的 `wh` 都是这行拿到的。 -1. 按 `warehouseCode` 查 `WarehouseRepository` → 拿 `WarehouseAccount` -2. 按 `provider` 解析出适配器 -3. 组装 `WarehouseContext`(仓编码、provider、仓方 id、连接、requestId、clock) +## 1.4 验证能跑通 -拿不到账户时抛 `IllegalStateException`。 - -**查能力位(不触发真实请求)** +在正式写业务前,先跑这一行——**只读,不改任何数据**: ```java -EnumSetView caps = sdk.capabilities("EDY-USLA"); -boolean canReturn = caps.supported().contains(WarehouseCapability.RETURN); -``` - ---- - -# 二、入参怎么传、出参怎么取 +import common.ecommerce.warehouse.model.WarehouseFacility; +import java.util.List; -## 2.1 通用约定(单位、时间、SKU、金额) +List warehouses = wh.warehouses(); -### 单位 +System.out.println("该账户有权限的仓:" + warehouses.size()); +for (WarehouseFacility w : warehouses) { + System.out.println(" " + w.warehouseCode() + " " + w.name() + " " + w.country()); +} +``` -| 项 | 统一模型 | 说明 | -|---|---|---| -| 尺寸 | **cm** | 字段名带 `Cm` | -| 重量 | **g** | 字段名带 `Grams` | -| 时间 | **`Instant`(UTC)** | SDK 内部一律 UTC,展示时区由宿主决定 | -| 金额 | **`Money`**(金额 + 币种) | 不允许裸数字,避免丢币种 | +能打出仓,说明**凭据、端点、配置全都对了**。 -适配器负责换算成仓方单位(易达云要 kg,会自己从 g 转)。 +跑不通时的对照: -### SKU 口径(最容易错的地方) +| 现象 | 原因 | +|---|---| +| `IllegalStateException: 该仓没有配置接入账户` | `warehouseCode` 和你的 `WarehouseRepository` 对不上 | +| `WarehouseUnsupportedCapabilityException` | 这家仓没有仓库清单接口(先看 [二](#二我要做的事能不能做)) | +| `WarehouseException ... http 401` | `appKey` / `appSecret` / `clientId` / `clientSecret` 有错 | +| 超时 | 端点不通;易达云首次调用较慢,建议重试一次 | -**所有环节都用「建档时下发给仓方的那串」。** +--- -```java -// 建档时 -String sku = product.providerSku(); // 宿主给了就用它 -sku = sku != null && !sku.isEmpty() ? sku : product.omsSku(); // 没给就用 OMS SKU -``` +# 二、我要做的事能不能做? + +| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 | +|---|---|:---:|:---:|:---:|:---:| +| 建出库单 / 打面单 | `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)` -| 场景 | 仓方库里存的 | 之后要传 | -|---|---|---| -| 给了 `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` | +> 以下示例假设 `wh` 已就绪(见 [1.3](#13-拿到一个仓的操作入口))。 +> 所有代码都是**片段**,省略了 import 与 try-catch,完整写法见 [五](#五出错了怎么办)。 -**SDK 不做 OMS → 仓侧 SKU 的转换**:映射表在宿主手里。传错不报错,只会查不到。 +## 3.1 发货:建出库单 → 拿面单 -### 金额 +### 第一步:建单 ```java -Money.of("19.99", "USD") // 字符串构造,保留精度 -Money.zero("USD") -money.add(other) / subtract / multiply / round() -``` +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.model.*; -## 2.2 分页入参 / 出参 `Page` +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(); -**入参**(每个 Query 都有) +OutboundReceipt receipt = wh.outbound().create(cmd); -```java -.pageSize(100) // 单页条数;各仓有上限,适配器会截断 -.cursor(null) // 第一页传 null +receipt.providerOrderId(); // 仓侧单号,**保存下来**,后续查单/取消要用 ``` -**出参** +### 第二步:拿面单 ```java -Page page = ...; +List pkgs = wh.outbound().packages( + OutboundRef.ofRequestNo("OB-20261117-001")); // 用我们自己的单号查 -page.items(); // List,不可变 -page.size(); -page.hasMore(); // 由 nextCursor 推导,不要从 items 数量猜 -page.nextCursor(); // null = 没有下一页 +for (PackageResult p : pkgs) { + p.trackingNumber(); // 跟踪号 + p.labelRef(); // 面单地址(URL) + p.carrier(); // 承运商 +} ``` -**翻页模板** +### 你会拿到什么 -```java -String cursor = null; -do { - Page page = wh.xxx(Query.builder().cursor(cursor).pageSize(100).build()); - for (X item : page.items()) { /* 处理 */ } - cursor = page.nextCursor(); -} while (cursor != null); -``` +| 字段 | 用途 | +|---|---| +| `receipt.providerOrderId()` | 仓侧单号,落库 | +| `p.trackingNumber()` | 跟踪号,回填到订单 | +| `p.labelRef()` | 面单文件地址,用来打印 | -> 各仓页码起点不同(易达云从 1、运去哪从 0),**游标已经屏蔽了差异**。 -> 不要自己算 ±1,原样把 `nextCursor()` 传回去即可。 +### ⚠️ 坑 -## 2.3 出库入参 `OutboundCommand` +1. **州名易达云要全称**(`California`),运去哪要二字码(`CA`)。 +2. **平台面单**要把 `labelMode` 设成 `PLATFORM_LABEL`,且易达云要的是 **文件 URL 不是 base64**——传 base64 会本地报错。 +3. **重复建单不会重复下单**:幂等键是 `orderRef`(没有则用 `outboundRequestNo`),同样的键再调一次会返回上次结果。 +4. **保存 `providerOrderId`**,取消和查单时能少一次请求。 -### 必填 +--- -| 字段 | 类型 | 说明 | -|---|---|---| -| `outboundRequestNo` | String | 我们自己的出库单号 | -| `salesPlatform` | Platform | 销售平台,映射成仓方 `channelName` | -| `shipTo` | ShipTo | 收件地址 | -| `line(...)` | OutboundLine | 至少一条商品行 | +## 3.2 查物流轨迹 -### 选填 +```java +// 只要节点 +List events = wh.track("1Z999AA10123456784"); +for (TrackEvent e : events) { + e.occurredAt(); // 时间 + e.description(); // 如「上网」「已派送」 + e.status(); // 仓方原值 +} -| 字段 | 说明 | -|---|---| -| `orderRef` | **平台单号,仓侧幂等键**(强烈建议给) | -| `warehouseId` | 指定发货仓;空则用账户配置 | -| `labelMode` | `WAREHOUSE_LABEL`(仓出)/ `PLATFORM_LABEL`(我们传面单) | -| `carrier` / `carrierCode` | 承运商 | -| `trackingNumber` | 跟踪号(平台面单时用) | -| `labelContentBase64` | 面单内容;易达云要 **URL** 不是 base64 | -| `currency` | 币种 | -| `declaredTotal` | 申报总额(Money) | -| `latestShipDate` | 最晚发货时间 | -| `remark` | 备注 | -| `signatureRequired` | 是否需要签收 | -| `sfp` | 是否 SFP 订单 | -| `packages` | 包裹拆分(多箱时) | - -### `OutboundLine` - -| 字段 | 说明 | +// 要运单整体状态(推荐) +TrackingInfo info = wh.trackShipment("1Z999AA10123456784"); + +info.firstOnlineAt(); // 上网时间(承运商首次揽收) +info.deliveredAt(); // 妥投时间 +info.carrier(); +info.events(); // 节点列表 +``` + +### 你会拿到什么 + +| 字段 | 含义 | |---|---| -| `lineNo` | 行号 | -| `omsSku` / `providerSku` | **providerSku 优先**(见 2.1) | -| `quantity` | 数量 | -| `declareName` / `declareNameEn` | 申报中/英文名 | -| `declareValue` | 申报单价(Money,**不是总额**) | -| `hsCode` / `countryOfOrigin` | 海关 | -| `insuredAmount` | 保价金额(易达云:任意行有值即整单保价) | -| `platformOrderItemId` | 平台子单号(亚马逊 `platformItemId`、eBay `ebayItemId`) | +| `firstOnlineAt()` | **包裹到底有没有交给承运商** —— 为空说明物流还没启动 | +| `deliveredAt()` | 妥投时间,为空表示未签收 | +| `signedBy()` | 签收人;**未签收就是 null** | -### `ShipTo` +### ⚠️ 坑 -```java -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() -``` +- **查不到不报错**:`track()` 返回空列表、`trackShipment()` 返回 `null`。这表示「还没轨迹」,不是失败。 +- 易达云 PR 环境目前没有可查到的轨迹数据,接口通但返回空。 -### 出参 `OutboundReceipt` +--- -```java -receipt.outboundRequestNo(); // 回显我们传入的单号 -receipt.providerOrderId(); // 仓侧单号(幂等重试时靠它定位) -receipt.rawStatus(); // 仓方原文 -``` +## 3.3 取消出库单 -## 2.4 库存入参 `InventoryQuery` +### 先问仓方能不能取消 ```java -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(); +import common.ecommerce.warehouse.enums.CancelEligibility; + +CancelEligibility e = wh.outbound().checkCancel( + OutboundRef.ofRequestNo("OB-20261117-001")); + +// FREE 可以免费取消 +// CHARGED 取消要收钱 +// BLOCKED 不能取消(已发货 / 已取消) ``` -出参 `Page` +### 再决定要不要取消 ```java -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(); +if (e == CancelEligibility.FREE) { + CancelResult r = wh.outbound().cancel(CancelCommand.builder() + .outboundRequestNo("OB-20261117-001") + .providerOrderId("ORD123") // 有就一起给,定位更准 + .acceptCharge(false) // 收费取消时传 false 会抛异常 + .build()); + + r.cancelled(); // true = 取消成功 +} ``` -> **`-1` 是「仓方没给」,不是 0。** 易达云的 `safeStock` 大量为 null,映射成 -1。 +### ⚠️ 坑 -**同步策略** +- `CHARGED` 时如果 `acceptCharge=false`,抛 `OutboundCancelChargeRequiredException`——**先 catch 再跟用户确认**。 +- `BLOCKED` 时抛 `OutboundCancelBlockedException`。 +- 重复调用不会重复取消(幂等),可以放心重试。 -```java -wh.inventorySyncStrategy(); // TIME_WINDOW / FULL_PULL_DIFF -``` +--- -`FULL_PULL_DIFF` 表示**没有时间维度**,`updatedAfter` 不生效,必须全量拉再 diff。 +## 3.4 退货 -## 2.5 入库入参 `InboundCommand` +### 建退货单 ```java -InboundCommand.builder() - .inboundRequestNo("IB-001") // 必填,幂等键 +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") - .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(); + .remark("客户寄回") + .build()); + +r.providerReturnId(); // 仓侧 RMA 号,**保存下来** ``` -出参 `InboundReceipt { inboundRequestNo(); providerInboundId(); }` +**`ReturnDealMethod` 选哪个** -**查询**:`inbound().get(ref)` / `query(cursor)` / `queryInbounds(InboundQuery)` +| 值 | 含义 | +|---|---| +| `WAREHOUSE_CONFIRM` | 仓库确认后处理(最常用) | +| `DESTROY` | 直接销毁 | +| `CUSTOMER_PICKUP` | 客户自提 | +| `PHOTO_CONFIRM` | 拍照确认后再定 | -## 2.6 退货入参 `ReturnCommand` / `ReturnQuery` +> ⚠️ **易达云只支持「自行退回」**,且**拒绝** `lineName` / `estimatedReceiveDate` / +> `returnReason`——传了会直接报错。 -### `ReturnCommand`(创建) +### 查退货进度 ```java -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` +WarehouseReturn detail = wh.returns().get("RMA2411053149"); // 仓侧 RMA 号 -> **易达云只支持「自行退回」**(它要求退货运单号),且**拒绝** `lineName` / -> `estimatedReceiveDate` / `returnReason` —— 传了直接报错,不静默丢弃。 +detail.status(); // DRAFT / RETURNING / PENDING_RECEIPT / COMPLETED / CLOSED ... +detail.rawStatus(); // 仓方原文,排查时看这个 +detail.lines(); // 明细:SKU / 数量 / 检验结果 +``` -### `ReturnQuery`(查询) +### 分页查退货单 ```java -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(); +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()); ``` -`ReturnStatus`:`DRAFT` / `PENDING_REVIEW` / `REJECTED` / `RETURNING` / -`PENDING_RECEIPT` / `COMPLETED` / `CLOSED` / `UNKNOWN` - -### 出参 `WarehouseReturn` +### 取消退货单 ```java -r.returnRequestNo(); // 我们传入的 -r.providerReturnId(); // 仓侧 RMA 号 -r.status(); // 统一状态 -r.rawStatus(); // 仓方原文(中文名或码) -r.lines(); // 明细 -r.createdAt(); -r.sourceProvider(); +boolean ok = wh.returns().cancel("RMA2411053149"); ``` -`ReturnLine`:`providerSku` / `quantity` / `newSku` / `inventoryType` / -`processedQuantity` / `suggestedDisposition` / `pictureUrls` / `remark` +> 传的是**仓侧 RMA 号**,不是我们的单号。 +> 仓方拒绝时**抛异常**,不返回 false。 -## 2.7 费用入参 `FeeQuery` / `FeeEstimateQuery` +--- -### `FeeQuery`(已发生的账单) +## 3.5 库存同步 -```java -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` +```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()); -| 方法 | 口径 | -|---|---| -| `fees().settlements(query)` | 账户流水(充值 / 扣费 / 退费 + 余额) | -| `fees().orderCosts(query)` | 按订单拆的费用(应收 / 折扣 / 实付 + 计费重) | -| `fees().storageRents(query)` | 仓租(按 SKU + 计费日逐条) | +for (InventorySnapshot s : page.items()) { + s.providerSku(); + s.available(); // 可用 + s.onHand(); // 总库存 + s.inTransit(); // 在途 + s.reserved(); // 冻结 +} +``` -出参 `List` +### 全量同步怎么做 ```java -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(); +// 先问这家仓支不支持增量 +InventorySyncStrategy strategy = wh.inventorySyncStrategy(); +// TIME_WINDOW 可以按 updatedAfter 增量 +// FULL_PULL_DIFF 只能全量拉再自己比对 ``` -### `FeeEstimateQuery`(发货前报价) - ```java -FeeEstimateQuery.builder() - .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000) - .receiveCountry("US").receivePostal("91761").receiveCity("...") - .warehouseCode("EDY-USLA") - .logisticsServiceCode("80") // 指定渠道;空则返回全部 - .build(); +// 全量翻页模板 +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); ``` -出参 `List` +### ⚠️ 坑 -```java -r.shipOrgWarehouseCode(); -r.carriers(); // List - q.carrier(); q.logisticsServiceCode(); - q.totalRate(); // Money - q.costItems(); // 细分:costName + estimatedCost -``` +- **`-1` 是「仓方没给」,不是 0**:`pendingOutbound` / `alertQuantity` 这类字段,仓方常返回 null,SDK 统一映射成 -1。展示时要区分。 +- **易达云没有时间维度**,`updatedAfter` 不生效,只能全量。 +- **零库存**:`includeZeroStock` 不传时由仓方默认(多数仓只返回 >0 的)。 -## 2.8 商品入参 `WarehouseProduct` / `ProductQuery` +--- -### `WarehouseProduct`(建档) +## 3.6 商品主数据 -**必填**:`omsSku`、`name`、`lengthCm`、`widthCm`、`heightCm`、`weightGrams` +### 建档 -**强烈建议**:`providerSku`、`barcode`、`nameEn`、`declareValue` + `countryOfOrigin` + `hsCode` +```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 重新打包) | 不支持 | +| `nameEn` | 可选 | **必填** | 不用 | +| `packingType` | 不用 | **必填**(0 原包装 / 1 重新打包) | 不用 | | `hsCode` 三项 | 用 | **必填整组** | 只用 `declaredValue` | -| `productCategory` | 不用 | 不用 | 用 | -| `imageUrls` | 不用 | 不用 | 用(尺寸复核图) | -### `ProductQuery`(查询) +> 不知道传哪个?**看目标仓是哪家,按那一列的要求传。** -```java -ProductQuery.builder() - .providerSku("SKU") // 仓侧 SKU - .barcode("N949...") // 运去哪不支持,传了本地报错 - .createdAfter(...).createdBefore(...) // 运去哪不支持 - .pageSize(100).cursor(null) - .build(); -``` +### 查询 -**支持的过滤维度** +```java +Page page = wh.queryProducts( + ProductQuery.builder() + .providerSku("AP0000X9US0010601") // 仓侧 SKU + .pageSize(100) + .build()); -| | 易达云 | 运去哪 | -|---|---|---| -| SKU 数量上限 | 50 | 100 | -| 条码 | ✅ | ❌ | -| 创建时间窗 | ✅ | ❌ | -| 不会默认时间窗 | 不带则**只查最近一个月** | 全量 | +ProductInfo info = page.items().get(0); +info.lengthCm(); info.weightGrams(); // **实际值**,不是预报值 +info.packedQuantity(); +``` -## 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` | 见 2.2 | +- **易达云是「创建」不是「保存」**:同 SKU 重复建档会报错。运去哪才是 upsert。 +- **易达云不带时间窗时只查最近一个月**,查老商品必须显式给 `createdAfter/Before`。 +- **运去哪不支持条码和时间窗过滤**,传了会本地报错(不会静默忽略)。 --- -# 三、各能力怎么调用 - -## 3.0 视图结构 +## 3.7 对账:拉费用明细 -`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 商品 +三个方法,看你要什么: ```java -WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); +// ① 账户流水(充值 / 扣费 / 退费 + 余额) +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()); -// 建档(写) -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 +// ② 按订单拆的费用(应收 / 折扣 / 实付 + 计费重) +List costs = wh.fees().orderCosts(FeeQuery.builder() + .saleOrderNo("SO-20261117-001") + .build()); -// 查询(只读) -Page page = wh.queryProducts( - ProductQuery.builder().providerSku("AP0000X9US0010601").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()); ``` -## 3.3 出库 +**你会拿到什么** ```java -WarehouseOutbounds out = wh.outbound(); - -// 建单(写,幂等键 = orderRef/outboundRequestNo) -OutboundReceipt r = out.create(cmd); +d.documentNo(); // 单据号 +d.feeName(); // 计费项名,如「尾程-燃油附加费」 +d.feeType(); // OPERATION / STORAGE / VALUE_ADDED / LAST_MILE +d.amount(); // Money(金额 + 币种) +d.settledAt(); // 计费时间 +d.estimated(); // true 预估 / false 实际 +``` -// 查单 -OutboundOrder o = out.get(OutboundRef.ofRequestNo("OB-1")); // 用我们的单号 -OutboundOrder o2 = out.get(OutboundRef.ofProviderOrderId("ORD123")); // 或用仓侧单号 +### 发货前算运费 -// 分页查 -// OutboundQuery 的时间 / 状态 / 排序端口径按仓定义,都是字符串 -Page list = out.query(OutboundQuery.builder() - .after(instant).before(instant) - .status("Shipped") // **仓侧原始状态字符串**,不是统一枚举 - .pageSize(100).cursor(null) +```java +List quotes = wh.fees().estimate(FeeEstimateQuery.builder() + .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000) + .receiveCountry("US").receivePostal("91761") + .logisticsServiceCode("80") // 指定渠道;空则返回所有渠道 .build()); -// 面单 -List 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()); +for (FeeEstimateResult q : quotes) { + for (FeeEstimateResult.CarrierQuote c : q.carriers()) { + c.carrier(); // 渠道名 + c.totalRate(); // 总价(Money) + c.costItems(); // 细分 + } } - -// 附件 -out.attachment(ref, attachments); ``` -`CancelEligibility`:`FREE`(免费)/ `CHARGED`(收费)/ `BLOCKED`(不可取消) +### ⚠️ 坑 -> **`OutboundQuery.status(...)` 收的是仓侧原始状态字符串**(如易达云 `Shipped`), -> 不是统一的 `OutboundStatus` 枚举——各仓码表不同,适配器不归一。 -> 想知道统一状态,用返回的 `OutboundOrder.status()`。 +- **必须给成本类型或时间窗**,否则本地拒绝(防止拉全量把账户拉爆)。 +- **易达云的「3 个月」时间窗阈值很怪**:同天数不同起点,结果可能一个通一个拒。超限时仓方返回明确错误,catch 后缩小窗口重试即可。 +- **费用试算第一次常超时**,重试一次就好。 -> 收费取消时 `acceptCharge=false` 会抛 `OutboundCancelChargeRequiredException`, -> 不可取消抛 `OutboundCancelBlockedException`。 +--- -## 3.4 库存 +## 3.8 打单:箱唛 / BOL + +### 箱唛(外箱标) ```java -// 策略 -InventorySyncStrategy s = wh.inventorySyncStrategy(); +import common.ecommerce.warehouse.enums.CaseMarkPaperSize; +import common.ecommerce.warehouse.model.CaseMarkPrintCommand; -// 查询 -Page page = wh.inventory().query( - InventoryQuery.builder().sku("SKU").pageSize(100).build()); -``` +WarehouseLabel label = wh.printCaseMarks(CaseMarkPrintCommand.builder() + .paperSize(CaseMarkPaperSize.SIZE_70_30) // 见下表 + .printSkuName(false) + .remark("Made in China") + .item("AP0000X9US0010601", 2) // SKU + 份数,最多 50 个 + .build()); -## 3.5 入库 +label.url(); // PDF 地址 +``` -```java -WarehouseOperations.InboundView in = wh.inbound(); +| 纸张 | 实际尺寸 | +|---|---| +| `SIZE_70_30` | 70 × 30 mm | +| `SIZE_100_60` | 100 × 60 mm | +| `SIZE_100_150` | 100 × 150 mm | +| `SIZE_60_40` | 60 × 40 mm | -InboundReceipt r = in.create(cmd); // 写 -InboundOrder o = in.get("IB-001"); // 按单号 -Page list = in.query(cursor); // 按游标 -Page adv = in.queryInbounds(InboundQuery.builder()...build()); -in.improve("IB-001", cmd); // 写:补资料 -in.submit("IB-001"); // 写:提交 -List bols = in.bols("IB-001"); // 入库计划 BOL 文件 -LabelPrintTask box = in.printBoxLabel(boxLabelCmd); // 异步任务 -LabelPrintTask sku = in.printSkuLabel(skuLabelCmd); // 异步任务 -``` +> ⚠️ **枚举是按实测尺寸命名的**。仓方文档标的和实际印出来的对不上(文档说第 2 档 6×4cm、第 3 档 A4,实际反过来),以枚举名为准。 -## 3.6 退货 +### BOL(提货单 / 签收凭证) ```java -WarehouseOperations.ReturnView rt = wh.returns(); +List bols = wh.orderBols("FBA473182144"); // EDA 平台仓订单号 -WarehouseReturn r = rt.create(cmd); // 写,幂等键 = returnRequestNo -WarehouseReturn d = rt.get("RMA1001"); // 按仓侧 RMA 号 -Page list = rt.query(ReturnQuery.builder()...build()); -rt.process(processCmd); // 写:检验后处理(多数仓不支持) -boolean ok = rt.cancel("RMA1001"); // 写,幂等 +for (BolDocument b : bols) { + b.bolCode(); + b.fileUrl(); // BOL 文件 + b.podFileUrl(); // 签收凭证 POD + b.statusName(); // 如「已妥投」 + b.scheduledPickupQuantity(); +} ``` -> `cancel` 返回 `true` 表示成功;仓方拒绝时**抛 `WarehouseException`**,不返回 false。 +--- -## 3.7 费用 +# 四、几条贯穿全局的规则 -```java -WarehouseOperations.FeeView fee = wh.fees(); +## 4.1 单位:尺寸 cm、重量 g + +| 项 | 单位 | 字段名 | +|---|---|---| +| 尺寸 | **cm** | 带 `Cm` 后缀 | +| 重量 | **g** | 带 `Grams` 后缀 | -// 试算(发货前报价) -List quotes = fee.estimate(FeeEstimateQuery.builder()...build()); +**不要自己换算**——易达云内部要 kg,适配器会自己转。 -// 结算明细(已发生) -List flows = fee.settlements(FeeQuery.builder()...build()); -List costs = fee.orderCosts(FeeQuery.builder()...build()); -List rents = fee.storageRents(FeeQuery.builder()...build()); +## 4.2 SKU:到底传哪一个(最容易错) -// 最优渠道推荐(按 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 +``` +建档时:providerSku 有值 → 仓方存它 + 没值 → 仓方存 omsSku + ↓ +之后:查商品 / 下单 / 查库存 都用同一串 ``` -> 易达云三个费用方法都必须给**成本类型或时间窗**,否则本地拒绝(避免拉全量)。 +| 你建档时 | 仓方存的 | 之后必须传 | +|---|---|---| +| 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) | +| 没传 | `omsSku` | `omsSku` | -## 3.8 基础资料(仓库 / 承运商 / 物流产品) +各仓字段名不同,但**值一样**: -```java -// 仓库(只返回有权限的) -List whs = wh.warehouses(); +| 场景 | 易达云字段 | 运去哪字段 | +|---|---|---| +| 建档 | `skuCode` | `sku` | +| 查商品 | `skuCode` | `skuList` | +| 下单 | `productSku` | `sku` | +| 查库存 | `skuCodeList` | `sku` | -// 承运商(带下属物流服务) -List carriers = wh.carrierDirectory(); -List codes = wh.carriers(); // 只要码时用这个 +> **SDK 不做 OMS→仓侧 SKU 转换**。映射表在你们手里。 +> 传错不会报错,只会**查不到**——这是最难排查的坑之一。 -// 物流产品 -List products = wh.logisticsProducts("2"); // 数字仓 id +## 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); ``` -> - 易达云的仓库清单有**两个接口**:`warehouses()` 走「有权限」那个, -> `activeWarehouses(...)` 是平台全量(含未授权的,不要用来给客户选仓)。 -> - 易达云承运商的 `carrierDirectory` 能给出两层结构;**只实现了 `carriers()` 的仓会抛不支持**, -> 不会把物流方式码硬凑成承运商名。 +- `cursor` 第一页传 `null` +- **不要自己算页码**:各仓起点不同(易达云从 1、运去哪从 0),游标已经屏蔽了差异 +- `hasMore()` 由游标推导,**不要拿 `items().size()` 去猜** -## 3.9 单据与打印(BOL / 轨迹 / 箱唛) +## 4.4 金额:为什么一定要用 Money ```java -// BOL(平台仓 / 店铺订单,带提货状态与 POD) -List bols = wh.orderBols("FBA473182144"); +Money.of("19.99", "USD") // ✅ +19.99 // ❌ +``` -// 轨迹 -List events = wh.track("1Z111"); -TrackingInfo info = wh.trackShipment("1Z111"); -info.firstOnlineAt(); // 上网时间 -info.deliveredAt(); // 妥投时间 +裸 `double` 会丢币种,对账时美元和加元混在一起就完了。所有金额字段都是 `Money`,带 `amount()` 和 `currencyCode()`。 -// 箱唛(同步返回 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" -``` +--- -**易达云两个打印接口的语义是反的**(已与仓方确认): +# 五、出错了怎么办 + +## 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) { + // 其它仓方错误 +} +``` -| 端点 | 实际打印 | 方法 | +| 异常 | 含义 | 重试? | |---|---|---| -| `skuInfo/v2/printBarcode` | **箱唛** | `printCaseMarks(...)` | -| `entryInfo/v1/newPrintCaseMark` | SKU 标 | 未开放(仓方内部报错) | - -> `track` 查不到返回**空列表**,`trackShipment` 返回 **null** —— 不抛异常。 -> 易达云的 SKU 标(`printSkuLabel`)在 PR 环境仓方内部报错,未开放。 +| `TransientException` | 网络 / 超时 | ✅ 可以 | +| `WarehouseException`(`retryable=true`) | HTTP 5xx | ✅ 可以 | +| `WarehouseException`(`retryable=false`) | 业务错误(参数错 / 单号不存在) | ❌ 不要 | +| `WarehouseUnsupportedCapabilityException` | 该仓不支持 | ❌ 换方案 | +| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需用户确认 | +| `OutboundCancelBlockedException` | 不能取消 | ❌ | -## 3.10 调拨 / 销毁 / 物流异动 +## 5.2 异常里有什么 ```java -// 调拨(写) -TransferOrder t = wh.createTransfer(cmd); -wh.approveTransfer("T-001"); -TransferOrder tg = wh.getTransfer("T-001"); -Page 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"); +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` | +| `参数不能为空` | 必填字段漏了 | 看对应任务的「必填」段 | -``` -ChannelException (RuntimeException) // 与渠道域共用基类 -└── WarehouseException - ├── WarehouseUnsupportedCapabilityException // 能力不支持,不要重试 - ├── WarehouseDuplicateOrderException // 重复下单 - ├── OutboundCancelBlockedException // 取消被拒 - ├── OutboundCancelChargeRequiredException // 取消要收费 - └── WarehouseWebhookVerificationException // 回调验签失败(宿主返 4xx) -``` +## 5.4 幂等:重复调用安全吗 -**取值** +**写操作都安全**,同样的单号调两次不会重复下单: -```java -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,别直接落日志**) +| 操作 | 幂等键 | +|---|---| +| 建出库单 | 仓编码 + `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 退避 + } } ``` -**重试判定** +--- -| 情况 | `retryable` | -|---|---| -| 网络 / 超时(`TransientException`) | `true` | -| HTTP 5xx | `true` | -| HTTP 4xx / 业务码非成功 | `false` | -| 能力不支持 | 不重试 | +## 附录 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: ... +``` + +| 字段 | 含义 | |---|---| -| `outbound().create` | `warehouseCode + outboundRequestNo + create` | -| `inbound().create` | `warehouseCode + inboundRequestNo + create` | -| `returns().create` | `warehouseCode + returnRequestNo + create` | -| `returns().cancel` | `warehouseCode + providerReturnNo + cancel` | -| `createTransfer` | `warehouseCode + transferRequestNo + create` | +| `op` | 哪个操作 | +| `provider` | 哪家仓 | +| `requestId` | 我们的链路 ID | +| `cost` | 耗时 | +| `result` | 返回条数(-1 表示不适用) | +| `code` / `platformCode` | 业务码 / 仓方码 | +| `params` | 关键入参摘要(不含 PII) | -重放时返回上次的结果引用,**不会真的再调一次仓方**。 +日志**不含凭据和完整报文**,可以放心长期保留。 --- -# 五、常见坑速查 +## 附录 B:枚举速查 -| 坑 | 说明 | +| 枚举 | 取值 | |---|---| -| **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` 才跑,不会误连生产 | +| `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 -.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) +OutboundCommand cmd = ...; +cmd.lines(); // IDE 里按住 Ctrl 点进去看注释 ``` -输出形如: - -``` -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`, -并对仓方文案做去换行 + 截断(防日志注入)。日志**不含凭据与报文**。 +- `docs-warehouse/edayun/README.md`、`docs-warehouse/edayun/TODO.md` +- `docs-warehouse/yqn/README.md` +- `docs-warehouse/hengjian/README.md` +- `docs-warehouse/architecture.md`(分层与能力位设计)