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.
142 lines
6.1 KiB
142 lines
6.1 KiB
package common.ecommerce.walmart; |
|
|
|
/** |
|
* 沃尔玛 Marketplace 协议常量。 |
|
* |
|
* <p>端点与路径属于<b>协议的一部分</b>,写在代码里,不做成配置表。 |
|
* 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}: |
|
* 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定, |
|
* 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。</p> |
|
* |
|
* <p>来源:Walmart Developer Portal 官方 reference(2026-11 核对): |
|
* {@code /us-marketplace/reference/} 下的 {@code shippingupdates}、{@code getallorders}、 |
|
* {@code getreturns}、{@code getallitems}、{@code itembulkuploads}、{@code getallfeedstatuses}。 |
|
* 与《沃尔玛沙箱接口说明》v1.0 冲突时<b>以官方 schema 为准</b>。</p> |
|
*/ |
|
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"; |
|
|
|
/** 发起退款:{@code POST /v3/returns/{returnOrderId}/refund}。⚠ 沙箱实测 404。 */ |
|
public static final String PATH_RETURN_REFUND = "/refund"; |
|
|
|
/** |
|
* Feed 提交({@code POST /v3/feeds?feedType=...})与状态查询({@code GET /v3/feeds/{feedId}})。 |
|
* |
|
* <p>⚠ 沙箱实测两条路由都 520(mock 未实现);本期只做常量与 DTO, |
|
* 没有对外方法——沃尔玛的商品写入是 Feed 的载体,等商品写接入时一起开放。</p> |
|
*/ |
|
public static final String PATH_FEEDS = "/v3/feeds"; |
|
|
|
// ---------------------------------------------------------------- 请求头 |
|
|
|
/** 服务名,固定值。 */ |
|
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"; |
|
|
|
/** 访问令牌;<b>业务接口用它,不用 Authorization</b>。 */ |
|
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"; |
|
|
|
// ---------------------------------------------------------------- 限制 |
|
|
|
/** |
|
* 商品列表单页上限。 |
|
* |
|
* <p>官方原文:{@code cannot be more than 1000 entities per request},默认 20。 |
|
* 注意 {@code nextCursor} 描述里的「more than 200 items」是<b>建议改用游标的阈值</b>, |
|
* 不是 limit 上限——两者容易混。</p> |
|
*/ |
|
public static final int MAX_ITEM_PAGE_SIZE = 1000; |
|
|
|
/** |
|
* 商品列表 {@code nextCursor} 的初始值。 |
|
* |
|
* <p>官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。 |
|
* 不过首页不传也能用平台默认,适配器选择<b>不显式传</b>,避免平台版本差异导致 400。</p> |
|
*/ |
|
public static final String ITEM_CURSOR_INITIAL = "*"; |
|
|
|
/** 商品游标有效期(秒);过期平台返回 400 Invalid Cursor。 */ |
|
public static final int ITEM_CURSOR_TTL_SECONDS = 120; |
|
|
|
/** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */ |
|
public static final int DEFAULT_ORDER_PAGE_SIZE = 20; |
|
|
|
/** |
|
* 订单列表单页上限。 |
|
* |
|
* <p>官方原文:{@code Cannot be larger than 200.}</p> |
|
*/ |
|
public static final int MAX_ORDER_PAGE_SIZE = 200; |
|
|
|
/** 退货列表默认单页条数;沃尔玛默认 10。 */ |
|
public static final int DEFAULT_RETURN_PAGE_SIZE = 10; |
|
|
|
/** 退货列表单页上限;官方原文 {@code Cannot be larger than 200.} */ |
|
public static final int MAX_RETURN_PAGE_SIZE = 200; |
|
|
|
/** |
|
* 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。 |
|
* |
|
* <p>超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。</p> |
|
*/ |
|
public static final int MAX_ORDER_WINDOW_DAYS = 180; |
|
|
|
/** |
|
* 令牌提前续期秒数。 |
|
* |
|
* <p>{@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count} |
|
* 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。</p> |
|
*/ |
|
public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L; |
|
|
|
/** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */ |
|
public static final int RAW_RESPONSE_LIMIT = 1024; |
|
|
|
private WalmartConstants() { |
|
} |
|
}
|
|
|