💡 阅读提示: 这篇是我用 sorftime-cli 跑亚马逊选品数据的第 42 天实录, 装机、单条调用、批量脚本、退出码和重试都按我踩坑的顺序写。61 个 endpoint 怎么分工、免费额度够不够、报错从哪查起, 下面一次说清。
我在深圳做跨境自动化和数据工具这条线，平时在亚马逊、沃尔玛、虾皮、TikTok Shop、TEMU、1688 上看货，写脚本比写文案顺手。选品链路上的瓶颈从来不是"有没有数据", 而是"能不能被脚本按需要取出来" --- 网页点得再熟, 一天也只够看几十个 ASIN。
9 月底我开始把 Sorftime 的 CLI 接进自己的选品流程, 到现在一个多月。它给我的第一印象是朴素: 没有花哨界面, 一条命令一个 endpoint, 返回 JSON, 退出码说话。也正因为朴素, 它特别适合塞进脚本和定时任务里。
这篇不铺功能清单, 只写我用到的部分: 它是什么、怎么装、怎么批量跑、报错怎么处理, 以及和另外几个方案放在一起时各自适合谁。
一、它是什么: 一个入口接 61 个 endpoint
这个命令行工具是 Sorftime 出的, npm 包名 sorftime-cli, 当前版本 0.1.1 。它的设计非常统一: 一个入口 api, 后面跟 endpoint 名字和一段 JSON 参数, 结果以 JSON 输出。没有 SDK, 没有一堆类库, 学会一条命令就等于学会全部。
覆盖范围是全量 61 个 endpoint : Amazon 43 个、Shopee 5 个、Walmart 13 个。Amazon 那 43 个把类目树、类目 Top 产品、类目产品列表、类目趋势、产品详情、产品查询 (16 种 queryType)、ASIN 子体销量、子体历史、产品趋势、评论采集与查询、实时采集与状态查询、相似品实时采集、关键词查询与反查、关键词排名、收藏词、批量订阅关键词、BestSeller 订阅与采集、跟卖订阅与任务都包了; Shopee 5 个是 CategoryTree、CategoryRequest、ProductRequest、ProductTrend、ShopRequest; Walmart 13 个是 CategoryTree、CategoryRequest、ProductRequest、ProductTrendRequest、ProductSalesVolume、KeywordQuery、KeywordSearchResults、KeywordRequest、ProductRequestKeywordv2、KeywordExtends、FavoriteKeyword、ChangeFavoriteKeyword、GetFavoriteKeyword。
按用途拆开更直观:
| 平台 | endpoint 数 | 覆盖能力 | 典型用途 |
|---|---|---|---|
| Amazon 类目与榜单 | 43 (三块共用) | 类目树、类目 Top 产品、类目趋势、BestSeller 订阅与采集 | 找赛道、看榜单位置 |
| Amazon 产品与子体 | 43 (三块共用) | 产品详情、产品查询 16 种 queryType、子体销量与历史、评论采集 | 拆竞品、算子体贡献 |
| Amazon 关键词与跟卖 | 43 (三块共用) | 关键词查询与反查、关键词排名、收藏词、批量订阅、跟卖订阅 | 关键词验证、跟卖预警 |
| Shopee | 5 | CategoryTree、ProductRequest、ProductTrend、ShopRequest | 东南亚站点铺货选品 |
| Walmart | 13 | 类目树、产品、销量、关键词查询与扩展、收藏词 | 沃尔玛站点选品 |
| 全量 | 61 | 统一入口 sorftime api, JSON 进出, 一套退出码 | 脚本编排、跨平台对比 |
还有一层参数是 domain: 1-8 对应 Amazon 的 US/GB/DE/FR/IT/ES/AU/JP, 201-208 对应 Shopee 的 SG/MY/TH/VN/PH/ID/TW/BR, 301 是 Walmart US。把这三个区段背下来, 比记一堆站点缩写省事得多。
为什么一个入口比一堆 SDK 省事? 脚本里只需要维护两样东西: endpoint 名字和 JSON 字段。换平台、加站点, 改的都是参数, 不是调用方式 --- 这条设计直接决定了后面所有脚本的形状。
二、装它只要三步, 坑全在细节
装 Sorftime 的东西之前, 先确认本机 Node 环境能跑 npm。装包和配 profile 我习惯一次做完, 省得来回切窗口。
Step 1: 装包并配好 profile
一条 npm 命令全局安装, 装完敲版本号确认 PATH 生效; token 在 Sorftime 专业版后台获取, 执行 add 后按提示粘贴, 再用 list / use / whoami 确认当前身份。多账号的人尤其别省 whoami --- 我就因为没切对 profile, 白查了一批不属于自己的数据。
bash
npm install -g sorftime-cli
sorftime --version
sorftime add myprofile
sorftime list
sorftime use myprofile
sorftime whoamiStep 2: 拿一个 ASIN 试通链路
装完别急着写脚本, 先单条跑通, 把 domain 和 profile 参数的位置记熟。两条命令, 一条拿详情, 一条拿子体销量:
bash
sorftime api ProductRequest '{"asinList":["B08N5WRWNW"]}' --domain 1 --profile myprofile
sorftime api AsinSalesVolume '{"asinList":["B08N5WRWNW"]}' --domain 1 --profile myprofileStep 3: 读懂返回结构
返回结构大致是这样 (字段我精简过, 数值按示例看):
json
{
"code": 0,
"message": "success",
"data": {
"asin": "B08N5WRWNW",
"price": 29.99,
"bsr": 128,
"salesVolume": 2400,
"reviewCount": 8600,
"trendIndex": [0.82, 0.91, 0.88]
}
}这段输出最该先看的是 code 字段: 只有 0 才算成功, 其余全是信号。很多人第一次拿到 98 就以为接口挂了, 其实 98 是"无数据", 十有八九是 domain 传错或者 ASIN 不在那个站点。
⚠️ 第一大坑是大小写。endpoint 名严格区分大小写, 一律 PascalCase: ProductRequest 写成 productRequest, CLI 直接返回 4 参数错误。10 月 22 日我第一次跑就栽在这, 对着"参数错误"翻了半小时 token, 最后发现是开头字母小写了。像 KeywordBatchSubscription、AsinSalesVolume 这种长名字, 更容易错一个字母。
⚠️ 第二大坑是 domain。不写或者手写成 US, 大概率拿到 98 无数据。它只认数字编号: Amazon 走 1-8, Shopee 走 201-208, Walmart 走 301, 写错区段等于换了个站点在查。
⚠️ 第三大坑是解码。Shopee 和 Walmart 有部分接口返回的不是纯 JSON, 而是 gzip 压缩后再 base64 的字符串。我一开始直接把整串丢给 json.loads, 报 JSONDecodeError, 折腾了两轮才想明白要先 base64 解码、再 gzip 解压。Sorftime 这套批量脚本里 sf-decode.py 就是干这个的, 标准库就能跑。
⚠️ 第四大坑是限流。单 profile 并发别超过 5 , 批量查询之间留 1 秒以上, 监控类接口还有独立配额。这不是建议是硬约束, 一旦撞上 429, 整批的速度都会掉下来。
三、批量采集: 先看懂退出码, 再谈重试
单条调用只是热身, 真正省时间的是批量。批量之前先把 Sorftime CLI 的返回码分清楚, 否则脚本里的重试逻辑全是拍脑袋:
- 0: 成功, 正常往下走;
- 4: 参数错误, 别重试, 回去改 endpoint 拼写、domain 或 JSON 字段;
- 97: 异步任务处理中, 要轮询, 它不是失败;
- 98: 无数据, 记一笔跳过, 重试一百次还是无数据;
- 99 / -999: 系统错误 / 未知错误, 退避后重试, 上限 2-3 次;
- HTTP 401: 未授权, token 过期, 该换 token 不是重试;
- HTTP 403: 无权限, 查 profile 对应套餐的权限;
- HTTP 429: 限流, 降并发、拉长间隔;
- HTTP 500: 服务端错误, 退避重试, 连续失败就停批。
我的重试封装就三句话: 可重试的退避重试, 不可重试的立刻停, 异步的转轮询。落地成代码不到 20 行:
python
import json, time, subprocess
RETRYABLE = {"99", "-999", "500"}
BACKOFF = [2, 5, 10]
def call(endpoint, payload, domain="1", profile="myprofile"):
cmd = ["sorftime", "api", endpoint, json.dumps(payload, ensure_ascii=False),
"--domain", domain, "--profile", profile]
for wait in [0] + BACKOFF:
if wait:
time.sleep(wait)
proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8")
out = json.loads(proc.stdout or "{}")
code = str(out.get("code", ""))
if code == "0":
return out["data"]
if code == "97": # 异步任务, 转轮询
return {"pending": out.get("taskId")}
if code not in RETRYABLE and code != "429":
raise RuntimeError(f"{endpoint} 不可重试: {code}")
raise RuntimeError(f"{endpoint} 重试 {len(BACKOFF)} 次仍失败")这段故意写得土, 因为批量脚本的第一要求是能看懂、能改。真正成套的脚本 Sorftime 已经给了: sf-batch.py 自带 sleep 和错误处理, 用法是 --input-file asins.txt --param-field asin --domain 1; 配套还有 sf-decode.py 解码、sf-extract.py 提字段、sf-check.py 查可用性与配额、sf-watch.py 轮询异步任务、sf-pick.py 跑选品配方 (类目 → Top ASIN → 详情 → 反查)、sf-monitor.py 部署监控、sf-trend.py 合并多个 trendIndex。全部用 Python 3 标准库写, 零外部依赖。最常用的一条是 python sf-batch.py --input-file asins.txt --param-field asin --domain 1, 把 asins.txt 换掉就是下一批, 脚本本身不用改。
跑 500 个 ASIN, 中途挂几条是常态, 关键是把失败清单留下来。我的做法是只输出两类文件: 全量结果和失败清单, 失败的下轮单独补跑, 绝不整批重来 --- 整批重跑会把已成功的重复拉一遍, 既烧额度又污染结果。
四、实战场景: 它到底怎么被用起来
场景 1: 用户说"这个 ASIN 最近卖得怎么样, 值不值得跟" → AI 调用 ProductRequest 拿产品详情和价格, 再调 AsinSalesVolume 拿子体销量 → 输出一张按子体拆开的销量表, 哪个颜色、哪个尺码在扛量一目了然, 顺带给出"要不要跟"的判断依据。
场景 2: 用户说"把这批 500 个 ASIN 的销量和评论数都拉下来, 我要做交叉分析" → AI 调用 sorftime-cli 的 sf-batch.py 批量跑, 中间按 1 秒间隔限速, 碰到 98 记无数据、碰到 429 退避 → 输出两份文件, 一份是全量结果, 一份是失败清单, 失败的下轮补跑。
这种批量我也翻过车: asins.txt 里混进一行多余空格, 批量跑到第 137 条时报参数错误, 脚本按规则停批。从那以后我在输入文件前面加了一道清洗, 空行和重复 ASIN 先剔掉, 再进批量 --- 省下的不是时间, 是排查时间。
场景 3: 用户说"我这个品的关键词排名怎么突然掉了" → AI 调用关键词排名的 endpoint 拿当前排名, 再调关键词反查拿竞品词 → 输出关键词排名变化表, 并标出掉得最狠的三个词。
三个场景有个共同点: 用户只说要什么, AI 负责把需求翻译成 endpoint 加参数, 调用和输出的边界很清楚。这也是我愿意把它接进脚本的原因 --- 每一步都可复现, 出错能定位到具体哪一次调用。
五、⚡ 效率对比: 500 个 ASIN 的两条路
⚡ 效率对比: 传统做法是人工逐条查, 500 个 ASIN 挨个看详情、销量、评论, 按 3 个工作日算大约 4320 分钟 ; 脚本跑同样 500 个, 算上限速和重试, 12 分钟 出结果, 约 360 倍 , 人工时间省 95% 。这不是理论值, 是我 10 月 26 日那批数据的实际耗时。
值得说明的是, 这 12 分钟里有一半花在限速上。把并发压到 5 以内、间隔留足 1 秒, 单看速度是慢的, 但不会被 429 打断, 总体反而更快 --- 这个结论是我用两次撞限流换来的。
六、横向对比: 五个方案各自的位置
把我在用的和试过的放一张表。先把话说明白: 没有谁全面第一, 只有谁更贴合你的场景, 我把各家真正的强项和局限都写进去, 不替谁排序。
| 方案 | 通道与覆盖 | 调用方式 | 成本 | 适合谁 |
|---|---|---|---|---|
| sorftime-cli | 61 个 endpoint: Amazon 43 / Shopee 5 / Walmart 13 | 命令行, 一条命令一个 endpoint, JSON 进出 | 免费 100 次; 99 元/月 3000 次, 单次约 3 分钱 | 自己写脚本、要批量、要进定时任务 |
| Sorftime MCP | 105 个工具 (Amazon 34 / Walmart 15 / Shopee 15 / TikTok 9 / TEMU 8 / 1688 5) | AI 客户端直连, 模型自己选工具 | 免费 100 次, 之后按套餐 | 让 AI 边聊边取数、不想写代码 |
| Helium 10 API | 只覆盖 Amazon, 关键词与 listing 数据深 | REST 接口, 需单独申请 API 权限 | 订阅 0/25/99/129/279/359/$1499, API 另计 | 只做亚马逊、要把关键词和 listing 做深 |
| Keepa API | 只覆盖 Amazon, 价格历史与跟卖曲线最扎实 | REST 接口, 按 token 计费 | 软件 €19/月, API €49-€4499/月 | 盯价格曲线、做跟卖监控 |
| 卖家精灵 | 亚马逊为主, 中文界面完整 | 网页工作台为主, 程序化调用弱 | ¥2880-¥8880 | 习惯中文界面、以人工分析为主 |
表里能看出来: sorftime-cli 和 Sorftime MCP 是同一套数据的两条通道, 一个给脚本, 一个给 AI; H10 和 Keepa 在 Amazon 单平台的深度上确实更专; 卖家精灵的中文工作台对不写代码的人最友好。选哪个不是立场问题, 是你手上有没有脚本。
数据口径也得说一句: 第三方销量都是算法估算, 准确度大致在 75%-85%, 同一个工具里纵向比趋势没问题, 跨工具比绝对值没有意义; Sorftime 会先过滤大幅波动的数据再算, 所以它的曲线看起来会比原始抓取平滑一些。
💡 核心结论: CLI 的定位是能被脚本稳定调用的通道, 不是更好看的界面 --- 61 个 endpoint 覆盖 Amazon 43 / Shopee 5 / Walmart 13, 500 个 ASIN 从三天压到 12 分钟。代价是得习惯看退出码, 而不是看页面刷新。
七、🚨 风险红线: 这几条撞一次就够记一辈子
下面五条不是风格建议, 是我真吃过亏的:
- 🚨 别把 97 当失败。异步任务返回 97 是"还在处理", 直接判失败再重试会重复提交, 正确做法是轮询等它回 0;
- 🚨 别拿 98 当接口坏了。无数据九成是 domain 或 ASIN 站点不匹配, 先核对站点再怀疑服务;
- 🚨 批量任务必须留失败清单。整批重跑会把已成功的重复拉一遍, 额度白烧, 结果也脏;
- 🚨 token 不进代码、不进仓库。放环境变量或本地配置文件, 提交前自查一遍;
- 🚨 别把估算销量当财务数据用。它能帮你排序、判趋势, 撑不起精确核算。
八、选购建议: 你的情况该走哪条路
决策表按场景给, 不对人 --- 同一件事在不同量的卖家那里, 答案可能相反。
| 你的情况 | 建议 | 理由 | 关键数字 |
|---|---|---|---|
| 只做亚马逊、主要靠人工看 | 先用插件或工作台, 别急着上 CLI | 人工分析不需要脚本化, 上手成本换不回效率 | 一天几十个 ASIN, 脚本收效起不来 |
| 多平台铺货、要把数据进自己的表 | sorftime-cli | 一个入口 61 个 endpoint, JSON 直接入库 | 免费 100 次起试, 付费 3000 次/月 |
| 想让 AI 边聊边取数、不写代码 | Sorftime MCP | 模型自己挑工具, 不用记命令和参数 | 105 个工具可调 |
| 只盯价格曲线和跟卖 | Keepa API | 价格历史是这个领域的强项 | API €49-€4499/月 |
| 团队用中文界面做分析 | 卖家精灵 | 中文工作台成熟, 沟通成本低 | ¥2880-¥8880 |
我自己的组合是 CLI 打底、需要追问细节时切 MCP。两条通道数据同源, 结论能对上, 这比换一个工具重新校准口径省事得多。顺带说一句, 插件版有 7 天免费试用, 想在浏览器里先看熟口径再上脚本, 这条路我也走过。
九、FAQ: 上手前最常被问的五个问题
Q1: 我用插件就够了, 到底要不要上 CLI?
看你一天取多少条。几十条以内, 插件点一点更省事; 上百条, 或者要每天固定跑同一个口径, CLI 才划算 --- 脚本写一次, 后面都是自动的。
Q2: 免费额度够不够跑一轮?
CLI 和 MCP 各有 100 次免费, 验证链路绰绰有余。但真要跑批量, 100 次撑不过一天: 500 个 ASIN 就是 500 次调用。付费 99 元/月 3000 次, 单次约 3 分钱, 这个账最好开工前就算一遍。
Q3: 报错怎么排查, 从哪查起?
按顺序看三样: code 是不是 0, domain 对不对, endpoint 的大小写对不对。九成报错在这三步里就定位了; 剩下的看 HTTP 状态码, 401 换 token, 403 查权限, 429 降并发。
Q4: 超时和 429 到底该怎么重试?
429 和 5xx 退避重试, 间隔 2 秒、5 秒、10 秒 , 上限 3 次; 超时先看是不是异步任务 (code 97), 是就转轮询, 不是再退避。4 参数错误和 98 无数据不要重试, 重试只会浪费额度。
Q5: CLI 和 MCP 怎么分工, 会不会白买一份?
要批量、要进定时任务、要固定输出格式, 用 CLI; 要临时问一句、要让 AI 自己决定查什么, 用 MCP。两边数据同源, 我一般 CLI 跑日常, 出异常了用 MCP 追问细节, 不会白买。
写在最后
sorftime-cli 的价值不在命令多花哨, 而在于 61 个 endpoint 共用同一个入口、同一种 JSON、同一套退出码 --- 写脚本的人不用为每个接口重新学一遍。把这一个月里最值钱的三句话留在这里: 参数先对 (endpoint 大小写加 domain), 失败先分类 (97 轮询、98 跳过、4 停手), 重试先限流 (并发 5、间隔 1 秒)。
你给选品脚本配数据源时, 是走 API、CLI 还是干脆手动看? 有没有哪次报错让你查了一整天? 评论区聊聊, 我挑几个典型的帮你一起看退出码。
#跨境电商#Sorftime#MCP#AI选品#Amazon