diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
index d8be395..a5f43ff 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
@@ -43,7 +43,6 @@ import common.ecommerce.walmart.dto.WalmartOrderDtos;
import common.ecommerce.walmart.dto.WalmartReturnDtos;
import common.ecommerce.walmart.dto.WalmartFeedDtos;
import common.ecommerce.walmart.dto.WalmartRefundDtos;
-import common.ecommerce.walmart.dto.WalmartShipmentDtos;
import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos;
import common.ecommerce.walmart.http.WalmartErrors;
import common.ecommerce.walmart.http.WalmartRequestFactory;
@@ -466,38 +465,52 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
/**
* 退货单详情:{@code GET /v3/returns/{returnOrderId}}。
*
+ *
沃尔玛没有 {@code GET /v3/returns/{returnOrderId}}——官方 Returns
+ * spec 里只有列表与退款两条。这里改用官方列表接口按 {@code returnOrderId} 过滤,
+ * 对外行为与「查详情」一致:返回该退货单展开出的所有售后行。
+ *
* 与列表一样按商品行展开:一个退货单可能含多个退货行,
* 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}),
* 可以直接拿去 upsert。
*
- * {@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主,
- * 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由,
- * 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。
- *
- * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ * 平台不保证过滤参数生效(沙箱 mock 就不生效),所以本地会再按单号筛一次,
+ * 不会把别的退货单混进来。
*
* @param returnOrderId 退货单号
* @return 该退货单展开出的售后行;退货单没有行时返回空列表
* @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类
*/
public List getReturn(ChannelContext ctx, String returnOrderId) {
- if (returnOrderId == null || returnOrderId.trim().isEmpty()) {
+ if (isBlank(returnOrderId)) {
throw unsupportedFilter("walmart return detail requires returnOrderId");
}
ChannelAccount account = ctx.account();
- String path = WalmartConstants.PATH_RETURN_BY_ID
- + WalmartRequestFactory.pathSegment(returnOrderId.trim());
+ Map queryParams = WalmartRequestFactory.query();
+ // 官方没有 GET /v3/returns/{id},只能走列表接口的 returnOrderId 过滤
+ queryParams.put("returnOrderId", returnOrderId.trim());
+ queryParams.put("limit", 1);
HttpResponse response = execute(ctx, "afterSales.get", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
- return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "afterSales.get");
+ return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_RETURNS,
+ queryParams, t, c, "afterSales.get");
}
});
- WalmartReturnDtos.ReturnOrder dto =
- json.fromJson(response.body(), WalmartReturnDtos.ReturnOrder.class);
- return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx));
+ WalmartReturnDtos.ReturnListResponse dto =
+ json.fromJson(response.body(), WalmartReturnDtos.ReturnListResponse.class);
+ if (dto == null || dto.returnOrders == null) {
+ return java.util.Collections.emptyList();
+ }
+ List out = new ArrayList();
+ for (WalmartReturnDtos.ReturnOrder order : dto.returnOrders) {
+ // 平台不保证过滤参数生效(沙箱 mock 就不生效),本地再筛一次
+ if (order != null && returnOrderId.trim().equals(order.returnOrderId)) {
+ out.addAll(WalmartReturnMapper.toAfterSales(order, account.omsStoreId(), zoneOf(ctx)));
+ }
+ }
+ return out;
}
// ---------------------------------------------------------------- MarkShippedCapable
@@ -544,7 +557,7 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
// 沃尔玛标发成功回更新后的订单;也见过只回受理结果的情况,两种都兼容
WalmartOrderDtos.OrderDetailResponse dto =
- json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
+ parseQuietly(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
return WalmartShipmentWriteMapper.toResult(dto == null ? null : dto.order, command);
}
@@ -606,6 +619,23 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
return WalmartRefundMapper.toResult(applied, command);
}
+ /**
+ * 尽力解析响应体:空体、非 JSON、结构不符都返回 null,不抛。
+ *
+ * 用于「平台可能只回受理结果」的写接口——把解析失败当成异常抛出,
+ * 会让一次成功的写操作变成失败(幂等层会记 FAILED,重试可能重复执行)。
+ */
+ private T parseQuietly(String body, Class type) {
+ if (body == null || body.trim().isEmpty()) {
+ return null;
+ }
+ try {
+ return json.fromJson(body, type);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
/** 退款响应尽力解析成退货单;解不出来返回 null,不抛。 */
private WalmartReturnDtos.ReturnOrder parseReturnOrderQuietly(String body) {
if (body == null || body.trim().isEmpty()) {
@@ -711,24 +741,25 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
/**
* 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。
*
- * 返回行级发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。
- * 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的
- * {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。
+ * 沃尔玛没有 {@code GET /v3/orders/{id}/shipping}——官方 Orders spec 里
+ * 该路径只有 POST(标发)。所以这里改读订单详情
+ * {@code GET /v3/orders/{purchaseOrderId}},从
+ * {@code orderLines[].orderLineStatuses[].trackingInfo} 抽行级发货记录;
+ * 数据与「发货信息」完全一致。
*
- * ⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用
- * {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。
+ * 返回行级记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间),
+ * 只包含有 {@code trackingInfo} 的行。
*
* @param purchaseOrderId 沃尔玛订单号
* @return 已发货行的记录;未发货时返回空列表
*/
public List getShipping(ChannelContext ctx,
String purchaseOrderId) {
- if (purchaseOrderId == null || purchaseOrderId.trim().isEmpty()) {
+ if (isBlank(purchaseOrderId)) {
throw unsupportedFilter("walmart shipping query requires purchaseOrderId");
}
String path = WalmartConstants.PATH_ORDER_BY_ID
- + WalmartRequestFactory.pathSegment(purchaseOrderId.trim())
- + WalmartConstants.PATH_ORDER_SHIPPING;
+ + WalmartRequestFactory.pathSegment(purchaseOrderId.trim());
HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() {
@Override
@@ -737,9 +768,9 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
}
});
- WalmartShipmentDtos.ShipmentResponse dto =
- json.fromJson(response.body(), WalmartShipmentDtos.ShipmentResponse.class);
- return WalmartShipmentMapper.toShipmentLines(dto);
+ WalmartOrderDtos.OrderDetailResponse dto =
+ json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
+ return WalmartShipmentMapper.fromOrder(dto == null ? null : dto.order);
}
// ---------------------------------------------------------------- internals
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java
deleted file mode 100644
index 907a2c9..0000000
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java
+++ /dev/null
@@ -1,134 +0,0 @@
-package common.ecommerce.walmart.dto;
-
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonProperty;
-
-import java.util.List;
-
-/**
- * 沃尔玛报文结构:查询发货信息({@code GET /v3/orders/{purchaseOrderId}/shipping})。
- *
- * 响应结构与标发请求体同形:{@code orderShipment.orderLines.orderLine[]},
- * 每个行状态里带 {@code trackingInfo}。
- *
- * ⚠ 沙箱实测该路由 404(mock 未实现)。若生产环境也不可用,可直接读订单详情
- * {@code orderLines[].orderLineStatuses[].trackingInfo}——两种方式数据一致。
- */
-public final class WalmartShipmentDtos {
-
- private WalmartShipmentDtos() {
- }
-
- /** 发货信息响应。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class ShipmentResponse {
-
- /** 发货单容器。 */
- @JsonProperty("orderShipment")
- public OrderShipment orderShipment;
- }
-
- /** 发货单:行数组。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class OrderShipment {
-
- /** 行容器。 */
- @JsonProperty("orderLines")
- public OrderLines orderLines;
- }
-
- /** 行容器。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class OrderLines {
-
- /** 发货行数组。 */
- @JsonProperty("orderLine")
- public List orderLine;
- }
-
- /** 发货行。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class OrderLine {
-
- /** 订单行号。 */
- @JsonProperty("lineNumber")
- public String lineNumber;
-
- /** 行状态容器(发货记录在 {@code status=Shipped} 的那条里)。 */
- @JsonProperty("orderLineStatuses")
- public OrderLineStatuses orderLineStatuses;
- }
-
- /** 行状态容器。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class OrderLineStatuses {
-
- /** 行状态数组。 */
- @JsonProperty("orderLineStatus")
- public List orderLineStatus;
- }
-
- /** 行状态:发货记录就挂在这里。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class OrderLineStatus {
-
- /** 状态:{@code Shipped} / {@code Delivered} 等。 */
- @JsonProperty("status")
- public String status;
-
- /** 该状态对应数量。 */
- @JsonProperty("statusQuantity")
- public Quantity statusQuantity;
-
- /** 物流信息。 */
- @JsonProperty("trackingInfo")
- public TrackingInfo trackingInfo;
- }
-
- /** 数量:与订单接口同形,{@code amount} 是字符串。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class Quantity {
-
- /** 计量单位。 */
- @JsonProperty("unitOfMeasurement")
- public String unitOfMeasurement;
-
- /** 数量(字符串)。 */
- @JsonProperty("amount")
- public String amount;
- }
-
- /** 物流信息。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class TrackingInfo {
-
- /** 发货时间,ISO-8601。 */
- @JsonProperty("shipDateTime")
- public String shipDateTime;
-
- /** 承运商。 */
- @JsonProperty("carrierName")
- public CarrierName carrierName;
-
- /** 运输方式编码。 */
- @JsonProperty("methodCode")
- public String methodCode;
-
- /** 跟踪号。 */
- @JsonProperty("trackingNumber")
- public String trackingNumber;
- }
-
- /** 承运商:{@code carrier} 与 {@code otherCarrier} 二选一。 */
- @JsonIgnoreProperties(ignoreUnknown = true)
- public static final class CarrierName {
-
- /** 标准承运商编码,如 {@code UPS}、{@code FedEx}。 */
- @JsonProperty("carrier")
- public String carrier;
-
- /** 非标准承运商名称。 */
- @JsonProperty("otherCarrier")
- public String otherCarrier;
- }
-}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
index 038e5c2..26ed820 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
@@ -1,6 +1,6 @@
package common.ecommerce.walmart.mapper;
-import common.ecommerce.walmart.dto.WalmartShipmentDtos;
+import common.ecommerce.walmart.dto.WalmartOrderDtos;
import java.util.ArrayList;
import java.util.Collections;
@@ -21,61 +21,47 @@ public final class WalmartShipmentMapper {
}
/**
- * 抽取每行的发货记录。
+ * 订单详情 → 行级发货记录。
*
- * 同一行可能有多个状态({@code Created} / {@code Shipped}),只取带
- * {@code trackingInfo} 的那条;没有任何发货记录的行不出现在结果里(表示尚未发货)。
+ * 沃尔玛没有「查询发货信息」的 GET 路由,发货信息本来就在订单详情的
+ * {@code orderLines[].orderLineStatuses[].trackingInfo} 里。这个方法把订单体
+ * 转成与 {@link #toShipmentLines} 相同的结构,所以调用方不用关心数据来自哪条路由。
*
- * @param dto 发货信息响应
- * @return 每行一条;响应为空时返回空列表
+ * 只输出有 {@code trackingInfo} 的行;未发货的行不出现。
+ *
+ * @param order 订单本体;null 时返回空列表
*/
- public static List toShipmentLines(WalmartShipmentDtos.ShipmentResponse dto) {
- if (dto == null || dto.orderShipment == null
- || dto.orderShipment.orderLines == null
- || dto.orderShipment.orderLines.orderLine == null) {
+ public static List fromOrder(WalmartOrderDtos.Order order) {
+ if (order == null || order.orderLines == null || order.orderLines.orderLine == null) {
return Collections.emptyList();
}
List out = new ArrayList();
- for (WalmartShipmentDtos.OrderLine line : dto.orderShipment.orderLines.orderLine) {
- if (line == null) {
+ for (WalmartOrderDtos.OrderLine line : order.orderLines.orderLine) {
+ if (line == null || line.lineNumber == null
+ || line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null) {
continue;
}
- WalmartShipmentDtos.TrackingInfo tracking = trackingOf(line);
- if (tracking == null) {
- continue;
+ // 同一行可能有多个状态,取第一个带 trackingInfo 的
+ for (WalmartOrderDtos.OrderLineStatus status : line.orderLineStatuses.orderLineStatus) {
+ if (status == null || status.trackingInfo == null) {
+ continue;
+ }
+ WalmartOrderDtos.TrackingInfo tracking = status.trackingInfo;
+ out.add(new ShipmentLine(
+ line.lineNumber,
+ tracking.carrierName == null ? null
+ : (tracking.carrierName.carrier != null
+ ? tracking.carrierName.carrier
+ : tracking.carrierName.otherCarrier),
+ tracking.methodCode,
+ tracking.trackingNumber,
+ tracking.shipDateTime));
+ break;
}
- out.add(new ShipmentLine(
- line.lineNumber,
- carrierOf(tracking),
- tracking.methodCode,
- tracking.trackingNumber,
- tracking.shipDateTime));
}
return out;
}
- /** 行上的发货记录:取第一条带 {@code trackingInfo} 的状态。 */
- static WalmartShipmentDtos.TrackingInfo trackingOf(WalmartShipmentDtos.OrderLine line) {
- if (line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null) {
- return null;
- }
- for (WalmartShipmentDtos.OrderLineStatus status : line.orderLineStatuses.orderLineStatus) {
- if (status != null && status.trackingInfo != null) {
- return status.trackingInfo;
- }
- }
- return null;
- }
-
- /** 承运商:标准编码优先,没有时用非标准名称。 */
- static String carrierOf(WalmartShipmentDtos.TrackingInfo tracking) {
- if (tracking.carrierName == null) {
- return null;
- }
- return tracking.carrierName.carrier != null
- ? tracking.carrierName.carrier : tracking.carrierName.otherCarrier;
- }
-
/** 一行的发货记录。 */
public static final class ShipmentLine {
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
index d901fa5..e7ab41f 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
@@ -33,27 +33,96 @@ class WalmartExtraQueryTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
+ /**
+ * 官方没有退货详情与发货信息的 GET 路由,实现改为:
+ * 退货详情走列表接口 + {@code returnOrderId} 过滤,发货信息走订单详情。
+ */
private RecordingTransport transport() {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
- .route("/v3/returns/103738048909818825",
- r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/detail.json")))
- .route("/shipping", r -> Responses.ok(
- JsonFixture.load("fixtures/walmart/orders/shipping.json")));
+ .route("/v3/returns", r -> Responses.ok(returnsListWithDetail()))
+ .route("/v3/orders/", r -> Responses.ok(shippedOrderDetail()));
+ }
+
+ /** 已发货的订单详情:发货信息从 orderLineStatuses[].trackingInfo 里读。 */
+ private static String shippedOrderDetail() {
+ return "{\"order\":{\"purchaseOrderId\":\"108816631915371\","
+ + "\"customerOrderId\":\"100000159992851\","
+ + "\"orderDate\":1686736267000,"
+ + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\","
+ + "\"item\":{\"productName\":\"Chair\",\"sku\":\"SKU-1\"},"
+ + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},"
+ + "\"orderLineStatuses\":{\"orderLineStatus\":["
+ + "{\"status\":\"Created\",\"statusQuantity\":"
+ + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":null},"
+ + "{\"status\":\"Shipped\",\"statusQuantity\":"
+ + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":{"
+ + "\"shipDateTime\":\"2026-11-16T07:00:00.000Z\","
+ + "\"carrierName\":{\"carrier\":\"UPS\"},"
+ + "\"methodCode\":\"Standard\","
+ + "\"trackingNumber\":\"1Z999AA10123456784\"}}]}}]}}}";
+ }
+
+ /** 列表响应里放一条与 detail.json 同构的退货单。 */
+ private static String returnsListWithDetail() {
+ return "{\"meta\":{\"totalCount\":1,\"limit\":1,\"nextCursor\":null},"
+ + "\"returnOrders\":[" + returnOrderJson() + "]}";
+ }
+
+ /** 单条退货单(与官方列表元素同构)。 */
+ private static String returnOrderJson() {
+ return "{\"returnOrderId\":\"103738048909818825\","
+ + "\"customerOrderId\":\"1234567891234\","
+ + "\"refundMode\":\"POST_DELIVERY\","
+ + "\"returnOrderDate\":\"2019-02-21T01:01:08.000Z\","
+ + "\"returnType\":\"REFUND\","
+ + "\"returnChannel\":{\"channelName\":\"ONLINE\"},"
+ + "\"returnLineGroups\":[{\"groupNo\":1,"
+ + "\"returnLines\":[{\"returnOrderLineNumber\":1}],"
+ + "\"labels\":[{\"carrierInfoList\":[{\"carrierName\":\"FEDEX\","
+ + "\"trackingNo\":\"785611449666\"}]}],\"returnExpectedFlag\":true}],"
+ + "\"returnOrderLines\":[{\"returnOrderLineNumber\":1,"
+ + "\"returnReason\":\"DAMAGED\",\"purchaseOrderId\":\"4790210558890\","
+ + "\"item\":{\"sku\":\"ANTL_GDL-0700\",\"productName\":\"Antlion Audio ModMic\"},"
+ + "\"quantity\":{\"unitOfMeasure\":\"EACH\",\"measurementValue\":2},"
+ + "\"unitPrice\":{\"currencyAmount\":119.95,\"currencyUnit\":\"USD\"},"
+ + "\"chargeTotals\":[{\"name\":\"lineTotal\",\"value\":239.9}],"
+ + "\"currentRefundStatus\":\"REFUND_PROCESSED\","
+ + "\"status\":\"IN_TRANSIT\","
+ + "\"statusTime\":\"2019-03-05T00:00:00.000Z\"}]}";
}
// ---------------------------------------------------------------- 退货单详情
@Test
- void returnDetailUsesReturnOrderIdPath() {
+ void returnDetailUsesListEndpointWithFilter() {
RecordingTransport transport = transport();
List afterSales = adapter(transport).getReturn(context(), "103738048909818825");
- assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/returns/103738048909818825");
+ String url = lastUrl(transport);
+ // 官方没有 /v3/returns/{id},走列表 + returnOrderId 过滤
+ assertUrlContains(url, ENDPOINT + "/v3/returns?");
+ assertUrlContains(url, "returnOrderId=103738048909818825");
+ assertTrue(!url.contains("/v3/returns/103738048909818825"), url);
assertEquals(1, afterSales.size());
}
@Test
+ void returnDetailIgnoresOtherOrdersReturnedByPlatform() {
+ // 平台不保证过滤参数生效(沙箱 mock 就不生效),本地要再筛一次
+ RecordingTransport transport = RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/v3/returns", r -> Responses.ok("{\"returnOrders\":["
+ + returnOrderJson() + ","
+ + "{\"returnOrderId\":\"OTHER\",\"returnOrderLines\":["
+ + "{\"returnOrderLineNumber\":1,\"status\":\"COMPLETED\"}]}]}"));
+
+ List afterSales = adapter(transport).getReturn(context(), "103738048909818825");
+ assertEquals(1, afterSales.size());
+ assertEquals("103738048909818825:1", afterSales.get(0).afterSaleId());
+ }
+
+ @Test
void returnDetailExpandsLinesLikeList() {
AfterSale a = adapter(transport()).getReturn(context(), "103738048909818825").get(0);
@@ -69,13 +138,15 @@ class WalmartExtraQueryTest {
}
@Test
- void returnDetailEncodesId() {
+ void returnDetailEncodesIdAsQueryValue() {
+ // 单号现在走 query 参数,空格编成 %20 或 + 都可以,关键是做了编码
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
- .route("/v3/returns/", r -> Responses.ok(
- JsonFixture.load("fixtures/walmart/returns/detail.json")));
+ .route("/v3/returns", r -> Responses.ok("{\"returnOrders\":[]}"));
adapter(transport).getReturn(context(), "R 1/2");
- assertUrlContains(lastUrl(transport), "/v3/returns/R%201%2F2");
+ String url = lastUrl(transport);
+ assertTrue(!url.contains("R 1/2"), url);
+ assertTrue(url.contains("returnOrderId=R+1%2F2") || url.contains("returnOrderId=R%201%2F2"), url);
}
@Test
@@ -89,7 +160,7 @@ class WalmartExtraQueryTest {
void returnDetail404PropagatesAsValidationException() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
- .route("/v3/returns/", r -> Responses.status(404,
+ .route("/v3/returns", r -> Responses.status(404,
JsonFixture.load("fixtures/walmart/errors/gateway-404.json")));
ValidationException ex = assertThrows(ValidationException.class,
@@ -100,14 +171,16 @@ class WalmartExtraQueryTest {
// ---------------------------------------------------------------- 发货信息
@Test
- void shippingUsesOrderPathAndMapsShippedLinesOnly() {
+ void shippingReadsOrderDetail() {
RecordingTransport transport = transport();
List lines =
adapter(transport).getShipping(context(), "108816631915371");
- assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/orders/108816631915371/shipping");
- // 3 行里只有 2 行有 trackingInfo;未发货行不出现
- assertEquals(2, lines.size());
+ String url = lastUrl(transport);
+ // 官方没有 GET .../shipping,改读订单详情
+ assertUrlContains(url, ENDPOINT + "/v3/orders/108816631915371");
+ assertTrue(!url.contains("/shipping"), url);
+ assertEquals(1, lines.size());
assertEquals("1", lines.get(0).lineNumber());
assertEquals("UPS", lines.get(0).carrier());
assertEquals("Standard", lines.get(0).methodCode());
@@ -117,11 +190,23 @@ class WalmartExtraQueryTest {
@Test
void shippingFallsBackToOtherCarrier() {
+ String body = "{\"order\":{\"purchaseOrderId\":\"PO-1\",\"orderDate\":1686736267000,"
+ + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\","
+ + "\"item\":{\"sku\":\"S\"},"
+ + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},"
+ + "\"orderLineStatuses\":{\"orderLineStatus\":[{\"status\":\"Shipped\","
+ + "\"statusQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},"
+ + "\"trackingInfo\":{\"shipDateTime\":\"2026-11-16T08:00:00.000Z\","
+ + "\"carrierName\":{\"otherCarrier\":\"Local Courier\"},"
+ + "\"methodCode\":\"Freight\",\"trackingNumber\":\"LC-1\"}}]}}]}}}";
+ RecordingTransport transport = RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/v3/orders/", r -> Responses.ok(body));
+
List lines =
- adapter(transport()).getShipping(context(), "108816631915371");
- // 非标准承运商:carrier 为空时用 otherCarrier
- assertEquals("Local Courier", lines.get(1).carrier());
- assertEquals("Freight", lines.get(1).methodCode());
+ adapter(transport).getShipping(context(), "PO-1");
+ assertEquals("Local Courier", lines.get(0).carrier());
+ assertEquals("Freight", lines.get(0).methodCode());
}
@Test
@@ -132,10 +217,15 @@ class WalmartExtraQueryTest {
}
@Test
- void emptyShipmentReturnsEmptyList() {
+ void orderWithoutTrackingReturnsEmptyList() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
- .route("/shipping", r -> Responses.ok("{\"orderShipment\":{\"orderLines\":{\"orderLine\":[]}}}"));
+ .route("/v3/orders/", r -> Responses.ok("{\"order\":{\"purchaseOrderId\":\"PO-1\","
+ + "\"orderDate\":1686736267000,"
+ + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\","
+ + "\"item\":{\"sku\":\"S\"},"
+ + "\"orderLineStatuses\":{\"orderLineStatus\":["
+ + "{\"status\":\"Created\",\"trackingInfo\":null}]}}]}}}"));
assertTrue(adapter(transport).getShipping(context(), "PO-1").isEmpty());
}
@@ -150,10 +240,9 @@ class WalmartExtraQueryTest {
}
@Test
- void listAndDetailAgreeOnReturnPathPrefix() {
- // 两个接口共用 /v3/returns 前缀;详情多一段 id,别把列表路由吃掉
+ void detailUsesListPathNotByeIdPath() {
+ // 官方没有 /v3/returns/{id};实现改为列表接口 + returnOrderId 过滤
assertEquals("/v3/returns", WalmartConstants.PATH_RETURNS);
- assertEquals("/v3/returns/", WalmartConstants.PATH_RETURN_BY_ID);
}
/** 列表接口仍然可用(详情方法没有误改列表路由)。 */
diff --git a/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json b/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json
deleted file mode 100644
index 73af15d..0000000
--- a/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json
+++ /dev/null
@@ -1,59 +0,0 @@
-{
- "orderShipment": {
- "orderLines": {
- "orderLine": [
- {
- "lineNumber": "1",
- "orderLineStatuses": {
- "orderLineStatus": [
- {
- "status": "Created",
- "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
- "trackingInfo": null
- },
- {
- "status": "Shipped",
- "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
- "trackingInfo": {
- "shipDateTime": "2026-11-16T07:00:00.000Z",
- "carrierName": { "carrier": "UPS" },
- "methodCode": "Standard",
- "trackingNumber": "1Z999AA10123456784"
- }
- }
- ]
- }
- },
- {
- "lineNumber": "2",
- "orderLineStatuses": {
- "orderLineStatus": [
- {
- "status": "Created",
- "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
- "trackingInfo": null
- }
- ]
- }
- },
- {
- "lineNumber": "3",
- "orderLineStatuses": {
- "orderLineStatus": [
- {
- "status": "Shipped",
- "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
- "trackingInfo": {
- "shipDateTime": "2026-11-16T08:00:00.000Z",
- "carrierName": { "otherCarrier": "Local Courier" },
- "methodCode": "Freight",
- "trackingNumber": "LC-0001"
- }
- }
- ]
- }
- }
- ]
- }
- }
-}
diff --git a/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json b/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json
deleted file mode 100644
index f6f574d..0000000
--- a/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
- "returnOrderId": "103738048909818825",
- "customerEmailId": "emailID123456@relay.walmart.com",
- "customerName": { "firstName": "Jane", "lastName": "Doe" },
- "customerOrderId": "1234567891234",
- "refundMode": "POST_DELIVERY",
- "returnOrderDate": "2019-02-21T01:01:08.000Z",
- "returnType": "RETURN",
- "returnByDate": "2019-03-23T01:01:06.000Z",
- "totalRefundAmount": { "currencyAmount": 127.45, "currencyUnit": "USD" },
- "returnChannel": { "channelName": "ONLINE" },
- "returnLineGroups": [
- {
- "groupNo": 1,
- "returnLines": [ { "returnOrderLineNumber": 1 } ],
- "labels": [
- {
- "labelImageURL": "https://i5.walmartimages.com/asr/label.png",
- "carrierInfoList": [
- {
- "carrierId": "11",
- "carrierName": "FEDEX",
- "serviceType": "FedEx Ground",
- "trackingNo": "785611449666"
- }
- ]
- }
- ],
- "returnExpectedFlag": true
- }
- ],
- "returnOrderLines": [
- {
- "returnOrderLineNumber": 1,
- "salesOrderLineNumber": 1,
- "returnReason": "DAMAGED",
- "purchaseOrderId": "4790210558890",
- "item": {
- "sku": "ANTL_GDL-0700",
- "productName": "Antlion Audio ModMic"
- },
- "quantity": { "unitOfMeasure": "EACH", "measurementValue": 2 },
- "unitPrice": { "currencyAmount": 119.95, "currencyUnit": "USD" },
- "chargeTotals": [ { "name": "lineTotal", "value": 239.9 } ],
- "currentDeliveryStatus": "IN_TRANSIT",
- "currentRefundStatus": "REFUND_PROCESSED",
- "refundedQty": 2,
- "status": "IN_TRANSIT",
- "statusTime": "2019-03-05T00:00:00.000Z"
- }
- ]
-}
diff --git a/docs/walmart/README.md b/docs/walmart/README.md
index a779524..31e81ca 100644
--- a/docs/walmart/README.md
+++ b/docs/walmart/README.md
@@ -73,11 +73,12 @@ ChannelConnection conn = ChannelConnection.of(
| `SALES_ORDER` 订单列表 / 详情 | ✅ |
| `PRODUCT` 商品列表 / 详情 | ✅ |
| `RETURNS` 退货列表(按行展开) | ✅ |
-| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) |
-| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) |
+| 退货单详情 `WalmartAdapter.getReturn` | ✅ 走列表接口 `returnOrderId` 过滤(官方无详情路由) |
+| 发货信息 `WalmartAdapter.getShipping` | ✅ 走订单详情 `trackingInfo`(官方无 GET shipping 路由) |
| `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) |
-| `REFUND` 退款 | ❌ 沙箱 404 |
-| 商品写入(Feed / 单个) | ❌ 沙箱 520 |
+| `REFUND` 退款 | ✅(⚠ 沙箱 404,见 §8) |
+| 商品 Feed 提交 / 状态查询 | ✅ 扩展方法(⚠ 沙箱 520,见 §9) |
+| 单个商品创建 / 更新 | ❌ 官方 API 不存在,商品写入走 Feed |
过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见
[`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。
@@ -154,8 +155,6 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
| `orders/detail.json` | 文档 §4.2 实测样例 |
| `items/list.json` | 文档 §3.1 实测样例 + 补了 `PUBLISHED/ACTIVE` 与 `PUBLISHED/RETIRED` 两条 |
| `returns/list.json` | 文档 §5.1 实测样例 + 补了第二行(覆盖无 `chargeTotals`、无面单分组) |
-| `returns/detail.json` | 按文档 §5.2 的「同列表元素」结构构造(沙箱 404,无实测) |
-| `orders/shipping.json` | 按文档 §4.4 的 `orderShipment` 结构构造(沙箱 404,无实测;含非标准承运商) |
| `errors/*.json` | 文档 §1.5 两种错误格式原文 |
| `token/success.json` | 文档 §2.1 实测结构(token 值为占位) |
@@ -166,7 +165,9 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
| 问题 | 状态 |
|---|---|
| 沙箱商品详情 404 | 生产环境再验 |
-| 沙箱退货详情 / 退款 404 | 两条都已按文档实现(`getReturn` / `refund`),生产再验 |
+| `GET /v3/returns/{id}` | **官方无此路由**;`getReturn` 改走列表接口 `returnOrderId` 过滤 |
+| `GET /v3/orders/{id}/shipping` | **官方无此路由**(只有 POST 标发);`getShipping` 改读订单详情 `trackingInfo` |
+| 沙箱退款 404 | 已按文档实现,生产再验 |
| 沙箱 Feed 520 | 提交 / 状态查询已按文档实现(`submitFeed` / `getFeedStatus`),生产再验 |
| 沙箱过滤参数不生效 | 以生产为准 |
| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |