20 KiB
common-ecommerce 操作手册
面向接入本 SDK 的宿主开发者。本文只讲怎么调、参数怎么传。 设计原理见
GUIDE.md,架构图与包结构见README.md。
目录
- 依赖与坐标
- 三个第一步
- 连接信息:域名与密钥
- 拉取订单
- 拉取商品 / Listing
- 拉取店铺列表(聚合器)
- 增量同步与水位线
- 写操作与幂等
- 查询能力矩阵
- 异常与重试
- 宿主必须实现的 SPI
- 常见错误对照表
一、依赖与坐标
<dependency>
<groupId>ecommerce</groupId>
<artifactId>channel-sdk-core</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>common-ecommerce-lingxing</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<!-- 仅测试用 -->
<dependency>
<groupId>ecommerce</groupId>
<artifactId>sdk-testkit</artifactId>
<version>1.0.0-SNAPSHOT</version>
<scope>test</scope>
</dependency>
要求 JDK 1.8。
二、三个第一步
调用任何接口之前,宿主必须先提供三样东西。
2.1 账户仓库 ChannelAccountRepository
SDK 靠它把 AccountKey 解析成账户配置。
public interface ChannelAccountRepository {
Optional<ChannelAccount> findByKey(String provider, String platform, String omsStoreId);
List<ChannelAccount> findByOmsStoreId(String omsStoreId);
}
注意:provider / platform 传的是枚举 name,如 "LINGXING" / "WALMART_SC"。
2.2 账户配置 ChannelAccount
ChannelAccount account = ChannelAccount.builder()
// 三件套:通道 + 平台 + 你自己的店铺 ID
.key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"))
// 平台侧店铺 ID(领星是 store_id / 亚马逊是 sid)
.externalStoreId("1108413237731")
// 领星 platform_code;直连账户不填
.platformCode(10008)
// 密钥引用(宿主侧密钥条目的标识);真实密钥经 ChannelConnection 传入,见第三节
.credentialRef("kms://oms/lingxing/store-001")
// 市场当地时区,必须是合法 IANA 时区
.marketplaceZone("America/Los_Angeles")
// 店铺币种
.currency("USD")
.build();
| 字段 | 必填 | 说明 |
|---|---|---|
key |
✅ | provider + platform + omsStoreId,SDK 的隔离维度 |
externalStoreId |
✅ | 平台店铺 ID。领星传 store_id;亚马逊 SC 传 sid |
platformCode |
领星必填 | 见 platform_code 对照 |
credentialRef |
✅ | 密钥引用标识,不是密钥本身;真实密钥经 ChannelConnection 传入 |
marketplaceZone |
✅ | 必须是 ZoneId.of(...) 能解析的值 |
currency |
✅ | ISO 4217 |
2.3 构建门面
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo) // 必需
.clock(Clock.systemUTC()) // 可选,默认 UTC
.idempotencyStore(idempotencyStore) // 写操作必需
.idempotencyOwner("oms-node-1") // 多实例时区分
.register(new LingxingAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
.build();
build() 立刻失败的情况:
| 缺失 | 异常 |
|---|---|
accountRepository |
ChannelSdk requires an accountRepository |
| 一个适配器都没注册 | ChannelSdk requires at least one adapter or adapter factory |
同一 provider + platform 注册两次 |
duplicate adapter for ... |
门面是单例。适配器里缓存了限流器状态,每次调用都
new会导致限流失效。
三、连接信息:域名与密钥
SDK 不保存端点、不读配置、不读环境变量。 每次调用都要由调用方传入。
ChannelConnection conn = ChannelConnection.of(
"https://openapi.lingxing.com", // 端点
ChannelSecret.builder()
.appKey("你的 appId") // 领星 AppID
.appSecret("你的 appSecret") // 领星 AppSecret
.build());
credentialRef 只是账户上的标识,SDK 不会拿它去取密钥;真实密钥就在上面的 ChannelSecret 里。
各平台需要的凭据字段
| 平台 | 需要的字段 |
|---|---|
| 领星 | appKey(= AppID)、appSecret |
| 亚马逊直连 | clientId、clientSecret、refreshToken |
| 沃尔玛 | clientId、clientSecret |
安全要求:
ChannelSecret的toString()不打印密钥;日志里只用fingerprint()- 不要把
ChannelSecret序列化进日志或异常信息 - 生产环境从 KMS / Vault 取,不要硬编码
四、拉取订单
4.1 单次查询
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
Page<SalesOrder> page = sdk.salesOrders(key, conn).pull(
SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z")) // 必填,UTC
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z")) // 可选,缺省取现在
.pageSize(100) // 平台上限内自动截断
.build());
for (SalesOrder order : page.items()) {
order.channelOrderId(); // 平台单号,参与 canonicalKey
order.status(); // 平台原始状态(见下方说明)
order.totalAmount(); // Money:BigDecimal + Currency
order.occurredAt().utc(); // 下单时间,UTC 真值
order.lines(); // 明细行
}
4.2 翻页
while (page.nextCursor() != null) {
page = sdk.salesOrders(key, conn).pull(
query.toBuilder().cursor(page.nextCursor()).build());
}
nextCursor == null 表示结束。游标是不透明字符串,不要解析它的内容。
4.3 入参说明 SalesOrderQuery
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
updatedAfter |
Instant |
✅ | 时间窗起点,UTC。领星按「更新时间」过滤 |
updatedBefore |
Instant |
时间窗终点,UTC;缺省取调用时刻 | |
pageSize |
int |
每页条数。领星订单上限 500,Listing 上限 1000 | |
cursor |
String |
上一页返回的 nextCursor |
4.4 出参说明 SalesOrder
| 字段 | 类型 | 说明 |
|---|---|---|
omsStoreId |
String |
你的店铺 ID |
channelOrderId |
String |
平台单号。canonicalKey 的一部分 |
status |
String |
平台原始状态值,未归一化 |
buyerName |
String |
领星订单列表接口不返回,为 null |
shipToCountryCode |
String |
收货国家二字码 |
lines |
List<OrderLine> |
明细行 |
totalAmount |
Money |
订单总额 |
occurredAt |
PlatformTime |
下单时间(UTC / 当地 / 北京三轴) |
sourceProvider |
ChannelProvider |
来源通道,不进业务主键 |
sourceAccountId |
String |
平台侧店铺 ID |
关于 status:目前保留平台原值,没做跨平台归一。领星订单返回数字(1 同步中 … 6 已发货 … 9 平台发货),宿主需要自己映射。
4.5 单条详情
SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789");
只有亚马逊 SC / VC(含 FBM 路由)实现了详情;其它子平台抛
UnsupportedCapabilityException。商品详情(sdk.products(key, conn).get(sku))全部未实现,
会抛 ChannelException: lingxing product detail is not implemented yet。
五、拉取商品 / Listing
Page<ProductListing> page = sdk.products(key, conn).pull(
ProductQuery.builder()
.updatedAfter(Instant.parse("2026-10-01T00:00:00Z")) // 可选
.updatedBefore(Instant.parse("2026-10-30T00:00:00Z")) // 可选
.pageSize(100)
.build());
for (ProductListing p : page.items()) {
p.platformSku(); // 平台侧 SKU(领星亚马逊取 seller_sku)
p.title(); // 标题
p.status(); // 原始状态值
p.updatedAt(); // 更新时间
p.imageUrls(); // 图片列表
}
入参说明 ProductQuery
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
updatedAfter |
Instant |
按「报表更新时间」过滤;亚马逊按 UTC 时间 | |
updatedBefore |
Instant |
同上 | |
pageSize |
int |
亚马逊 Listing 上限 1000 | |
cursor |
String |
上一页游标 | |
searchField |
ProductSearchField |
按 SKU 搜索的维度:PLATFORM_SKU / LOCAL_SKU;不传表示不按 SKU 搜 |
|
searchValue |
String |
单个模糊匹配值;设了 searchField 才能用 |
|
searchValues |
List<String> |
多个精确匹配值;与 searchValue 互斥(同时设置时会抛异常) |
按 SKU 搜索的示例:
Page<ProductListing> page = sdk.products(key, conn).pull(
ProductQuery.builder()
.searchField(ProductSearchField.PLATFORM_SKU)
.searchValues(Arrays.asList("SKU-1", "SKU-2"))
.build());
领星会把上面的维度翻译成各子平台自己的 searchField 编码(见 LingxingProductSearchMapper)。
Target 的 LOCAL_SKU 编码尚未实测确认,目前会显式抛 UnsupportedOperationException,不会静默返回错数据。
当前支持范围
| provider | 平台 | 是否支持 |
|---|---|---|
| LINGXING | 亚马逊 SC | ✅ |
| LINGXING | 亚马逊 VC / 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress | ✅ |
| LINGXING | 其它子平台(BestBuy / AEPH / Michaels / Echo / Losdlius / Custom …) | ❌ 商品接口未接入 |
| DIRECT | — | ❌ 暂无直连适配器 |
不支持时会抛 ChannelException.UnsupportedCapabilityException: PRODUCT。
六、拉取店铺列表(聚合器)
聚合器(领星)下挂多家子店铺,调用方需要先把它们拉出来,再逐店构造 ChannelAccount。
AccountKey aggregatorKey = AccountKey.of(
ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent");
```java
List<SubChannel> shops = sdk.subChannels(aggregatorKey, conn);
for (SubChannel shop : shops) {
shop.platformCode(); // 10001(亚马逊 SC)
shop.externalStoreId(); // 领星店铺 sid,如 "1519"
shop.platform(); // Platform.AMAZON_SC
shop.name(); // 店铺名
shop.status(); // 授权状态原值
shop.region(); // 站点简称,如 na
// 用它构造账户
ChannelAccount account = ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.LINGXING, shop.platform(), "oms-amz-" + shop.externalStoreId()))
.externalStoreId(shop.externalStoreId())
.platformCode(shop.platformCode())
.credentialRef("kms://oms/lingxing/amz")
.marketplaceZone("America/Los_Angeles")
.currency("USD")
.build();
accountRepo.save(account);
}
当前支持范围
| provider | 平台 | 接口 |
|---|---|---|
| LINGXING | 亚马逊 SC / VC | /erp/sc/data/seller/lists ✅ |
| LINGXING | 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress / Wayfair / Mirakl / BestBuy / AEPH / Michaels / Echo / Losdlius / Custom | 多平台店铺接口 /pb/mp/shop/v2/getSellerList ✅ |
返回的店铺会过滤掉非正常状态(领星 status != 1 的店铺)。
七、增量同步与水位线
单次查询不推进水位线;需要增量就用 SyncEngine。
String stream = SyncSpec.STREAM_SALES_ORDERS;
// ① 首次:先写一个起点,否则 SyncEngine 会抛 IllegalStateException
if (cursorStore.get(ChannelProvider.LINGXING, "oms-wm-001", stream) == null) {
cursorStore.advance(ChannelProvider.LINGXING, "oms-wm-001", stream,
Instant.parse("2026-01-01T00:00:00Z"));
}
// ② 配置同步维度
SyncSpec spec = SyncSpec.of(
ChannelProvider.LINGXING,
"oms-wm-001",
stream,
Duration.ofMinutes(10)); // 重叠窗口,防边界丢单
// ③ 跑一次
Instant to = Instant.now();
SyncResult result = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to,
(from, cursor) -> sdk.salesOrders(key, conn).pull(
SalesOrderQuery.builder()
.updatedAfter(from)
.updatedBefore(to)
.cursor(cursor)
.build()));
result.pages(); // 拉了几页
result.items(); // 落了几条
result.watermarkAdvanced(); // 水位线是否推进
行为说明
| 行为 | 说明 |
|---|---|
| 起点计算 | from = 上次水位线 - overlap |
| 终点 | 你传入的 to,不是 now() |
| 推进时机 | 整批成功才推进;中途抛异常水位线不动 |
| 调度 | SDK 不持有线程,由宿主调度器触发 |
Sink 实现要点
public void upsertSalesOrders(Page<SalesOrder> page) {
for (SalesOrder o : page.items()) {
String key = CanonicalKeys.salesOrder(platform, o.omsStoreId(), o.channelOrderId());
// INSERT ... ON DUPLICATE KEY UPDATE
// 唯一索引建在 canonicalKey 上
}
}
必须按 canonicalKey upsert,否则直连和领星拉到同一单会变成两行。
八、写操作与幂等
所有写操作必须过 IdempotencyGuard。
WriteScope scope = WriteScope.of(
ChannelProvider.LINGXING, // 本次走哪条通道
Platform.WALMART_SC,
"oms-wm-001", // 业务店铺
"1108413237731", // 平台店铺 ID
"markShipped", // 动作名
"PO-123456789:pkg-1"); // 业务自然键
WriteResult<ShipResult> result = sdk.writes().execute(
scope,
() -> adapter.markShipped(ctx, command), // 真正调平台
ShipResult::shipmentId); // 结果引用
if (result.alreadyCompleted()) {
// 之前已成功,用 result.resultRef() 返回给上游,不算失败
}
参数说明 WriteScope.of
| 参数 | 说明 |
|---|---|
provider |
本次通道 |
platform |
业务平台 |
omsStoreId |
业务店铺(跨 provider) |
externalStoreId |
平台店铺 ID(单 provider 内) |
action |
动作名,如 markShipped / refund |
businessRef |
业务自然键。退款禁止用金额,用 returnId:itemId:refundRequestId |
行为表
| 情形 | 结果 |
|---|---|
| 首次调用 | EXECUTED |
| 同 provider 重复 | ALREADY_COMPLETED,不调平台 |
| 另一 provider 重复 | CrossProviderConflictException |
| 并发 | IdempotencyConflictException |
抛 retryable=true 异常 |
记 FAILED_RETRYABLE,可重跑 |
抛 retryable=false 异常 |
记 FAILED_FINAL,需人工 |
| 崩溃窗口(平台已写、业务键未记) | provider 键命中,回放,不重复写 |
九、查询能力矩阵
只读,不发请求。
CapabilityReport caps = sdk.capabilities(key);
caps.supports(Capability.SALES_ORDER); // true / false
caps.supported(); // 支持的能力集合
caps.unsupported(); // 不支持的能力集合
聚合器按子平台判断:同一个领星适配器,沃尔玛店和 eBay 店的答案不同。
SDK 不会自动换 provider。能力不足时抛 UnsupportedCapabilityException,由调用方决定换账户还是走人工。
十、异常与重试
| 异常 | 触发 | 可重试 |
|---|---|---|
AuthException |
401/403、token 失效、签名错误 | 刷新后 1 次 |
RateLimitException |
429 / 领星 3001008 |
是,带 retryAfterMillis() |
TransientException |
5xx / 网络 / 超时 | 是 |
ValidationException |
4xx / 映射失败 | 否 |
PlatformBusinessException |
平台业务码 | 视码 |
ChannelException.UnsupportedCapabilityException |
能力缺失 | 否 |
IdempotencyConflictException |
并发重复写 | 否 |
CrossProviderConflictException |
已由另一 provider 完成 | 否 |
所有异常都带 provider / omsStoreId / operation / requestId / rawResponse,排查时先看这几个字段。
try {
sdk.salesOrders(key, conn).pull(query);
} catch (RateLimitException e) {
Thread.sleep(e.retryAfterMillis());
} catch (TransientException e) {
// 退避后重试
} catch (AuthException e) {
// 刷新 token 后重试一次,仍失败则停用账户
}
SDK 自身不做重试,退避策略由宿主决定。
十一、宿主必须实现的 SPI
| SPI | 作用 | 哪个操作需要 |
|---|---|---|
ChannelAccountRepository |
读账户配置 | 全部 |
TokenStore |
token 读写(宿主加密) | 全部 |
LockProvider |
token 刷新防击穿 | 全部 |
SyncCursorStore |
水位线 | 增量同步 |
Sink |
领域对象落库 | 增量同步 |
IdempotencyStore |
幂等键抢占与结果 | 写操作 |
SDK 不碰数据库。所有持久化都由宿主实现上述接口。
十二、常见错误对照表
| 现象 | 原因 | 处理 |
|---|---|---|
channel account not configured |
findByKey 没查到 |
检查 provider/platform/omsStoreId 三个值是否与账户一致 |
no adapter registered for ... |
该 provider + platform 没注册适配器 |
检查 register(...);领星工厂覆盖 16 个子平台,不含 WALMART_1P |
duplicate adapter for ... |
同一 provider + platform 注册了两次 |
去掉重复的 register |
UnsupportedCapabilityException |
适配器不声明该能力 | 先 capabilities() 判断,或换 provider |
lingxing sub platform not implemented: X |
该子平台没有注册到 LingxingSubPlatforms |
对照 LingxingSubPlatformDefaults.all(...) 的注册清单 |
lingxing code=102 msg=参数不合法 |
请求参数不对 | 检查 sid / platform_code / 时间格式 |
lingxing code=2001013 app authentication failed |
AppID/AppSecret 错误 | 检查凭据;确认出口 IP 在白名单 |
lingxing code=3001008 |
触发限流 | 该接口 qps=1,必须串行调用 |
lingxing code=2001006/2001007 |
签名错误/过期 | 检查签名参数与系统时间 |
token refresh in progress |
另一实例正在刷新 | 属于正常并发保护,稍后重试 |
previous attempt failed permanently |
幂等记录为 FAILED_FINAL |
人工介入后清理记录 |
附录:领星 platform_code 对照
| platform_code | Platform |
|---|---|
| 10001 | AMAZON_SC |
| 10035 | AMAZON_VC |
| 10003 | EBAY |
| 10005 / 10031 | AEPH |
| 10008 | WALMART_SC |
| 10010 | WAYFAIR |
| 10011 | TIKTOK |
| 10021 / 10027 / 10028 | SHEIN |
| 10022 / 10024 | TEMU |
| 10029 / 10030 | ALIEXPRESS |
| 10034 | MIRAKL |
| 10009 / 10017 / 其它 | CUSTOM(同一码下混有多个业务平台,无法用一个枚举表示) |
业务平台以账户的
AccountKey.platform为准,这张表只用于从店铺列表 / 订单行反推。 Target / BestBuy / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码。
附录:当前实现状态
| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct |
|---|---|---|---|---|---|
| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ |
| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ |
| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ |
| 店铺列表 | ✅ | ✅ | ✅ | ✅ | — |
| 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ |
| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ |
| 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
| 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
写接口没有测试环境,联调时只跑查询。