|
|
|
@ -1,11 +1,11 @@ |
|
|
|
# 三方仓 SDK 使用说明(源码集成版) |
|
|
|
# 三方仓 SDK 使用说明(源码集成版) |
|
|
|
|
|
|
|
|
|
|
|
> 我们提供完整源码,直接用源码方式集成,**不走 Maven 坐标**。 |
|
|
|
> 源码已随交付提供,直接在本项目里使用即可。 |
|
|
|
> 本文档说明:源码怎么放、要引哪些第三方库、每个业务动作怎么写。 |
|
|
|
|
|
|
|
> |
|
|
|
> |
|
|
|
> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。 |
|
|
|
> JDK 1.8;需要 `jackson-databind 2.13.5`、`slf4j-api 1.7.36`、`okhttp 4.12.0` |
|
|
|
|
|
|
|
> (或自己实现 `HttpTransport` 替换 OkHttp)。 |
|
|
|
> |
|
|
|
> |
|
|
|
> JDK 1.8 |
|
|
|
> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。 |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
@ -13,181 +13,21 @@ |
|
|
|
|
|
|
|
|
|
|
|
| 我要… | 看这节 | |
|
|
|
| 我要… | 看这节 | |
|
|
|
|---|---| |
|
|
|
|---|---| |
|
|
|
| 把源码放进项目 | [一、源码怎么集成](#一源码怎么集成) | |
|
|
|
| 配好 SPI / SDK / 连接 | [一、配置](#一配置) | |
|
|
|
| 知道要引哪些 jar | [二、必须引入的第三方库](#二必须引入的第三方库) | |
|
|
|
| 确认能跑通 | [二、快速上手](#二快速上手) | |
|
|
|
| 配好 SPI / SDK / 连接 | [三、配置](#三配置) | |
|
|
|
| 知道某仓支不支持某功能 | [三、我要做的事能不能做](#三我要做的事能不能做) | |
|
|
|
| 确认能跑通 | [四、快速上手](#四快速上手) | |
|
|
|
| 发货 / 面单 | [4.1](#41-发货建出库单--拿面单) | |
|
|
|
| 知道某仓支不支持某功能 | [五、我要做的事能不能做](#五我要做的事能不能做) | |
|
|
|
| 查轨迹 / 取消订单 | [4.2](#42-查物流轨迹) · [4.3](#43-取消出库单) | |
|
|
|
| 发货 / 面单 | [6.1](#61-发货建出库单--拿面单) | |
|
|
|
| 退货 / 库存 / 商品 / 对账 | [4.4](#44-退货) · [4.5](#45-库存同步) · [4.6](#46-商品主数据) · [4.7](#47-对账拉费用明细) | |
|
|
|
| 查轨迹 / 取消订单 | [6.2](#62-查物流轨迹) · [6.3](#63-取消出库单) | |
|
|
|
| 打箱唛 / BOL | [4.8](#48-打单箱唛--bol) | |
|
|
|
| 退货 / 库存 / 商品 / 对账 | [6.4](#64-退货) · [6.5](#65-库存同步) · [6.6](#66-商品主数据) · [6.7](#67-对账拉费用明细) | |
|
|
|
| 单位 / SKU / 分页 / 金额 | [五、贯穿全局的规则](#五几条贯穿全局的规则) | |
|
|
|
| 打箱唛 / BOL | [6.8](#68-打单箱唛--bol) | |
|
|
|
| 报错 / 重试 | [六、出错了怎么办](#六出错了怎么办) | |
|
|
|
| 单位 / SKU / 分页 / 金额 | [七、贯穿全局的规则](#七几条贯穿全局的规则) | |
|
|
|
|
|
|
|
| 报错 / 重试 | [八、出错了怎么办](#八出错了怎么办) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 一、源码怎么集成 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.1 源码结构 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
common-ecommerce/ |
|
|
|
|
|
|
|
├── sdk-common/ ← 公共基础(HTTP / JSON / SPI / 审计 / 幂等骨架) |
|
|
|
|
|
|
|
├── warehouse-sdk-core/ ← 三方仓统一模型 + 门面 + 能力接口 |
|
|
|
|
|
|
|
├── warehouse-sdk-edayun/ ← 易达云适配器 |
|
|
|
|
|
|
|
├── warehouse-sdk-yqn/ ← 运去哪适配器 |
|
|
|
|
|
|
|
├── warehouse-sdk-xincang/ ← 信仓适配器 |
|
|
|
|
|
|
|
├── warehouse-sdk-hengjian/ ← 恒健适配器 |
|
|
|
|
|
|
|
├── sdk-testkit/ ← 测试辅助(可选,见 1.4) |
|
|
|
|
|
|
|
├── warehouse-sdk-testkit/ ← 仓域测试辅助(可选) |
|
|
|
|
|
|
|
├── channel-sdk-core/ ← 平台域,本次不用 |
|
|
|
|
|
|
|
└── lingxing/ ← 领星,本次不用 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.2 需要拷贝的模块 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**只拷 `src/main/java`**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 目录 | 作用 | 文件数 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| `sdk-common/src/main/java` | HTTP、JSON、SPI 定义、日志、幂等骨架 | 47 | |
|
|
|
|
|
|
|
| `warehouse-sdk-core/src/main/java` | 统一模型、门面、能力接口 | 126 | |
|
|
|
|
|
|
|
| `warehouse-sdk-edayun/src/main/java` | 易达云适配器(用哪个仓拷哪个) | 64 | |
|
|
|
|
|
|
|
| `warehouse-sdk-yqn/src/main/java` | 运去哪适配器 | 56 | |
|
|
|
|
|
|
|
| `warehouse-sdk-xincang/src/main/java` | 信仓适配器 | 38 | |
|
|
|
|
|
|
|
| `warehouse-sdk-hengjian/src/main/java` | 恒健适配器 | 58 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**不用拷**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- `channel-sdk-core/`、`lingxing/` —— 平台商品域 / 领星,与三方仓无关 |
|
|
|
|
|
|
|
- 各模块的 `src/test/java` —— 单测,不影响运行 |
|
|
|
|
|
|
|
- 仓库域主代码**完全没有引用 `channel` 包**(已全量 grep 核对),只拷上面 6 个即可 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.3 放进项目的两种方式 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 方式 A:保留包结构,直接加入源码目录(推荐) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
包名一律是 `common.ecommerce.*`,**原样拷进去,不需要改任何 import**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
你们的项目/ |
|
|
|
|
|
|
|
└── src/main/java/ |
|
|
|
|
|
|
|
└── common/ecommerce/ |
|
|
|
|
|
|
|
├── shared/ ← 来自 sdk-common |
|
|
|
|
|
|
|
├── http/ ← 来自 sdk-common |
|
|
|
|
|
|
|
├── warehouse/ ← 来自 warehouse-sdk-core |
|
|
|
|
|
|
|
├── edayun/ ← 来自 warehouse-sdk-edayun |
|
|
|
|
|
|
|
├── yqn/ ← 来自 warehouse-sdk-yqn |
|
|
|
|
|
|
|
├── xincang/ ← 来自 warehouse-sdk-xincang |
|
|
|
|
|
|
|
└── hengjian/ ← 来自 warehouse-sdk-hengjian |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
> 6 个模块的根包都是 `common/ecommerce/xxx`,各占一个子目录,合并时**不会冲突**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 方式 B:作为独立模块加入现有构建 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```kotlin |
|
|
|
|
|
|
|
// Gradle |
|
|
|
|
|
|
|
include(":sdk-common", ":warehouse-sdk-core", ":warehouse-sdk-edayun") |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// warehouse-sdk-edayun/build.gradle.kts |
|
|
|
|
|
|
|
dependencies { |
|
|
|
|
|
|
|
api(project(":sdk-common")) |
|
|
|
|
|
|
|
api(project(":warehouse-sdk-core")) |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
java { |
|
|
|
|
|
|
|
sourceCompatibility = JavaVersion.VERSION_1_8 |
|
|
|
|
|
|
|
targetCompatibility = JavaVersion.VERSION_1_8 |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
tasks.withType<JavaCompile> { options.encoding = "UTF-8" } |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Maven 多模块同理:每个模块的 pom 用 `compile` 依赖相邻模块。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 1.4 关于测试代码(可选) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 拷 `src/test/java` 需要额外引入 `junit-jupiter 5.8.2` |
|
|
|
|
|
|
|
- **`sdk-testkit` 主代码引用了 `channel` 包**(`FakeDirectAdapter`), |
|
|
|
|
|
|
|
只想测仓库域的话,**只拷这几个类**: |
|
|
|
|
|
|
|
`RecordingTransport`、`Responses`、`InMemoryTokenStore`、 |
|
|
|
|
|
|
|
`InMemoryLockProvider`、`InMemoryIdempotencyStore`,跳过 `FakeDirectAdapter` |
|
|
|
|
|
|
|
- 或者干脆不拷测试 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 二、必须引入的第三方库 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
仓库域主代码**只用到三个**第三方库(已用 `grep import` 全量核对): |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 库 | 版本 | 用在哪 | 必须? | |
|
|
|
|
|
|
|
|---|---|---|---| |
|
|
|
|
|
|
|
| `com.fasterxml.jackson.core:jackson-databind` | 2.13.5 | 所有 DTO 序列化 | ✅ | |
|
|
|
|
|
|
|
| `org.slf4j:slf4j-api` | 1.7.36 | `Slf4jCallObserver` 打日志 | ✅(实现由你们提供) | |
|
|
|
|
|
|
|
| `com.squareup.okhttp3:okhttp` | 4.12.0 | `sdk-common` 的 `OkHttpTransport` | ✅(可自己实现替换) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**不需要 Lombok**——仓库域主代码一个文件都没用(只有 `lingxing` 用了,那个模块不拷)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Gradle |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```kotlin |
|
|
|
|
|
|
|
dependencies { |
|
|
|
|
|
|
|
implementation("com.fasterxml.jackson.core:jackson-databind:2.13.5") |
|
|
|
|
|
|
|
implementation("org.slf4j:slf4j-api:1.7.36") |
|
|
|
|
|
|
|
implementation("com.squareup.okhttp3:okhttp:4.12.0") |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Maven |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```xml |
|
|
|
|
|
|
|
<dependency> |
|
|
|
|
|
|
|
<groupId>com.fasterxml.jackson.core</groupId> |
|
|
|
|
|
|
|
<artifactId>jackson-databind</artifactId> |
|
|
|
|
|
|
|
<version>2.13.5</version> |
|
|
|
|
|
|
|
</dependency> |
|
|
|
|
|
|
|
<dependency> |
|
|
|
|
|
|
|
<groupId>org.slf4j</groupId> |
|
|
|
|
|
|
|
<artifactId>slf4j-api</artifactId> |
|
|
|
|
|
|
|
<version>1.7.36</version> |
|
|
|
|
|
|
|
</dependency> |
|
|
|
|
|
|
|
<dependency> |
|
|
|
|
|
|
|
<groupId>com.squareup.okhttp3</groupId> |
|
|
|
|
|
|
|
<artifactId>okhttp</artifactId> |
|
|
|
|
|
|
|
<version>4.12.0</version> |
|
|
|
|
|
|
|
</dependency> |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的版本。 |
|
|
|
|
|
|
|
代码只用了最基础的 API,向上兼容。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**OkHttp 4.x 是 Kotlin 写的**,需要 `kotlin-stdlib`。不想引 Kotlin 就: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 用 OkHttp 3.14.x(纯 Java,API 兼容),或者 |
|
|
|
|
|
|
|
- 自己实现 `HttpTransport`(只有一个方法),换成你们已有的 HTTP 客户端: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
import common.ecommerce.http.HttpRequest; |
|
|
|
|
|
|
|
import common.ecommerce.http.HttpResponse; |
|
|
|
|
|
|
|
import common.ecommerce.http.HttpTransport; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
public class MyHttpTransport implements HttpTransport { |
|
|
|
|
|
|
|
@Override |
|
|
|
|
|
|
|
public HttpResponse execute(HttpRequest request) { |
|
|
|
|
|
|
|
// request.method() / url() / headers() / body() / contentType() |
|
|
|
|
|
|
|
// 返回 HttpResponse.of(statusCode, headers, body, latencyMillis) |
|
|
|
|
|
|
|
return ...; |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
然后在组装 SDK 时把它传给适配器(见 3.2 的工厂参数说明)。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 三、配置 |
|
|
|
# 一、配置 |
|
|
|
|
|
|
|
|
|
|
|
## 3.1 实现两个 SPI |
|
|
|
## 1.1 实现两个 SPI |
|
|
|
|
|
|
|
|
|
|
|
### ① 仓编码 → 哪家仓 |
|
|
|
### ① 仓编码 → 哪家仓 |
|
|
|
|
|
|
|
|
|
|
|
@ -308,7 +148,7 @@ public class MyIdempotencyStore implements IdempotencyStore { |
|
|
|
> 只做查询可以先不实现;一旦建单会抛 |
|
|
|
> 只做查询可以先不实现;一旦建单会抛 |
|
|
|
> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。 |
|
|
|
> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。 |
|
|
|
|
|
|
|
|
|
|
|
## 3.2 组装 SDK |
|
|
|
## 1.2 组装 SDK |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseSdk; |
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseSdk; |
|
|
|
@ -340,7 +180,7 @@ WarehouseSdk sdk = WarehouseSdk.builder() |
|
|
|
|
|
|
|
|
|
|
|
> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。 |
|
|
|
> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。 |
|
|
|
|
|
|
|
|
|
|
|
## 3.3 连接信息(端点 + 凭据) |
|
|
|
## 1.3 连接信息(端点 + 凭据) |
|
|
|
|
|
|
|
|
|
|
|
SDK 不保存端点和凭据,每次调用由你们传: |
|
|
|
SDK 不保存端点和凭据,每次调用由你们传: |
|
|
|
|
|
|
|
|
|
|
|
@ -371,9 +211,9 @@ WarehouseConnection conn = WarehouseConnection.of( |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 四、快速上手 |
|
|
|
# 二、快速上手 |
|
|
|
|
|
|
|
|
|
|
|
## 4.1 拿到仓的操作入口 |
|
|
|
## 2.1 拿到仓的操作入口 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseOperations; |
|
|
|
import common.ecommerce.warehouse.sdk.WarehouseOperations; |
|
|
|
@ -383,7 +223,7 @@ WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); |
|
|
|
|
|
|
|
|
|
|
|
后面所有 `wh.xxx()` 都从这个对象出发。 |
|
|
|
后面所有 `wh.xxx()` 都从这个对象出发。 |
|
|
|
|
|
|
|
|
|
|
|
## 4.2 验证能跑通 |
|
|
|
## 2.2 验证能跑通 |
|
|
|
|
|
|
|
|
|
|
|
**只读,不改任何数据**: |
|
|
|
**只读,不改任何数据**: |
|
|
|
|
|
|
|
|
|
|
|
@ -403,7 +243,7 @@ for (WarehouseFacility w : warehouses) { |
|
|
|
| 现象 | 原因 | |
|
|
|
| 现象 | 原因 | |
|
|
|
|---|---| |
|
|
|
|---|---| |
|
|
|
| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 | |
|
|
|
| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 | |
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#五我要做的事能不能做)) | |
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#三我要做的事能不能做)) | |
|
|
|
| `http 401` / token 错误 | `ChannelSecret` 字段填错 | |
|
|
|
| `http 401` / token 错误 | `ChannelSecret` 字段填错 | |
|
|
|
| 超时 | 端点不通;易达云首次调用慢,重试一次 | |
|
|
|
| 超时 | 端点不通;易达云首次调用慢,重试一次 | |
|
|
|
|
|
|
|
|
|
|
|
@ -412,7 +252,7 @@ for (WarehouseFacility w : warehouses) { |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 五、我要做的事能不能做? |
|
|
|
# 三、我要做的事能不能做? |
|
|
|
|
|
|
|
|
|
|
|
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 | |
|
|
|
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 | |
|
|
|
|---|---|:---:|:---:|:---:|:---:| |
|
|
|
|---|---|:---:|:---:|:---:|:---:| |
|
|
|
@ -442,11 +282,11 @@ for (WarehouseFacility w : warehouses) { |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 六、按任务 |
|
|
|
# 四、按任务 |
|
|
|
|
|
|
|
|
|
|
|
> 以下假设 `wh` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 |
|
|
|
> 以下假设 `wh` 已就绪(见 [2.1](#21-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 |
|
|
|
|
|
|
|
|
|
|
|
## 6.1 发货:建出库单 → 拿面单 |
|
|
|
## 4.1 发货:建出库单 → 拿面单 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
import common.ecommerce.shared.model.Platform; |
|
|
|
import common.ecommerce.shared.model.Platform; |
|
|
|
@ -504,7 +344,7 @@ for (PackageResult p : pkgs) { |
|
|
|
3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`) |
|
|
|
3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`) |
|
|
|
4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求 |
|
|
|
4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求 |
|
|
|
|
|
|
|
|
|
|
|
## 6.2 查物流轨迹 |
|
|
|
## 4.2 查物流轨迹 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
List<TrackEvent> events = wh.track("1Z999AA10123456784"); |
|
|
|
List<TrackEvent> events = wh.track("1Z999AA10123456784"); |
|
|
|
@ -518,7 +358,7 @@ info.events(); |
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。 |
|
|
|
**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。 |
|
|
|
|
|
|
|
|
|
|
|
## 6.3 取消出库单 |
|
|
|
## 4.3 取消出库单 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
CancelEligibility e = wh.outbound().checkCancel( |
|
|
|
CancelEligibility e = wh.outbound().checkCancel( |
|
|
|
@ -538,7 +378,7 @@ if (e == CancelEligibility.FREE) { |
|
|
|
**⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`; |
|
|
|
**⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`; |
|
|
|
`BLOCKED` 抛 `OutboundCancelBlockedException`。 |
|
|
|
`BLOCKED` 抛 `OutboundCancelBlockedException`。 |
|
|
|
|
|
|
|
|
|
|
|
## 6.4 退货 |
|
|
|
## 4.4 退货 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
import common.ecommerce.warehouse.enums.ReturnDealMethod; |
|
|
|
import common.ecommerce.warehouse.enums.ReturnDealMethod; |
|
|
|
@ -569,7 +409,7 @@ boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号 |
|
|
|
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` / |
|
|
|
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` / |
|
|
|
`returnReason`(传了直接报错)。 |
|
|
|
`returnReason`(传了直接报错)。 |
|
|
|
|
|
|
|
|
|
|
|
## 6.5 库存同步 |
|
|
|
## 4.5 库存同步 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
Page<InventorySnapshot> page = wh.inventory().query( |
|
|
|
Page<InventorySnapshot> page = wh.inventory().query( |
|
|
|
@ -593,7 +433,7 @@ InventorySyncStrategy strategy = wh.inventorySyncStrategy(); |
|
|
|
- **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1) |
|
|
|
- **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1) |
|
|
|
- 易达云没有时间维度,`updatedAfter` 不生效 |
|
|
|
- 易达云没有时间维度,`updatedAfter` 不生效 |
|
|
|
|
|
|
|
|
|
|
|
## 6.6 商品主数据 |
|
|
|
## 4.6 商品主数据 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
WarehouseProduct p = WarehouseProduct.builder() |
|
|
|
WarehouseProduct p = WarehouseProduct.builder() |
|
|
|
@ -633,7 +473,7 @@ Page<ProductInfo> page = wh.queryProducts( |
|
|
|
- 易达云不带时间窗只查最近一个月 |
|
|
|
- 易达云不带时间窗只查最近一个月 |
|
|
|
- 运去哪不支持条码 / 时间窗过滤,传了本地报错 |
|
|
|
- 运去哪不支持条码 / 时间窗过滤,传了本地报错 |
|
|
|
|
|
|
|
|
|
|
|
## 6.7 对账:拉费用明细 |
|
|
|
## 4.7 对账:拉费用明细 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
// ① 账户流水 |
|
|
|
// ① 账户流水 |
|
|
|
@ -664,7 +504,7 @@ List<FeeEstimateResult> quotes = wh.fees().estimate(FeeEstimateQuery.builder() |
|
|
|
|
|
|
|
|
|
|
|
**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。 |
|
|
|
**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。 |
|
|
|
|
|
|
|
|
|
|
|
## 6.8 打单:箱唛 / BOL |
|
|
|
## 4.8 打单:箱唛 / BOL |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
import common.ecommerce.warehouse.enums.CaseMarkPaperSize; |
|
|
|
import common.ecommerce.warehouse.enums.CaseMarkPaperSize; |
|
|
|
@ -699,13 +539,13 @@ b.statusName(); // 如「已妥投」 |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 七、几条贯穿全局的规则 |
|
|
|
# 五、几条贯穿全局的规则 |
|
|
|
|
|
|
|
|
|
|
|
## 7.1 单位:尺寸 cm、重量 g |
|
|
|
## 5.1 单位:尺寸 cm、重量 g |
|
|
|
|
|
|
|
|
|
|
|
字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。 |
|
|
|
字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。 |
|
|
|
|
|
|
|
|
|
|
|
## 7.2 SKU:到底传哪一个(最容易错) |
|
|
|
## 5.2 SKU:到底传哪一个(最容易错) |
|
|
|
|
|
|
|
|
|
|
|
**所有地方都用「建档时下发给仓方的那一串」。** |
|
|
|
**所有地方都用「建档时下发给仓方的那一串」。** |
|
|
|
|
|
|
|
|
|
|
|
@ -723,7 +563,7 @@ b.statusName(); // 如「已妥投」 |
|
|
|
|
|
|
|
|
|
|
|
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。 |
|
|
|
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。 |
|
|
|
|
|
|
|
|
|
|
|
## 7.3 分页 |
|
|
|
## 5.3 分页 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
String cursor = null; |
|
|
|
String cursor = null; |
|
|
|
@ -738,15 +578,15 @@ do { |
|
|
|
- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异 |
|
|
|
- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异 |
|
|
|
- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜 |
|
|
|
- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜 |
|
|
|
|
|
|
|
|
|
|
|
## 7.4 金额 |
|
|
|
## 5.4 金额 |
|
|
|
|
|
|
|
|
|
|
|
一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。 |
|
|
|
一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。 |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
# 八、出错了怎么办 |
|
|
|
# 六、出错了怎么办 |
|
|
|
|
|
|
|
|
|
|
|
## 8.1 五类异常 |
|
|
|
## 6.1 五类异常 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
try { |
|
|
|
try { |
|
|
|
@ -773,7 +613,7 @@ try { |
|
|
|
| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 | |
|
|
|
| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 | |
|
|
|
| `OutboundCancelBlockedException` | 不能取消 | ❌ | |
|
|
|
| `OutboundCancelBlockedException` | 不能取消 | ❌ | |
|
|
|
|
|
|
|
|
|
|
|
## 8.2 异常里有什么 |
|
|
|
## 6.2 异常里有什么 |
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
```java |
|
|
|
catch (WarehouseException e) { |
|
|
|
catch (WarehouseException e) { |
|
|
|
@ -789,18 +629,18 @@ catch (WarehouseException e) { |
|
|
|
|
|
|
|
|
|
|
|
> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。 |
|
|
|
> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。 |
|
|
|
|
|
|
|
|
|
|
|
## 8.3 常见报错对照 |
|
|
|
## 6.3 常见报错对照 |
|
|
|
|
|
|
|
|
|
|
|
| 报错 | 原因 | 怎么办 | |
|
|
|
| 报错 | 原因 | 怎么办 | |
|
|
|
|---|---|---| |
|
|
|
|---|---|---| |
|
|
|
| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) | |
|
|
|
| `requires an idempotencyStore` | 没配 | 见 [1.1](#11-实现两个-spi) | |
|
|
|
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` | |
|
|
|
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` | |
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#五我要做的事能不能做) | |
|
|
|
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#三我要做的事能不能做) | |
|
|
|
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` | |
|
|
|
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` | |
|
|
|
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) | |
|
|
|
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [5.2](#52-sku到底传哪一个最容易错) | |
|
|
|
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` | |
|
|
|
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` | |
|
|
|
|
|
|
|
|
|
|
|
## 8.4 幂等:重复调用安全吗 |
|
|
|
## 6.4 幂等:重复调用安全吗 |
|
|
|
|
|
|
|
|
|
|
|
写操作都安全,同样单号调两次不会重复下单: |
|
|
|
写操作都安全,同样单号调两次不会重复下单: |
|
|
|
|
|
|
|
|
|
|
|
|