# 沃尔玛直连接入(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(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. 接入 ```java 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](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。 --- ## 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 契约测试(无网络) ```bash 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 沙箱探针(读写开关分离) ```bash 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) 沃尔玛没有批量标发接口,**一次一个订单**;支持部分发货。 ```java 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 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,细到**退货行 × 费用项**: ```java 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——沃尔玛商品写入的主流方式。 ```java 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` 取消退货 | 同上 |