一、 核心参数分类与必填性规范
| 参数类别 | 核心参数 | 必填性 | 核心规范 |
|---|---|---|---|
| 基础定位参数 | itemId | 必传 | 商品全局唯一标识，得物平台商品 ID 为纯数字串（如12345678），需从商品链接 / 平台数据源精准提取，不可传空、非数字或错误 ID |
skuId | 可选 | 商品规格唯一标识（对应尺码 / 配色 / 容量等），不传则返回商品基础信息，传则精准返回该规格的价格 / 库存；格式为数字串，需与itemId匹配 | |
| 鉴权参数 | appKey | 必传 | 开放平台申请的应用唯一标识，纯字符串（如dw_app_123456），需与签名中的appKey完全一致 |
timestamp | 必传 | 时间戳，主流为毫秒级（部分接口为秒级，以文档为准），格式为数字串（如1735689600000），需与服务器时间偏差≤5 分钟 | |
nonce | 必传 | 随机数，用于防重放，格式为 6~16 位数字 / 字母组合（如897897或a8b9c7d8），每次请求需生成新值，不可重复使用 | |
sign | 必传 | 签名串，按平台指定算法（HMAC-SHA256/MD5）生成，字符集为小写十六进制，长度固定（如 SHA256 签名为 64 位） | |
| 场景适配参数 | platform | 可选 | 终端类型，取值仅支持app/h5/miniProgram（小写），不传默认app；不同取值返回的图片链接、字段结构略有差异 |
region | 可选 | 地区编码，取值为 6 位数字（如310100= 上海、110100= 北京），需符合得物平台的地区编码规范，影响库存、发货时效等本地化数据 | |
version | 可选 | 接口版本号，取值为字符串（如v1/v2），需传平台已开放的版本，不传默认最新稳定版 |
二、 参数格式与编码规范
- 字符编码
所有参数（包括中文、特殊符号）必须采用
UTF-8编码，禁止使用GBK/GB2312，否则会导致商品名称、规格等中文参数乱码；示例（Python 中处理中文参数）：
python运行# 正确：先转UTF-8编码，再拼接到请求串item_name = "李宁韦德之道10 白黑"encoded_name = item_name.encode("utf-8").decode("utf-8") # 确保编码为UTF-8- 参数传递方式
GET请求：参数需拼接到 URL 后，且进行URL 编码（如空格转%20、中文转%E4%BD%A0）；python运行import urllib.parse params = {"itemId": "123456", "platform": "app"}encoded_params = urllib.parse.urlencode(params) # 自动URL编码url = f"https://api.dewu.com/item/detail?{encoded_params}"POST请求：参数需放在请求体中，格式按接口要求（application/json或application/x-www-form-urlencoded），禁止混合传递（部分参数在 URL、部分在请求体）。- 数值类型规范
数字型参数（如
itemId、timestamp、region）：需传递字符串格式的数字，而非整型 / 浮点型（避免语言序列化差异，如 Python 的123和 JavaScript 的123.0导致签名错误）；示例：
timestamp需传"1735689600000"，而非1735689600000或1.7356896e12。- 空值处理规范
非必传参数若无值，建议直接省略，而非传递
null、空字符串""或0；错误示例：
{"skuId": ""}→ 正确示例：不传入skuId参数；特殊场景：若接口明确要求非空，需传默认值（如
region无指定则传000000，以文档为准）。
三、 参数取值与逻辑约束
itemId与skuId的匹配性skuId必须属于对应itemId的商品规格，不可跨商品传递（如商品 A 的skuId不能搭配商品 B 的itemId）；验证方式：可先调用无
skuId的接口获取该商品的所有skuId列表，再选择有效skuId传递。timestamp的时效性时间戳需为当前时间 ±5 分钟，超出范围会被判定为 “请求过期”，签名直接失效；
建议：请求前实时生成时间戳，避免提前生成后长时间未发送。
nonce的唯一性同一
appKey下，nonce值需保证每次请求唯一（建议用 “时间戳 + 随机数” 生成），重复的nonce会触发防重放机制，请求被拒绝；示例：
nonce = f"{int(time.time()*1000)}{random.randint(1000,9999)}"。
四、 常见参数错误与避坑要点
| 常见错误 | 表现 | 避坑方案 |
|---|---|---|
| 时间戳单位错误 | 签名验证失败（401 错误） | 确认接口要求是 “毫秒级” 还是 “秒级”，Python 中time.time()返回秒级，需 ×1000 转为毫秒级 |
| URL 未编码 | 中文参数乱码、请求参数解析失败 | 所有拼接在 URL 中的参数必须通过urllib.parse.urlencode()编码 |
| skuId 与 itemId 不匹配 | 返回 “规格不存在”（code≠0） | 先调用基础接口获取商品的 sku 列表，再选择有效 skuId |
| 签名串参数顺序错误 | 签名验证失败 | 严格按平台文档的参数顺序拼接签名串（如文档要求appKey→timestamp→itemId，则不可调换） |
| 重复使用 nonce | 403 Forbidden | 每次请求生成新的 nonce，且记录已使用的 nonce（短期缓存），避免重复 |
总结
必填参数不遗漏：
itemId、appKey、timestamp、nonce、sign是核心必传项，缺一不可；格式编码要统一：所有参数 UTF-8 编码，数字型参数传字符串，GET 请求参数需 URL 编码；
取值逻辑要匹配：
skuId与itemId对应、时间戳在有效期内、nonce 保证唯一；空值处理有讲究：非必传参数无值时直接省略，不传递空字符串 / NULL。
