结论先拍：1688开放平台是“L1基础免费（受QPS卡脖子）+ L2资源包（提频/高级实时库存/跨境增强，几百~几千元/年）+ L3超包按量（≈¥0.001~0.01/次，极少触发）”的三层结构。 日常做商品同步+订单回流+物流轨迹零调用费，但单Key默认搜索QPS≈10/s、订单QPS≈20/s，超了返回 ISP_FLOW_CONTROL_LIMIT，不扣钱但直接失败；要批发防超卖必须买包拿高级实时可售库存（不含占用/锁定）+ 提频到50/100/200。

一、三层收费架构（2026现行口径）

官方《开放平台付费服务规则》明确：能力按资源包收费，一次性支付生效，不支持退款，过期或调用量耗尽该能力不可用。

二、各接口收费属性速查

• ✅ 永远免费（占QPS）：商品搜索、商品详情（含sku_list.stock_num基础库存，有缓存非强一致）、买家订单列表/明细、物流轨迹、确认收货。

• ⚠️ 必须资源包才有权限：高级实时可售库存（区分占用/锁定/在途）、QPS提频到50+、跨境HS编码/英文申报增强、ISV代发分账、消息推送高级版。

• ❌ 不存在“按次人民币扣费的基础API”：基础接口要么免额内0元，要么超QPS被限流，不会像淘宝TOP那样“超免额0.02/百次”。

三、QPS 10 的真实瓶颈（回顾）

• 监控500爆款SKU、30s一轮 → 需 16.7次/s > 单Key 10 QPS → 限流。

• alibaba.item.get 里的 stock_num 是基础缓存库存，不含买家已下单未付款/锁单占用，代发锁库存会超卖。

• 破墙三正规路（上篇已给GuardedClient）：令牌桶自律8QPS + 同企业多Key轮询 + 买包提频/开高级库存。

四、资源包购买攻略（CTO/老板视角）

1. 先算账再买：日调用<2万次（搜索5k+详情1w+订单回写少量）→ L1免费够用，别买包。

2. 自研ERP选档：

• 100~500 SKU代发、30s级防超卖 → 基础版资源包 ¥980~1980/年，QPS提至50，含高级实时库存查询。

• 500~2000 SKU / 多店聚合 → 企业版 ¥1980~2980/年，QPS100+，含数据推送。

• 跨境寻源（Supply）同区间，增强字段包。

3. 购买路径：open.1688.com → 控制台 → 服务市场 → API资源包 → 选应用(AppKey)绑定 → 支付后5分钟内权限自动生效，在「应用详情→接口权限」看“已生效”。

4. 避坑：

• 应用类型必须是自用型（企业实名+店铺/采购授权），ISV工具型需额外资质审核且包档不同。

• 资源包不退款、不过期顺延，大促前买别大促当天买（5分钟生效也可能卡审核）。

• 高级实时库存不是单独一个method全局开放，是按AppKey在“接口权限”页点亮，调无包Key返回 no permission。

五、Python：三层计费模型选择器 + 购买决策器

# ali1688_billing_model.py
"""
1688 三层收费模型：免费/QPS判定 + 资源包档位推荐 + 超量按量估算
"""
from dataclasses import dataclass
from typing import Dict, List

# 官方/实测参考值
SEARCH_QPS = 10
ORDER_QPS = 20
ADV_PACK_PRICE = {"base": (980, 1980), "ent": (1980, 2980)}
OVERAGE_UNIT = 0.005 / 100   # 超资源包按量≈0.005元/次（参考值，非基础API触发）

@dataclass
class AppProfile:
    daily_search_calls: int
    daily_item_calls: int
    daily_order_calls: int
    sku_monitored: int
    poll_interval_sec: int = 30   # 爆款轮询周期
    need_realtime_stock: bool = False

def qps_demand(p: AppProfile) -> Dict:
    # 爆款轮询峰值QPS（按监控SKU全量轮询估算）
    peak_qps = p.sku_monitored / max(p.poll_interval_sec, 1)
    return {
        "search_avg_qps": round(p.daily_search_calls / 86400, 3),
        "item_peak_qps": round(peak_qps, 3),
        "order_avg_qps": round(p.daily_order_calls / 86400, 3),
        "hit_search_limit": peak_qps > SEARCH_QPS,
    }

def recommend_tier(p: AppProfile) -> Dict:
    q = qps_demand(p)
    peak = q["item_peak_qps"]
    if not p.need_realtime_stock and peak <= SEARCH_QPS and p.daily_search_calls + p.daily_item_calls < 50_000:
        return {"tier": "L1免费", "buy_pack": False,
                "reason": f"峰值{peak}QPS≤10，日总调用<5万，L1零费够用",
                "year_cost": 0}
    if p.need_realtime_stock or peak > SEARCH_QPS:
        if peak <= 50:
            lo, hi = ADV_PACK_PRICE["base"]
            return {"tier": "L2基础版资源包", "buy_pack": True,
                    "reason": f"需实时库存或峰值{peak}QPS>10，提频50+高级库存",
                    "year_cost": f"¥{lo}~{hi}"}
        else:
            lo, hi = ADV_PACK_PRICE["ent"]
            return {"tier": "L2企业版资源包", "buy_pack": True,
                    "reason": f"峰值{peak}QPS>50，多店聚合/大卖",
                    "year_cost": f"¥{lo}~{hi}"}
    return {"tier": "L1免费", "buy_pack": False, "reason": "默认", "year_cost": 0}

def overage_cost_if_no_pack(p: AppProfile, pack_calls_per_year: int = 0) -> float:
    """如果买了包但包内调用量耗尽，超量按量估算（演示用）"""
    yearly_total = (p.daily_search_calls + p.daily_item_calls + p.daily_order_calls) * 365
    over = max(0, yearly_total - pack_calls_per_year)
    return round(over * OVERAGE_UNIT, 2)

if __name__ == "__main__":
    cases = [
        ("微型自研单店", AppProfile(2000, 3000, 200, 50, 300, False)),
        ("代发100SKU 30s防超卖", AppProfile(1000, 5000, 300, 100, 30, True)),
        ("代发500SKU 30s", AppProfile(2000, 20000, 800, 500, 30, True)),
        ("中大型多店聚合", AppProfile(8000, 60000, 3000, 1500, 30, True)),
    ]
    for name, prof in cases:
        q = qps_demand(prof)
        rec = recommend_tier(prof)
        print(f"▶ {name}")
        print(f"  峰值item QPS≈{q['item_peak_qps']} (限流阀值10) | 搜平均{q['search_avg_qps']}")
        print(f"  推荐: {rec['tier']} | 年费 {rec['year_cost']} | {rec['reason']}")
        print()

• 微型单店 → L1免费，0元

• 100SKU防超卖 → 峰值3.3QPS但need_realtime_stock=True → 基础包¥980~1980

• 500SKU 30s → 峰值16.7QPS>10 → 基础包

• 1500SKU → 峰值50QPS → 企业包¥1980~2980

六、一句话选型定性

1688的“免费”是真的（L1基础同步零调用费），但QPS 10是硬墙、基础stock_num是缓存库存；中小自研别急着买包，先令牌桶压8QPS跑一个月看水位；一旦做代发锁库存或监控超300SKU，¥980/年的基础资源包不是成本是保费——比超卖赔售后便宜两个数量级。按量付费层在1688里几乎碰不到，主线决策就是“免费用不用、包买哪档”。