1688 代采系统实战：SKU 阶梯价、快递费和搜索降级这三个坑，我踩了两个月
代采系统的难点不在"拿到商品详情"，而在"下单前那一刻能不能算对钱"。这篇是一次完整的排障记录：SKU 阶梯价怎么选、运费怎么估、找货搜索接口只有 53% 成功率怎么办。全部是实测数据和可直接复用的代码，写给正在做代采、铺货、反向海淘报价的朋友。
一、先明确一件事：代采系统的技术核心是"报价"
代采的业务闭环是：客户给链接 → 系统给出到手价 → 客户付款 → 系统去 1688 下单。中间最脆弱的一环是报价，而报价依赖三个数据：SKU 单价、数量对应价格、运费。任何一个算错，要么自己亏钱，要么客户跑单。
我把 1688 这条线（走 https://api-gw.onebound.cn/1688/{接口名}）跑了两个月，后台统计的成功率是这样：item_get、item_get_app、item_get_pro、custom 都是 99%，cat_get 97%，item_fee 96%，但 item_search 只有 53%。这组数字直接决定了下面三个坑怎么填。
二、坑一：SKU 阶梯价，直接用 price 字段一定出事
1688 的商品大量是批发价，价格不是一个数字，而是一段区间。item_get 返回的 skus.sku[] 里，每个 SKU 都可能有 price、quantity（起订量）和 price_range（阶梯区间）。我最初只取 price，结果客户订 1000 件时系统按 1 件的价格报出去，单笔亏了几百块。
正确做法是按采购量匹配阶梯：
def pick_price(sku, qty):
# sku["price_range"] 形如 "1-99:3.20;100-499:2.85;500-:2.40"
ranges = []
for seg in (sku.get("price_range") or "").split(";"):
if ":" not in seg:
continue
span, price = seg.split(":")
lo, _, hi = span.partition("-")
ranges.append((int(lo), int(hi) if hi else 10**9, float(price)))
for lo, hi, price in sorted(ranges):
if lo <= qty <= hi:
return price
return float(sku.get("price", 0))配套有三个细节：一是 is_promotion=1 时拿到的是促销价，报价口径必须和前端展示口径一致，否则客户看到的和下单价对不上；二是 quantity 是最小起订量，低于它要么拒单要么走一件代发通道；三是 SKU 的 properties_name（如"颜色:黑色;尺码:XL"）要完整透传给下单侧，否则人工下单时对不上规格。
另外提醒一句：主链路的 99% 成功率意味着这层几乎不用写重试，但类目字段的差异要提前处理，不同类目下 skus 可能是数组、可能是空对象，解析前先判类型。
三、坑二：运费预估，item_fee 不是你以为的那样
代采报价必须含运费，我用的是 item_fee（实测 96%）。它的入参除了 num_iid，关键是收货地区 ID，而地区 ID 来自 cat_get 那一类的行政区划数据，需要提前离线同步一份本地映射表——在线实时查行政区划既慢又浪费调用量。
r = call("1688", "item_fee", num_iid="674532958902", area_id="360700")
fee = r["item"]["express_fee"] # 单位：元两个实操经验：第一，item_fee 返回的是快递报价，对重量敏感的大件（家具、大件家电）偏差明显，我在报价侧加了一个体积重校验，超过阈值直接提示"运费面议"，比硬报一个错价安全；第二，发货地会影响运费，代采下单前拿到的发货地要重新校验一次，跨省调货的场景我遇到过一次报价和实付差 30 块。
四、坑三：搜索只有 53%，别拿它做主链路
这是最花时间的一个坑。代采系统有个"客户不知道要买哪家，输入关键词找货"的功能，我一开始直接接了 item_search，结果近一半的搜索请求返回失败或空结果，客服每天被问"为什么搜不出来"。53% 的成功率做实时搜索，产品体验是不可能成立的。
我最后改成三层组合，绕开了对搜索的强依赖：
本地商品池：客户历史询价过的商品全部入库，搜索优先走自己的 ES，命中率覆盖了七成以上的重复询价；
类目树下钻：用
cat_get（97%）把类目树离线落库，客户可以从"类目 → 子类目 → 商品"逐级进入，这条路径不依赖搜索接口；关键词搜索兜底：只有前两条都没命中时才调
item_search，且失败时前端展示"暂未找到，可粘贴链接直接报价"，把失败转成引导动作。
改造之后，搜索模块的有效响应率从 53% 提到 96% 以上，调用量反而下降了——因为本地池消化了大部分请求，成本也降了。
五、顺带说下错误码里的成本规则
0000（成功）与 2000（搜索成功但无结果）计费，4000 / 4001 / 4002 / 4017 这些服务端错误、网络错误、超时都不计费。所以搜索返回 2000（没搜到东西）是要花钱的，上面那套"本地池优先"的策略不只是为了体验，也是在省钱。超时设置同样建议给到 10 秒以上，避免客户端主动断开导致"服务端已计费、本地没数据"的双输。
六、写在最后
三个坑的共同点是：接口本身很稳，坑都出在"怎么用"。把 SKU 价格口径、运费口径、失败路径定清楚，代采系统的报价准确率能做到接近 100%。接口参数我是对着 open.onebound.cn/help/api 逐个核的，测试 key 是在万邦开放平台的控制台申请的，入口放这里，需要的自取：API 控制台
