MPSTATS Open API

直连 MPSTATS 官方 API，覆盖 Wildberries + Ozon + Yandex Market 三平台，无第三方网关中转。

🔑 第 0 步（强制）：先确认 API Token

任何取数动作之前，必须先确认 MPSTATS_TOKEN 是否已配置。 这是不可跳过的第一步。

检查顺序

1. 读 config/.env 中的 MPSTATS_TOKEN
2. 读环境变量 MPSTATS_TOKEN
3. 若两者都没有 → 立即向操作者索要，并停止后续动作

索要话术（直接使用）

开始查询前，我需要你的 MPSTATS API Token。

获取路径：登录 mpstats.io → 个人面板（https://mpstats.io/userpanel）→ 「API token」区块 → 复制。
注意：MPSTATS 需要有效订阅，Token 才会可用。

请把它配置到以下任一位置：

  方式一（推荐）：在本 skill 的 config/.env 中写入：
    MPSTATS_TOKEN=你的token

  方式二：设置环境变量 MPSTATS_TOKEN

配置好告诉我，我先调用 user/report_api_limit 验证连通性并读取剩余额度。

两点提醒：
1. 请勿把 Token 直接贴在对话里，它只写进配置文件，我不会把它回显到任何输出或日志。
2. 修改账号密码、或在设置里点过「Change API token」，都会让旧 Token 立即失效——如果你刚做过这两件事，请重新复制一次 Token。

铁律

首调用示例

python scripts/mpstats.py quota

内部等价于：

GET https://mpstats.io/api/user/report_api_limit
X-Mpstats-TOKEN: <token>

返回：

{"available": 2500, "use": 38}

报告格式：已连通。套餐额度 2500 次，已用 38，剩余 2462 次。

接入信息

定位与边界

与 LinkFox 的关系：本 skill 是它的替代品，不是补充。 LinkFox 侧的 6 个 mpstats skill
全部只覆盖 Ozon，且要经网关中转；本 skill 直连 MPSTATS 原生接口，覆盖 WB + Ozon + YM 三平台，
可核实方法签名从 6 个工具扩到 188 条，也不再依赖 LINKFOXAGENT_API_KEY 与 LinkFox 的积分体系。

LinkFox 完全没有、本 skill 原生独有：WB 全部 118 个方法、YM 全部 20 个方法；
相似商品四族（40 方法，含反向「谁在蹭我」）；主题/利基 subject/*；
季节性 season_effects/* 与 AI 预测 forecast/*；尺码/颜色库存；
四级分仓；品牌口碑三件套；卡片变更史 photos_history；地域分布。

与 Seerfar skill 的职责边界（重要——划不清会重复取数、白耗两边额度）：

两条 skill 都配好时：同一个问题只在一个数据源上取数，不要两边各拉一遍；
若两边数字不一致（第三方估算模型不同），汇报时必须写明数据来源，不得混合成一张表。

端点规模（188 条可核实方法签名）

> 口径声明：官方 README 自述「122 端点」，不同提交出现过 122 / 125 / 127 三种表述，
> 差异源于计数口径（相似商品四族是否按族计数等）。本 skill 以可逐条核对的 188 条方法签名为准，
> 完整清单见 references/wb-endpoints.md / ozon-endpoints.md / ym-endpoints.md。

调用规范（硬约束）

额度

• 不是按次积分，是按订阅套餐内的调用次数计数
• 查额度：GET user/report_api_limit → 剩余 = available - use
• 单任务预估调用 > 50 次 → 先报告预估并等待确认
• 额度不足以完成任务 → 先报告，再决定

限流

• 速率上限取决于订阅套餐，官方未公布固定秒级数值
• ⚠️ 不要把 Seerfar 的「3 次/3 秒」套用到本 API
• 收到 429 → 读 message 字段了解细节，读 Retry-After 响应头获得等待秒数，按该秒数退避后重试
• 批量任务：串行，不并发

分页

• 请求体固定为 {startRow, endRow, filterModel, sortModel}
• startRow 从 0 起；endRow - startRow 即本页条数；endRow 单请求上限 5000
• 响应 total 是未分页总行数，用它判断还要不要继续翻页
• 按需取数，不要盲目拉满

参数陷阱

错误码处置

脚本用法

主入口是纯 Python 标准库实现（scripts/mpstats.py），三平台通用。

> ⚠️ SkillHub 分发包不含 mpstats.cmd（平台按扩展名白名单校验，不收 .cmd）。
> Windows 用户直接 python scripts/mpstats.py <子命令> [...] 即可，功能与启动器完全一致；
> 需要 .cmd 时可自建（见 scripts/README.md 中的一行模板）。

通用入口（任意方法 / 路径）

python scripts/mpstats.py raw GET  user/report_api_limit
python scripts/mpstats.py raw POST analytics/v1/wb/category/items \
  'path=Женщинам/Одежда/Футболки&d1=2026-08-01&d2=2026-08-31' \
  '{"startRow":0,"endRow":50,"filterModel":{},"sortModel":[{"colId":"revenue","sort":"desc"}]}'

语义化子命令

# 额度
python scripts/mpstats.py quota

# ── Wildberries ──
python scripts/mpstats.py wb-categories
python scripts/mpstats.py wb-category  --path "Женщинам/Одежда/Футболки" --d1 2026-08-01 --d2 2026-08-31 --rows 50 --sort revenue:desc
python scripts/mpstats.py wb-category-stats --path "Женщинам/Одежда" --report categories --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-subjects
python scripts/mpstats.py wb-subject  --id 70 --report items --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-brand    --path "adidas" --report items --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-seller   --id 123456 --report items --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-sku      --id 152490541 --report full
python scripts/mpstats.py wb-sku      --id 152490541 --report keywords --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-similar  --family similar --id 72124874 --report items --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py wb-season   --scope category --path "Женщинам/Одежда" --report annual
python scripts/mpstats.py wb-compare  --scope subject --id 70 --d1 2026-07-01 --d2 2026-07-15 --d3 2026-07-16 --d4 2026-07-31

# ── Ozon ──
python scripts/mpstats.py oz-categories
python scripts/mpstats.py oz-category --path "Автотовары" --d1 2026-08-01 --d2 2026-08-31 --rows 50
python scripts/mpstats.py oz-brand    --path "Samsung" --report categories --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py oz-seller   --id 3628678 --report items --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py oz-sku      --id 1786874757 --report full
python scripts/mpstats.py oz-sku      --id 1786874757 --report keywords --d1 2026-08-01 --d2 2026-08-31

# ── Yandex Market ──
python scripts/mpstats.py ym-category --path "Электроника/Смартфоны" --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py ym-brand    --path "Samsung" --report categories
python scripts/mpstats.py ym-seller   --path "Эльдорадо" --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py ym-seller   --path "Эльдорадо" --report categories --d1 2026-08-01 --d2 2026-08-31
python scripts/mpstats.py ym-sku      --id 12345678 --d1 2026-08-01 --d2 2026-08-31

脚本行为约定：

• 自动从 config/.env → 环境变量 读取 MPSTATS_TOKEN
• Token 缺失时报错退出并打印索要话术，不发起任何请求
• Token 一律不回显（输出里只出现 Token: *** 或完全不提）
• 内置串行节流；遇 429 按 Retry-After 自动退避重试（最多 2 次）
• 统一输出格式化 JSON 到 stdout
• 非 200 响应以非零退出码返回，并打印错误码含义
• --dry-run 只打印将要发出的请求（Token 打码），不实际发送—用于参数自检

机器可读的参考文件（按需读，不要一次性全读）

场景 → 端点映射（选了就用）

输出规范

1. 金额单位：₽（卢布）；如平台返回已换算币种，必须说明
2. 指标标注：必须写英文 API 字段名 + 中文释义
3. 俄语对照：类目路径、品牌、关键词一律「俄语原文 + 中文释义」双列
4. 时间与口径：注明 d1–d2、平台、是否含 fbs
5. 异常标注：呈现任何数字前先过 references/anomaly-check.md；异常按规程显式标注
6. 预测标注：引用 forecast/* 必须写明「模型预测值，非事实」
7. 置信度：每次输出标注 高 / 中 / 低
8. 风险提示：第三方估算数据，与平台后台可能有偏差

红线

1. 不把 Token 写入任何输出、日志或交付文件
2. 未配置 Token 时不发起业务请求；401 时停止而非重试
3. 不编造 API 未返回的数值
4. 不静默丢弃异常值，也不把异常当真实值汇报
5. 不做收益承诺（不说「必赚」「稳赚」）
6. 不协助侵权、仿品、违禁品类
7. endRow 不超过 5000
8. 批量调用不并发（串行 + 按 Retry-After 退避）
9. 引用 forecast 必须标注为模型预测