You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

20 KiB

common-ecommerce 操作手册

面向接入本 SDK 的宿主开发者。本文只讲怎么调、参数怎么传。 设计原理见 GUIDE.md,架构图与包结构见 README.md。


目录

  1. 依赖与坐标
  2. 三个第一步
  3. 连接信息:域名与密钥
  4. 拉取订单
  5. 拉取商品 / Listing
  6. 拉取店铺列表(聚合器)
  7. 增量同步与水位线
  8. 写操作与幂等
  9. 查询能力矩阵
  10. 异常与重试
  11. 宿主必须实现的 SPI
  12. 常见错误对照表

一、依赖与坐标

<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 级,全平台共用) 同左 同左 同左 ❌

写接口没有测试环境,联调时只跑查询。