做 B2B 电商开发这么多年，1688 的 item_get 接口算是打交道最多的 —— 毕竟要从源头拿货，商品的起批量、供应商资质、批发价这些数据都得靠它。但刚开始对接的时候，光签名就卡了我 3 天，后来又踩过 “库存字段不统一”“起批量单位混乱” 的坑。今天把这些实战经验整理出来，从参数配置到高阶代码实现，全是能直接用的干货，帮大家少走弯路。
一、对接前必做的准备：这些参数别搞错
1688 接口和淘宝不太一样，多了不少 B2B 特有的字段，比如起批量、供应商 ID，而且权限申请也有讲究，先把基础信息理清楚：
1. 接口基础信息（我踩过的权限坑）
项目 |
详情 |
接口名称 |
item_get（1688 商品详情查询） |
请求方式 |
POST（之前试过 GET，偶尔会丢参数，POST 稳定多了） |
响应格式 |
JSON（1688 不支持 XML，别瞎试） |
版本 |
目前稳定版是 1.0（2.0 还在灰度，不建议生产用） |
权限要求 |
个人开发者要实名认证，企业开发者得传营业执照，不然拿不到供应商信息 |
调用限制 |
个人号 100 次 / 天，企业号 5000 次 / 天（之前超了一次，被限制 24 小时，别乱刷） |
2. 核心参数说明（带实战注意点）
1688 的参数分 “系统必传” 和 “业务必传”，还有些可选参数看似不重要，没处理好就出问题：
（1）系统必传参数（签名的关键）
参数名 |
类型 |
说明 + 踩坑经验 |
app_key |
String |
开放平台申请的 APP_KEY，记着存在环境变量里，别硬编码（之前把密钥提交到 Git，赶紧重置了） |
method |
String |
固定填 “alibaba.item.get”（不是 “1688.item.get”，刚开始写错了报参数错误） |
timestamp |
String |
格式 “yyyy-MM-dd HH:mm:ss”，和 1688 服务器时间差不能超 3 分钟（之前差 5 分钟，签名一直失败） |
sign |
String |
HMAC-SHA1 签名串（和淘宝的 MD5 不一样，别搞混了） |
format |
String |
固定 “json”，不用改 |
（2）业务必传参数（B2B 特有字段）
参数名 |
类型 |
说明 + 实战注意点 |
item_id |
String |
商品 ID，从 1688 商品页 URL 里拿 |
fields |
String |
要返回的字段，建议指定（比如 “item_id,title,price,quantity,provider_id”），少传字段快很多 |
（3）容易忽略的可选参数
参数名 |
类型 |
说明 + 实战价值 |
lang |
String |
语言，默认 “zh”，要英文传 “en”（做外贸对接时用到过） |
country |
String |
国家码，默认 “CN”，查跨境商品时传目标国家（比如 “US” 查美国可售的） |
二、签名机制：1688 和淘宝不一样，别踩坑！
刚开始对接的时候，我拿淘宝的 MD5 签名逻辑套，结果一直报 “签名无效”，后来才发现 1688 用的是 HMAC-SHA1，步骤也不一样，现在把正确流程写清楚，照着做绝对不会错：
- 收集参数：把所有要传的参数（除了 sign）都列出来，比如 app_key、method、timestamp、item_id 这些；
- 参数排序：按参数名的 ASCII 码升序排（比如 “app_key” 在 “item_id” 前面，“method” 在 “timestamp” 前面）；
- 拼接字符串：按 “key=value&key=value” 的格式拼，比如app_key=xxx&item_id=123&method=alibaba.item.get×tamp=2024-06-01 10:00:00；
- 加密钥签名：把拼接好的字符串，用 app_secret 作为密钥，做 HMAC-SHA1 加密，然后转成大写（这里要注意，密钥要完整，少一个字符都不行）；
- 加 sign 参数：把生成的签名放到 sign 字段里，一起发请求。
我之前踩的坑：没给参数排序，直接按传入顺序拼的，结果签名错了；还有一次 timestamp 格式用了 “yyyyMMddHHmmss”，应该是带横杠和空格的，大家别犯一样的错。
三、高阶代码实现：带缓存 + 异常处理（可直接用）
之前写过简单版的代码，但是生产环境一用就出问题 ——QPS 高了被限流，库存数据实时性差，后来加了 Redis 缓存、多线程控制，现在稳定运行大半年了，代码里都加了注释，照着改改就能用：
四、实战踩坑指南：这些问题我都遇过
1. 签名相关的坑
- 坑 1：timestamp 格式错，用了 “yyyyMMddHHmmss”，应该是 “yyyy-MM-dd HH:mm:ss”，差一个符号就失败；
- 坑 2：参数没排序，之前按传入顺序拼的，结果签名对不上，后来用 sorted 排了就好；
- 坑 3：app_secret 是字符串，没转成 bytes 类型，HMAC 加密的时候报错，后来加了.encode('utf-8')才好。
2. 数据解析的坑
- 坑 1：起批量单位不统一，有的商品 “10 件起批”，有的 “1 箱起批”，没处理导致算错采购量，后来加了单位换算的逻辑；
- 坑 2：供应商信息缺失，没申请 “供应商资质” 权限，导致 provider_id 是空的，去开放平台补申请就好；
- 坑 3：标题过长，有的商品标题超 200 字，存数据库的时候报 “字段过长”，后来截断到 200 字就没问题。
3. 调用限制的坑
- 坑 1：QPS 太高被限流，个人号 QPS 超 10 就会被限制，企业号建议控制在 8 以内，加了 request_interval 就稳定了；
- 坑 2：日调用量超了，没监控，突然不能用了才发现，后来加了日志告警，快到限额就提醒。
五、常见问题排查表（按优先级排）
问题现象 |
大概率原因 |
解决办法（我亲测有效） |
签名无效（code3002） |
1. timestamp 格式错；2. 参数没排序；3. app_secret 错 |
1. 检查 timestamp 是不是 “yyyy-MM-dd HH:mm:ss”；2. 用 sorted 排参数；3. 重新复制 app_secret，别多空格 |
参数错误（code3001） |
1. item_id 错；2. method 填错；3. fields 有无效字段 |
1. 从 1688 商品页重新复制 item_id；2. method 必须是 “alibaba.item.get”；3. 只传文档里有的字段 |
权限不足（code4001） |
1. 没申请对应权限；2. 账号没认证 |
1. 去开放平台申请 “商品详情查询”“供应商资质” 权限；2. 个人号实名认证，企业号传营业执照 |
库存数据不对 |
1. 没处理单位换算；2. 缓存没更新 |
1. 检查库存单位，转成统一的 “件”；2. 缩短缓存时间，实时性要求高的设 10 分钟 |
六、最后说点心里话
干电商接口这行十几年了，从最早手动爬数据踩坑，到现在做企业级对接，1688、淘宝、京东这些平台的接口都摸得差不多了。其实 1688 的 item_get 接口不算复杂，就是细节多，比如 B2B 特有的起批量、供应商信息，还有签名和淘宝不一样，刚开始容易卡壳。
你们要是在测试接口的时候遇到问题，不管是签名对不上，还是数据解析有疑问，随时在评论区喊我。我知道写代码的时候卡壳有多烦，能帮大家少踩一个坑，我这篇东西就没白写～
