|
|
|
@ -0,0 +1,783 @@ |
|
|
|
|
|
|
|
# 三方仓 SDK 使用说明(Jar 引入版) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> 我们提供编译好的 jar,按正常 Maven / Gradle 依赖引入即可,**不需要拷源码**。 |
|
|
|
|
|
|
|
> 本文档说明:引哪些 jar、怎么配置、每个业务动作怎么写。 |
|
|
|
|
|
|
|
> |
|
|
|
|
|
|
|
> 想直接用源码集成的话,看同目录的 `SDK使用说明-源码集成.md`。 |
|
|
|
|
|
|
|
> |
|
|
|
|
|
|
|
> JDK 1.8 · 版本 1.0.0-SNAPSHOT |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 快速导航 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 我要… | 看这节 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 引入 jar | [一、集成方式](#一集成方式) | |
|
|
|
|
|
|
|
| 配好 SPI / SDK / 连接 | [二、配置](#二配置) | |
|
|
|
|
|
|
|
| 确认能跑通 | [三、快速上手](#三快速上手) | |
|
|
|
|
|
|
|
| 知道某仓支不支持某功能 | [四、我要做的事能不能做](#四我要做的事能不能做) | |
|
|
|
|
|
|
|
| 发货 / 面单 | [5.1](#51-发货建出库单--拿面单) | |
|
|
|
|
|
|
|
| 查轨迹 / 取消订单 | [5.2](#52-查物流轨迹) · [5.3](#53-取消出库单) | |
|
|
|
|
|
|
|
| 退货 / 库存 / 商品 / 对账 | [5.4](#54-退货) · [5.5](#55-库存同步) · [5.6](#56-商品主数据) · [5.7](#57-对账拉费用明细) | |
|
|
|
|
|
|
|
| 打箱唛 / BOL | [5.8](#58-打单箱唛--bol) | |
|
|
|
|
|
|
|
| 单位 / SKU / 分页 / 金额 | [六、贯穿全局的规则](#六几条贯穿全局的规则) | |
|
|
|
|
|
|
|
| 报错 / 重试 | [七、出错了怎么办](#七出错了怎么办) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 一、集成方式 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.1 需要引入的 jar |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**核心两个 + 按需引入适配器**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| jar | 说明 | 必需 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| `warehouse-sdk-core` | 统一模型 + 门面 + 能力接口(会带出 `sdk-common`) | ✅ | |
|
|
|
|
|
|
|
| `warehouse-sdk-edayun` | 易达云适配器 | 用哪个仓引哪个 | |
|
|
|
|
|
|
|
| `warehouse-sdk-yqn` | 运去哪适配器 | 同上 | |
|
|
|
|
|
|
|
| `warehouse-sdk-xincang` | 信仓适配器 | 同上 | |
|
|
|
|
|
|
|
| `warehouse-sdk-hengjian` | 恒健适配器 | 同上 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> 适配器 jar 只依赖 `sdk-common` + `warehouse-sdk-core`,**互不依赖**, |
|
|
|
|
|
|
|
> 只引实际要用的那一个或几个即可,不会把别家仓的代码带进来。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.2 Maven |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```xml |
|
|
|
|
|
|
|
<dependencies> |
|
|
|
|
|
|
|
<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> |
|
|
|
|
|
|
|
</dependencies> |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.3 Gradle |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```kotlin |
|
|
|
|
|
|
|
dependencies { |
|
|
|
|
|
|
|
implementation("ecommerce:warehouse-sdk-core:1.0.0-SNAPSHOT") |
|
|
|
|
|
|
|
implementation("ecommerce:warehouse-sdk-edayun:1.0.0-SNAPSHOT") // 按需 |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.4 jar 里有源码,建议开启 source 下载 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
我们对外发布的 jar 同时带了 `-sources.jar`,IDE 里 Ctrl+点击能直接看到字段注释: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```bash |
|
|
|
|
|
|
|
# Maven |
|
|
|
|
|
|
|
mvn dependency:sources |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Gradle(IDEA 里右键项目 → Download Sources 也可) |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.5 传递依赖(jar 自动带上,不用手工加) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 库 | 版本 | 由谁带出 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| `com.fasterxml.jackson.core:jackson-databind` | 2.13.5 | sdk-common | |
|
|
|
|
|
|
|
| `org.slf4j:slf4j-api` | 1.7.36 | sdk-common | |
|
|
|
|
|
|
|
| `com.squareup.okhttp3:okhttp` | 4.12.0 | sdk-common | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> **不需要 Lombok**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**两个注意点** |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. **OkHttp 4.x 是 Kotlin 写的**,需要 classpath 上有 `kotlin-stdlib`。 |
|
|
|
|
|
|
|
不想引 Kotlin 的话,可以: |
|
|
|
|
|
|
|
- 降级到 OkHttp 3.14.x(纯 Java,API 兼容),或 |
|
|
|
|
|
|
|
- 自己实现 `HttpTransport`(只有一个 `execute()` 方法),换成你们已有的 HTTP 客户端; |
|
|
|
|
|
|
|
需要的话我们出一个无 OkHttp 依赖的版本 |
|
|
|
|
|
|
|
2. **版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的, |
|
|
|
|
|
|
|
代码只用了最基础的 API(`ObjectMapper` / `MediaType` / `OkHttpClient`),向上兼容 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 二、配置 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 2.1 实现两个 SPI |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### ① 仓编码 → 哪家仓 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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`(如果拷了的话)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```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); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 2.2 组装 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)`;前两个可传 `null`(则每次重登) | |
|
|
|
|
|
|
|
| `YqnAdapterFactory` | `(Clock)` | |
|
|
|
|
|
|
|
| `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` | |
|
|
|
|
|
|
|
| `HengjianAdapterFactory` | 无参 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 2.3 连接信息(端点 + 凭据) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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` | 算签名 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 三、快速上手 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 3.1 拿到仓的操作入口 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseOperations; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
后面所有 `wh.xxx()` 都从这个对象出发。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 3.2 验证能跑通 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**只读,不改任何数据**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.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") // ⚠️ 易达云要全称、运去哪要 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(); // 仓侧单号,**保存下来** |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
拿面单: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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`,后续查单 / 取消能少一次请求 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.2 查物流轨迹 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
List<TrackEvent> events = wh.track("1Z999AA10123456784"); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TrackingInfo info = wh.trackShipment("1Z999AA10123456784"); |
|
|
|
|
|
|
|
info.firstOnlineAt(); // 上网时间(为空 = 物流还没启动) |
|
|
|
|
|
|
|
info.deliveredAt(); // 妥投时间(为空 = 未签收) |
|
|
|
|
|
|
|
info.signedBy(); // 签收人(未签收 = null) |
|
|
|
|
|
|
|
info.events(); |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.3 取消出库单 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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`。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.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") |
|
|
|
|
|
|
|
.build()); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
r.providerReturnId(); // 仓侧 RMA 号,**保存下来** |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
查进度 / 取消: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
WarehouseReturn detail = wh.returns().get("RMA2411053149"); |
|
|
|
|
|
|
|
detail.status(); // 统一状态 |
|
|
|
|
|
|
|
detail.rawStatus(); // 仓方原文 |
|
|
|
|
|
|
|
detail.lines(); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` / |
|
|
|
|
|
|
|
`returnReason`(传了直接报错)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.5 库存同步 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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` 不生效 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.6 商品主数据 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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` | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
查询: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
Page<ProductInfo> page = wh.queryProducts( |
|
|
|
|
|
|
|
ProductQuery.builder().providerSku("AP0000X9US0010601").build()); |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑** |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 易达云是「创建」不是 upsert,同 SKU 重复建档会报错 |
|
|
|
|
|
|
|
- 易达云不带时间窗只查最近一个月 |
|
|
|
|
|
|
|
- 运去哪不支持条码 / 时间窗过滤,传了本地报错 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.7 对账:拉费用明细 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
// ① 账户流水 |
|
|
|
|
|
|
|
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 后缩窗重试。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 5.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 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> 枚举按**实测尺寸**命名。仓方文档标的与实际印出来的对不上,以枚举名为准。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
BOL(提货单 / 签收凭证): |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
List<BolDocument> bols = wh.orderBols("FBA473182144"); |
|
|
|
|
|
|
|
b.fileUrl(); // BOL 文件 |
|
|
|
|
|
|
|
b.podFileUrl(); // 签收凭证 |
|
|
|
|
|
|
|
b.statusName(); // 如「已妥投」 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 六、几条贯穿全局的规则 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 6.1 单位:尺寸 cm、重量 g |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 6.2 SKU:到底传哪一个(最容易错) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**所有地方都用「建档时下发给仓方的那一串」。** |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
建档时:providerSku 有值 → 仓方存它 |
|
|
|
|
|
|
|
没值 → 仓方存 omsSku |
|
|
|
|
|
|
|
↓ |
|
|
|
|
|
|
|
之后:查商品 / 下单 / 查库存 都用同一串 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 建档时 | 仓方存的 | 之后必须传 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) | |
|
|
|
|
|
|
|
| 没传 | `omsSku` | `omsSku` | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 6.3 分页 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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()` 猜 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 6.4 金额 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 七、出错了怎么办 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 7.1 五类异常 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
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` | 不能取消 | ❌ | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 7.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()` 有完整报文,可能含买家地址电话。**别直接落日志**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 7.3 常见报错对照 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 报错 | 原因 | 怎么办 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) | |
|
|
|
|
|
|
|
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` | |
|
|
|
|
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [四](#四我要做的事能不能做) | |
|
|
|
|
|
|
|
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` | |
|
|
|
|
|
|
|
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) | |
|
|
|
|
|
|
|
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 7.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`。日志**不含凭据与完整报文**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 附录 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+点击看)。 |