package common.ecommerce.walmart; /** * 沃尔玛 Marketplace 协议常量。 * *
端点与路径属于协议的一部分,写在代码里,不做成配置表。 * 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}: * 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定, * 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。
* *来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 * {@code https://sandbox.walmartapis.com} 实测。
*/ public final class WalmartConstants { /** 适配器标识;注册表与日志用。 */ public static final String ADAPTER_ID = "walmart-direct"; /** 生产端点。 */ public static final String PRODUCTION_BASE_URL = "https://marketplace.walmartapis.com"; /** 沙箱端点。 */ public static final String SANDBOX_BASE_URL = "https://sandbox.walmartapis.com"; // ---------------------------------------------------------------- 路径 /** 换取访问令牌;form-urlencoded + Basic Auth。 */ public static final String PATH_TOKEN = "/v3/token"; /** 商品列表;游标分页。 */ public static final String PATH_ITEMS = "/v3/items"; /** 商品详情;路径参数为 URL 编码后的 SKU。 */ public static final String PATH_ITEM_BY_SKU = "/v3/items/"; /** 订单列表;按创建时间窗 + 游标分页。 */ public static final String PATH_ORDERS = "/v3/orders"; /** 订单详情;路径参数为 purchaseOrderId。响应多包一层 {@code {"order": ...}}。 */ public static final String PATH_ORDER_BY_ID = "/v3/orders/"; /** 退货单列表;{@code meta.nextCursor} 本身是一段查询串,翻页时整串拼到路径后面。 */ public static final String PATH_RETURNS = "/v3/returns"; /** 退货单详情;路径参数为 returnOrderId。⚠ 沙箱实测 404。 */ public static final String PATH_RETURN_BY_ID = "/v3/returns/"; /** 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。⚠ 沙箱实测 404。 */ public static final String PATH_ORDER_SHIPPING = "/shipping"; // ---------------------------------------------------------------- 请求头 /** 服务名,固定值。 */ public static final String HEADER_SVC_NAME = "WM_SVC.NAME"; /** 服务名的固定取值。 */ public static final String SVC_NAME_VALUE = "Walmart Marketplace"; /** 调用链追踪 ID,每次请求生成一个新的;SDK 用 {@code ChannelContext.requestId()}。 */ public static final String HEADER_CORRELATION_ID = "WM_QOS.CORRELATION_ID"; /** 访问令牌;业务接口用它,不用 Authorization。 */ public static final String HEADER_ACCESS_TOKEN = "WM_SEC.ACCESS_TOKEN"; /** 表单类型,仅令牌接口使用。 */ public static final String CONTENT_TYPE_FORM = "application/x-www-form-urlencoded"; /** JSON 类型,业务接口使用。 */ public static final String CONTENT_TYPE_JSON = "application/json"; // ---------------------------------------------------------------- 限制 /** * 商品列表单页上限(官方值,超了本地截断)。 * *与领星不同,这里是平台硬上限:静默截断是安全的,因为调用方本来 * 就只能拿到这么多,且用 {@code nextCursor} 翻页。
*/ public static final int MAX_ITEM_PAGE_SIZE = 200; /** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */ public static final int DEFAULT_ORDER_PAGE_SIZE = 20; /** * 订单列表单页上限(📖 官方常见取值 200,与商品一致)。 * *文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断, * 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。
*/ public static final int MAX_ORDER_PAGE_SIZE = 200; /** 退货列表默认单页条数;沃尔玛默认 10。 */ public static final int DEFAULT_RETURN_PAGE_SIZE = 10; /** * 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。 * *超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。
*/ public static final int MAX_ORDER_WINDOW_DAYS = 180; /** * 令牌提前续期秒数。 * *{@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count} * 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。
*/ public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L; /** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */ public static final int RAW_RESPONSE_LIMIT = 1024; private WalmartConstants() { } }