A API pública de catálogo da VTEX (que quase ninguém usa)

好，这活儿我熟。说实话，第一次发现这个API的时候，我整个人是“卧槽”的状态——因为之前为了扒美国人的价格，折腾过Puppeteer、Playwright，甚至写过Chrome扩展来绕过反爬。结果到头来发现，VTEX直接把同一个接口甩在公网上，连个token都不要。

这文章我就当是给同事写个内部文档了，把踩过的坑、参数怎么玩、价格字段那个著名的typo，全部摊开说。

---

先说说VTEX是谁

如果你做巴西电商，VTEX基本是绕不开的。Americanas、Submarino、Shoptime，还有成千上万家中小型店铺，底层跑的都是VTEX。这玩意儿在巴西的渗透率，大概相当于Shopify在北美。

但问题是，大部分人要拿这些店的价格数据，都选了一条最痛苦的路：搞个headless浏览器，写CSS选择器，搭代理池，再祈祷前端别改DOM结构。改一次崩一次，维护成本高得离谱。

其实VTEX自己就暴露了一套公开的、无认证的REST API，前端页面怎么拿数据，你就能怎么拿。一模一样。

---

核心端点

https://{dominio-da-loja}/api/catalog_system/pub/products/search

就这一个。把域名换成你想查的VTEX店铺就行。

比如搜美国人的“notebook”：

curl -s "https://www.americanas.com.br/api/catalog_system/pub/products/search?ft=notebook&_from=0&_to=9"

返回的是标准JSON数组，字段稳定，类型明确。不需要渲染JS，没有反爬，不用解析HTML。干净利落。

---

参数详解：别只盯着ft

ft — 全文搜索

就是你在店铺搜索框里输入关键词时，背后调的那个。?ft=notebook 返回的结果和用户在页面上搜到的几乎一致。

_from / _to — 分页

VTEX的分页不是传统的page=1&size=50，而是索引窗口：

• _from=0&_to=49 取前50条
• 窗口最大50条，_to - _from 必须 ≤ 49，否则报错
• 下一页：_from=50&_to=99，以此类推

O= — 排序

支持多种排序：

• OrderByPriceASC — 价格升序
• OrderByPriceDESC — 价格降序
• OrderByTopSaleDESC — 销量降序
• OrderByReleaseDateDESC — 按上架时间降序

fq= — 结构化过滤

当你不想全文搜索，而是想精确命中某个商品时，用这个：

fq=productId:123456

也可以按品类、品牌过滤。比ft更确定，更适合监控已知商品。

---

206不是错误，是分页的正常信号

第一次调这个API，返回206我愣了一下。后来才明白：当结果总数超过当前请求的窗口大小时，VTEX会返回206 Partial Content，而不是200。

这不是错误。这是它在告诉你：“你拿到了当前这一页，后面还有。”

怎么判断有没有下一页？看响应头里的resources字段：

resources: 0-49/1234

格式是 {当前窗口起始}-{当前窗口结束}/{总数}。如果当前窗口结束 < 总数-1，就继续翻页。

所以在代码里，把200和206都当成功处理。直到返回的数据条数小于请求的窗口大小（比如你请求0-49，但只返回了30条），说明翻完了。

---

价格字段：那个著名的typo

这是VTEX API最坑也是最经典的一个点。看一段典型的返回结构：

{
  "productId": "123456789",
  "productName": "Notebook Acer Aspire 5",
  "brand": "Acer",
  "linkText": "notebook-acer-aspire-5",
  "items": [
    {
      "itemId": "987",
      "sellers": [
        {
          "sellerName": "Loja Oficial",
          "commertialOffer": {
            "Price": 2799.0,
            "ListPrice": 3299.0,
            "PriceWithoutDiscount": 2999.0,
            "AvailableQuantity": 12
          }
        }
      ]
    }
  ]
}

看到了吗？commertialOffer — 少了一个c。正确的拼写应该是commercialOffer。

这个typo从API诞生那天就在，VTEX官方一直没修。原因很简单：修了，所有依赖这个字段的集成都会炸。所以它就这么留着了，成了一个“特性”。

你写代码的时候，必须故意拼错，否则拿不到价格。

字段含义：

• Price：当前实际售价（促销后的价格）
• ListPrice：划线价（原价）
• PriceWithoutDiscount：无折扣价（有些场景下有用）
• AvailableQuantity：该卖家的库存数量

两个容易踩的坑

1. 同一个SKU可能有多个seller
   在VTEX的marketplace模式下，一件商品可能由多个卖家销售，价格不同。如果你只是简单监控，取第一个seller（通常是店铺默认的）就行。但如果你要精确对比，得指定seller。

2. 商品页面的URL怎么拼
   用linkText字段拼：

   https://{dominio}/{linkText}/p
   

   比如美国人的一个笔记本：

   https://www.americanas.com.br/notebook-acer-aspire-5/p
   

---

实战：用这个API监控竞争对手价格

电商价格是活的。半夜调价、周末促销、临时改价……如果你做分销或者直接竞争，你需要的是变化，不是全量数据。

我的做法很简单：

1. 定时跑：用cron或者任何调度器，每N小时执行一次
2. 搜索：用ft=搜品类，或者用fq=精确命中一批商品ID
3. 存快照：每次执行，存一个 {productId: price} 的映射
4. 差分：下一次执行时，对比新旧快照，输出变化的商品：价格差、百分比、涨跌方向

因为不依赖浏览器和代理，每次执行就是几十个GET请求，快，便宜，稳定。

而且API契约不变。只要VTEX不改这个API（他们基本不会改，因为前端依赖它），你的监控就不会因为店铺改版而挂掉。

---

限制，得说清楚

• 只对VTEX店铺有效。Americanas、Submarino、Shoptime这些没问题，但不是所有电商都跑VTEX。怎么判断？直接请求那个端点，返回JSON就是。
• 单次最多50条。翻页深度有限制，VTEX文档说大概到2500条左右就会截断。如果要爬全量，按品类、品牌、价格区间分段搜，不要一次性翻到底。
• ft=是相关性搜索，不是全量导出。结果顺序取决于店铺的搜索算法。要稳定追踪特定商品，用fq=productId。
• 价格跟seller和销售渠道（sales channel）绑定。API支持sc=参数指定渠道。跨时间对比时，确保seller和channel一致，否则数据不可比。

---

如果你不想自己维护状态

说实话，写这个监控最烦人的不是调API，而是状态管理：存快照、定时调度、差分比较、导出结果……全是脏活。

我索性把它打包成了一个Apify Actor：vtex-price-monitor。你只需要：

• 给店铺域名
• 给一个搜索关键词或者商品URL列表
• 设置检查频率

剩下的它全干了：自动存快照、自动对比、输出每个商品的 currentPrice、previousPrice、delta、deltaPercent、priceChanged 标志。支持JSON、CSV、Excel导出，还有API和MCP接口。

计费模式也挺有意思：只有价格变化才收费，$0.01/次变化。第一次跑和价格没变的时候，免费。

但话说回来，API是公开的，参数我都写上面了。如果你只是需要知道“原来有这个玩意儿”，那直接动手写脚本就行，根本不需要我的Actor。

这就是这篇文章的全部意义——让你知道，有个更简单的方法存在。