|
|
7 hours ago | |
|---|---|---|
| .. | ||
| README.md | 7 hours ago | |
README.md
沃尔玛直连接入(channel-sdk-walmart)
模块:
channel-sdk-walmart通道:ChannelProvider.DIRECT平台:Platform.WALMART_SC协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16)+ Walmart Developer Portal 官方文档/reference(2026-11 核对),沙箱https://sandbox.walmartapis.com退货单详情以官方 Returns Management API overview 为准:该页明确有GET /v3/returns/{returnOrderId},但 reference 目录未单列响应 schema。
已接(共 7 条路由):/v3/token 鉴权 + 商品列表 + 订单列表/详情 + 退货单列表/详情 + 退款 + 标发。
未接:商品详情、商品创建/更新(走 Feed,本期不做)、创建退货 / 取消退货(无报文)、
开放单对账、发货信息查询、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)
│ │ ├── WalmartRefundMapper.java RefundCommand → 退款报文;响应 → RefundResult
│ │ └── WalmartShipmentWriteMapper.java ShipmentCommand → 标发报文;响应 → ShipmentResult
│ ├── 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 商品列表 |
✅(单品查询未接,get() 显式报错) |
RETURNS 退货列表(按行展开) |
✅ |
退货单详情 WalmartAdapter.getReturn |
✅ GET /v3/returns/{returnOrderId}(overview 有定义,reference 未给 schema;兼容单条/列表/裸对象三种响应) |
MARK_SHIPPED 标发 |
✅(⚠ 沙箱 404,见 §7) |
REFUND 退款 |
✅(⚠ 沙箱 404,见 §8) |
| 商品详情 / 创建 / 更新、发货信息查询、开放单对账 | ❌ 本期不接 |
过滤条件的支持面比领星窄,不支持的组合一律抛 ValidationException,见
docs/channel/api-reference.md §15A.6。
4. 增量同步
沃尔玛订单只有创建时间过滤,没有更新时间。updatedAfter/updatedBefore 直接映射成
createdStartDate/createdEndDate,pull 的语义保持单一可预测;老单状态变化本期不做对账,
需要时用较大的创建时间窗重拉(平台不支持按更新时间过滤)。
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)、未知值、空值 |
WalmartReturnDetailTest |
退货单详情:真实路由、路径段编码、三种响应形状、404 透传 |
WalmartFacadeTest |
门面路由、能力矩阵、未实现写能力被拒、未注册平台报错 |
WalmartMarkShippedTest |
标发报文(单数包装 / 固定状态 / 字符串数量 / ISO 时间)、非标准承运商、响应映射、幂等键稳定性 |
WalmartRefundTest |
退款报文逐字段对齐 §5.3 示例、多行多费用项、非整数行号本地拒绝 |
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 里的「📖 待核实」注释去掉:
x-current-token-count的实际值(确认缓存复用是否必要)createdStartDate的真实最大回溯窗口charges的真实结构(沙箱样例有ItemPrice+Shipping两条)- 退货
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. 已知问题
| 问题 | 状态 |
|---|---|
GET /v3/returns/{id} |
官方 overview 明确列出该路由,但 reference 未单列响应 schema;getReturn 已按真实路由实现,沙箱 mock 404,生产再验 |
| 沙箱退款 404 | 已按文档实现,生产再验 |
| 沙箱过滤参数不生效 | 以生产为准 |
订单列表 status 过滤是否生效 |
探针未覆盖写操作,读侧以生产为准 |
| 订单翻页时是否仍需带时间窗 | 未验证,退货游标是完整查询串,暗示游标已蕴含条件 |
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. 未接入的接口
| 接口 | 原因 |
|---|---|
POST /v3/items 创建商品 |
报文只有「精简示例」,正式对接需按《Item Spec》生成;版本管理未定 |
PUT /v3/items/{sku} 更新商品 |
同上;且 PUT 是覆盖式,需先定「先查后写」的约定 |
GET /v3/items/{sku} 商品详情 |
本期只同步商品列表;ProductCapable.get() 显式报错 |
GET /v3/orders/{id}/shipping 发货信息 |
官方只有 POST 标发,没有查询路由 |
POST /v3/returns 创建退货 |
文档只给路径,没有请求报文 |
POST /v3/returns/{id}/cancel 取消退货 |
同上 |