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.
lml e3a087dfc8 fix(walmart): 退货详情与发货信息改用官方存在的接口 1 day ago
..
README.md fix(walmart): 退货详情与发货信息改用官方存在的接口 1 day ago

README.md

沃尔玛直连接入(channel-sdk-walmart)

模块:channel-sdk-walmart 通道:ChannelProvider.DIRECT 平台:Platform.WALMART_SC 协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 https://sandbox.walmartapis.com

已接:订单 / 商品 / 售后(读)+ 标发 / 退款(写)+ 商品 Feed(提交与状态查询)。 未接:单个商品创建/更新(Item Spec 版本管理)、创建退货 / 取消退货(无报文)、WALMART_1P、结算、Webhook。


1. 目录结构

channel-sdk-walmart/
├── src/main/java/common/ecommerce/walmart/
│   ├── WalmartConstants.java          沙箱/生产端点、路径、请求头名、分页上限、时间窗上限
│   ├── adapter/
│   │   ├── WalmartAdapter.java        SalesOrderCapable + ProductCapable + AfterSaleCapable
│   │   └── WalmartAdapterFactory.java DIRECT + WALMART_SC
│   ├── auth/WalmartTokenClient.java   POST /v3/token(Basic Auth + form)
│   ├── http/
│   │   ├── WalmartRequestFactory.java 公共头 + token 头 + query 拼接
│   │   └── WalmartErrors.java         两种错误格式 → Auth/Transient/RateLimit/Validation
│   ├── mapper/
│   │   ├── WalmartOrderMapper.java    订单 → SalesOrder(行状态聚合、金额汇总、单价折分)
│   │   ├── WalmartProductMapper.java  ItemResponse → ProductListing(shelf 二次解析)
│   │   ├── WalmartReturnMapper.java   returnOrder → List<AfterSale>(1 → N)
│   │   └── WalmartShipmentMapper.java shipping 响应 → 行级发货记录
│   ├── enums/
│   │   ├── WalmartOrderStatus.java    行状态 → 订单级状态聚合
│   │   ├── WalmartPublishedStatus.java publishedStatus + lifecycleStatus → ProductStatus
│   │   └── WalmartReturnType.java     returnType → AfterSaleType
│   └── dto/                           一个接口一个文件,字段名照抄沃尔玛
└── src/test/
    ├── java/.../adapter/              订单 / 商品 / 售后契约测试
    ├── java/.../http/                 错误解析
    ├── java/.../enums/                状态映射边界
    ├── java/.../WalmartFacadeTest     门面集成
    ├── java/.../probe/                沙箱探针(默认跳过)
    └── resources/fixtures/walmart/    夹具,来源见 §5

2. 接入

ChannelSdk sdk = ChannelSdk.builder()
        .accountRepository(repo)
        .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
        .register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
        .build();

AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001");

ChannelConnection conn = ChannelConnection.of(
        "https://sandbox.walmartapis.com",
        ChannelSecret.builder()
                .clientId("...")
                .clientSecret("...")
                .build());

ChannelAccount 上只需要 marketplaceZone(订单时间用)、currency;platformCode 对直连没有意义, 落库用 ChannelProvider.NO_PLATFORM_CODE。


3. 能力与限制

能力 状态
SALES_ORDER 订单列表 / 详情 ✅
PRODUCT 商品列表 / 详情 ✅
RETURNS 退货列表(按行展开) ✅
退货单详情 WalmartAdapter.getReturn ✅ 走列表接口 returnOrderId 过滤(官方无详情路由)
发货信息 WalmartAdapter.getShipping ✅ 走订单详情 trackingInfo(官方无 GET shipping 路由)
MARK_SHIPPED 标发 ✅(⚠ 沙箱 404,见 §7)
REFUND 退款 ✅(⚠ 沙箱 404,见 §8)
商品 Feed 提交 / 状态查询 ✅ 扩展方法(⚠ 沙箱 520,见 §9)
单个商品创建 / 更新 ❌ 官方 API 不存在,商品写入走 Feed

过滤条件的支持面比领星窄,不支持的组合一律抛 ValidationException,见 docs/channel/api-reference.md §15A.6。


4. 增量同步

沃尔玛订单只有创建时间过滤,没有更新时间。SDK 给了两条明确的路,不混用:

场景 调用
拉新单(水位线增量) sdk.salesOrders(key, conn).pull(query),updatedAfter/updatedBefore 即创建时间窗
老单状态对账 WalmartAdapter.pullOpenOrders(ctx, statuses, createdAfter, cursor),按 Created/Acknowledged 拉开放单

SyncEngine 目前只支持 syncSalesOrders;商品的 FULL_PULL_DIFF 由宿主自己比对 (ProductCapable.syncStrategy() 已声明)。

时间窗上限 180 天(📖 待官方核实),超了本地拒绝,不静默截断。


5. 测试与探针

5.1 契约测试(无网络)

mvn -pl channel-sdk-walmart -am test
测试 覆盖
WalmartOrderTest 请求头、创建时间窗、游标、token 缓存与 401 重试、行状态聚合、金额汇总、地址映射
WalmartDirtyDataTest 缺单号/下单时间的单被跳过、除不尽时 unitPrice 为 null、运费不冒充单价、多币种不给总额、退货缺单号整单丢弃
WalmartProductTest limit 上限、sku 搜索、三种不支持过滤的报错、shelf 解析、状态组合
WalmartReturnTest 1 单拆 N 行、查询串型游标、退款金额回落、脏时间不卡页
WalmartErrorsTest 两种错误格式、401/429/5xx/SYSTEM_ERROR 分类、报文截断
WalmartStatusMappingTest 精确匹配(不做 contains)、未知值、空值
WalmartExtraQueryTest 退货详情、发货信息两个扩展查询
WalmartFacadeTest 门面路由、能力矩阵、未实现写能力被拒、未注册平台报错
WalmartMarkShippedTest 标发报文(单数包装 / 固定状态 / 字符串数量 / ISO 时间)、非标准承运商、响应映射、幂等键稳定性
WalmartRefundTest 退款报文逐字段对齐 §5.3 示例、多行多费用项、非整数行号本地拒绝
WalmartFeedTest Feed 提交报文头、feedId 返回、状态计数与逐商品明细、错误压行

5.2 沙箱探针(读写开关分离)

mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
    -Dwalmart.probe=true \
    -Dwalmart.probe.clientId=你的clientId \
    -Dwalmart.probe.clientSecret=你的clientSecret \
    -Dtest=WalmartProbeTest test

可选参数:-Dwalmart.probe.baseUrl=...(打生产,只读)、-Dwalmart.probe.sku=...。

探针打印每一条请求/响应(token 只打前 12 位),对已知的 404 / 固定条数不断言失败, 唯一硬断言是 token 能换到。

探针跑完请核对这几件事,四项都确认后可以把 WalmartConstants 里的「📖 待核实」注释去掉:

  1. x-current-token-count 的实际值(确认缓存复用是否必要)
  2. createdStartDate 的真实最大回溯窗口
  3. charges 的真实结构(沙箱样例有 ItemPrice + Shipping 两条)
  4. 退货 nextCursor 的形态是否始终是查询串

5.3 夹具来源

src/test/resources/fixtures/walmart/:

文件 来源
orders/list.json 文档 §4.1 实测样例(2 条)+ 补了 3 条:部分发货、已发完仍残留 Created、多件(整行金额折单价)
orders/detail.json 文档 §4.2 实测样例
items/list.json 文档 §3.1 实测样例 + 补了 PUBLISHED/ACTIVE 与 PUBLISHED/RETIRED 两条
returns/list.json 文档 §5.1 实测样例 + 补了第二行(覆盖无 chargeTotals、无面单分组)
errors/*.json 文档 §1.5 两种错误格式原文
token/success.json 文档 §2.1 实测结构(token 值为占位)

6. 已知问题

问题 状态
沙箱商品详情 404 生产环境再验
GET /v3/returns/{id} 官方无此路由;getReturn 改走列表接口 returnOrderId 过滤
GET /v3/orders/{id}/shipping 官方无此路由(只有 POST 标发);getShipping 改读订单详情 trackingInfo
沙箱退款 404 已按文档实现,生产再验
沙箱 Feed 520 提交 / 状态查询已按文档实现(submitFeed / getFeedStatus),生产再验
沙箱过滤参数不生效 以生产为准
订单列表 status 过滤是否生效 探针未覆盖写操作,读侧以生产为准
pullOpenOrders 的 status=Created,Acknowledged 多值是否成立 未验证,文档只给了单值示例;探针跑通后确认
订单翻页时是否仍需带时间窗 未验证,退货游标是完整查询串,暗示游标已蕴含条件
createdStartDate 最大回溯窗口 代码按 180 天硬校验,待探针核实
x-current-token-count 实际值 待探针核实

7. 标发(MARK_SHIPPED)

沃尔玛没有批量标发接口,一次一个订单;支持部分发货。

ShipmentCommand cmd = ShipmentCommand.builder()
        .channelOrderId("108816631915371")
        .line(ShipmentCommand.Line.builder()
                .lineNumber("1")                 // 必须与订单详情一致
                .quantity(2)                     // 本次实发
                .carrier("UPS")                  // 或 carrierName("非标准承运商")
                .methodCode("Standard")          // 必须与承运商方式对照表匹配
                .trackingNumber("1Z999...")
                // .shippedAt(...)                // 不传则取 ctx.clock()
                .build())
        .build();

// 写操作必须包在 sdk.writes() 里
WriteResult<ShipmentResult> r = sdk.writes().execute(
        WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC,
                "oms-wm-001", "wm-seller-01", "markShipped", cmd.businessRef()),
        () -> sdk.salesOrders(key, conn).markShipped(cmd),
        ShipmentResult::channelOrderId);

幂等键:ShipmentCommand.businessRef() = 订单号|行号:数量,行号:数量(行号排序)。 不带金额与跟踪号——换跟踪号属于修正,不应产生新动作;数量不同则是新的一次部分发货。

报文要求(依据官方 reference/shippingupdates schema):

字段 要求
lineNumber 与订单详情一致
status 固定 Shipped
statusQuantity.unitOfMeasurement 固定 EACH(官方枚举 EACH/EA)
statusQuantity.amount 字符串
trackingInfo.shipDateTime epoch 毫秒整数(官方 int64,不是 ISO 字符串)
trackingInfo.carrierName carrier 与 otherCarrier 至少一个
trackingInfo.methodCode 官方枚举:Standard / Express / OneDay / Freight / WhiteGlove / Value
trackingInfo.trackingNumber 必填
trackingInfo.trackingURL 可空;用 otherCarrier 时建议给
sellerOrderId 官方标必填(≤30 字符,印在退货面单上);适配器不强制,超长时省略而不是截断
intentToCancelOverride 客户已申请取消但仍要发货时传 true;默认不发
processMode 发货后只更新物流信息时传 PARTIAL_UPDATE;首次标发不传

DTO 上标了 @JsonInclude(NON_NULL),未设置字段不会被发成 null。


8. 退款(REFUND)

报文按文档 §5.3,细到退货行 × 费用项:

RefundCommand cmd = RefundCommand.builder()
        .afterSaleId("103738048909818825")
        .line(RefundCommand.Line.builder()
                .lineId("1")                       // 平台退货行号,必须是整数
                .charge(RefundCommand.Charge.builder()
                        .chargeName("ItemPrice")
                        .chargeType("PRODUCT")     // PRODUCT / FEE / SHIPPING
                        .amount(Money.of("119.95", "USD"))
                        .build())
                .build())
        .build();

sdk.writes().execute(
        WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC,
                "oms-wm-001", "wm-seller-01", "refund", "103738048909818825:1"),
        () -> sdk.afterSales(key, conn).refund(cmd),
        RefundResult::afterSaleId);

业务规则(文档 §5.3):部分售后由平台自动退款,只有 currentRefundStatus 需要卖家处理 (或 refundChannels 含 SELLER_MANUAL_REFUND)时才调用;调用前先查详情核对 refundedQty / cancellableQty,避免超退。

退货列表的官方过滤参数(reference/getreturns):

参数 说明
returnCreationStartDate / returnCreationEndDate 按退货单创建时间(ISO-8601)
returnLastModifiedStartDate / returnLastModifiedEndDate 按退货单修改时间(ISO-8601)
returnType PREORDER / REPLACEMENT / REFUND
status INITIATED / DELIVERED / COMPLETED
limit 默认 10,上限 200;没有 offset

统一模型 AfterSaleQuery.DateType 的映射:

  • AFTER_SALE_TIME → returnCreation*
  • UPDATE_TIME → returnLastModified*
  • PURCHASE_TIME → 没有对应参数,本地报错

行号不是整数时本地抛 ValidationException,不发请求。


9. 商品 Feed(扩展方法)

单商品写接口要管理 Item Spec 版本,先做 Feed——沃尔玛商品写入的主流方式。

WalmartAdapter wm = (WalmartAdapter) sdk.resolve(key);

String feedId = wm.submitFeed(ctx, WalmartFeedCommand.builder()
        .version("4.2")                        // 必须与后台开通版本一致
        .businessUnit("WALMART_US")
        .locale("en")                          // 默认 en
        .subCategory("OTHER")                  // 可选
        .item(itemPayload)                     // 结构见 Item Spec,原样透传
        .build());

WalmartFeedStatus status = wm.getFeedStatus(ctx, feedId, true);
if (status.isFinished()) {
    status.isFullySucceeded();                 // PROCESSED 且 itemsFailed == 0
    status.items();                            // 逐商品 SUCCESS / DATA_ERROR / SYSTEM_ERROR
}

商品数组原样透传,适配器只补 MPItemFeedHeader——不同 productType 的必填字段差异太大, 建模反而会挡住合法报文。


10. 未接入的接口

接口 原因
POST /v3/items 创建商品 报文只有「精简示例」,正式对接需按《Item Spec》生成;版本管理未定
PUT /v3/items/{sku} 更新商品 同上;且 PUT 是覆盖式,需先定「先查后写」的约定
POST /v3/returns 创建退货 文档只给路径,没有请求报文
POST /v3/returns/{id}/cancel 取消退货 同上