Response Schema

五种类型覆盖了所有平台操作。同一个字段无论出现在哪里，含义都相同，而且每个概念只有一个名字——配送信息 在搜索卡片、商品、报价和运费报价中都是同一种形状。

可选字段是真正可选的：缺失表示平台没有给出该信息，而不是某个默认值。没有 price 意味着这条商品当前 没有在售报价，而不是免费。没有 delivery.cost 意味着运费尚未算出，而不是包邮——包邮是 delivery.free: true，那是另一个断言。

某个平台实际会填充哪些可选字段，差异很大；每个平台的文档里都有实测比例。

SearchResult

{
  "marketplace": "amazon",
  "query": "running shoes",
  "page": { "index": 1, "size": 48, "total": 1200 },
  "items": [ /* SearchItem */ ],
  "cursor": "…"
}

Facet

站点针对本次查询给出的筛选栏。缺失表示没有返回筛选栏；[] 表示本次查询没有筛选栏。

value 就是你在 facets 请求参数里回传的内容。它是可读的标签，而不是内部 id。

当 maps_to 存在时，优先使用那个类型化参数：它在每个平台上含义相同。

SearchItem 与 Product

两者都扩展自同一种条目结构，因此同一个字段在结果卡片和商品详情页里含义一致。Product 只是补上了详情页 才有的内容。

两者共有

Money 是 {currency, amount}，其中 amount 以十进制主单位表示。

ext 是最后的手段：只要有含义相同的共享字段，信息就放进该字段；只有其他平台都没有的信息，才以该平台自己的 名称放进 ext。商品、变体、卖家、报价、评价、评价页和类目节点都可能带有它。

DeliveryOption

所有配送信息都是这一种形状——delivery、shippingOptions 的每一项、报价的 delivery，以及 ShippingQuote 的每个选项。

没有 cost 表示未说明，而不是包邮；包邮是 free: true。available: false 是一个答案，绝不等于运费为零。只要平台展示了，delivery 始终是适用于所有买家的选项—— 会员专享的包邮（Prime）带着 membership 放在 shippingOptions 中，绝不会被当作所有人的条件。

Seller

rating.grouped: true 表示该汇总覆盖整个变体系列，而不是所请求的那一个变体。该字段缺失意味着不确定 是否被合并，这比"确定是按变体统计的"要弱。

仅 SearchItem

仅 Product

变体，以及唯一需要检查的那件事

现实中存在两种变体模型，一个字段就能区分：

• 存在 variant.productId——该组合本身就是可单独获取的商品。把这个 id 回传给 product。Amazon属于 这一类。
• 没有 variant.productId——该组合只存在于这个商品内部，你需要的东西都已经拿到了。Shopify、Walmart 与AliExpress属于这一类。

你永远不需要知道自己在跟哪个平台打交道，检查这个字段即可。

Offer

平台会逐条列出时的竞争卖家：{seller?, price, listPrice?, condition?, conditionNote?, fulfilledBy?, inStock?, status?, delivery?}。delivery 是一个 DeliveryOption，因为更便宜但发货更晚的报价是另一个报价。

ReviewPage

{
  "marketplace": "walmart",
  "productId": "996425081",
  "summary": { "average": 4.6, "count": 1204, "distribution": { "5": 78 } },
  "page": { "index": 1, "size": 10, "total": 990 },
  "reviews": [ /* Review */ ],
  "grouped": true
}

没有评价的商品

它会以明确的零返回 200，因此你可以放心地显示"0 条评价"：

{ "marketplace": "shopify", "productId": "shop.com/handle", "page": { "index": 1, "size": 0, "total": 0 }, "reviews": [] }

page.total: 0 只在商品确实没有任何评价时才会发出。如果有证据表明该商品确实有评价但取不到——报出了 条数或平均分，或者商品页上能看到评价——你会收到一个错误，而绝不是零。因此一个空的 reviews 数组只可能 意味着两件事之一，而 page.total 会告诉你是哪一件：

返回零时不会有 summary：没有平均分可报。

grouped 是必须披露的事实，而不是细节。商家可以用整个系列的 9,000 条评价来回答某一种颜色的页面，而评价 本身不会有任何提示——在被合并的页面上计算"这个商品的评分"，得到的是整个系列的评分。

review.incentivized: true 表示平台将这条评价标注为获得回报（免费商品、样品、奖励）后撰写；没有该字段只表示 没有标注，绝不代表"确认未获回报"。review.reply 是商家的公开回复，形如 {body, date?, author?}。

当平台给出时，review.variant 会指明该评价是针对哪一个同系列商品写的。在被合并的页面里，variant 为空表示 平台没有说明，绝不表示"这条是针对你所请求的那个商品的"。

page.total 与 summary.count 统计的对象不同：一个商品可以报出 7,654 个评分，而它的评价列表只收录 990 条带文字的评价。 count 忠实于商品，total 忠实于列表。两者都不保证每条评价都能取到：各平台对可翻页的深度设有上限，cursor 结束时列表即结束。

CategoryList

categories 返回的内容：一份扁平列表，每个节点都指明自己的父级。之所以扁平而非嵌套，是因为常见的请求是 "整棵分类树"，而嵌套会让它在传输上更大、也更难分页。重建树结构只是按 parentId 做一次 groupBy。

{
  "marketplace": "aliexpress",
  "path": [ { "id": "200000345", "name": "Women's Clothing" } ],
  "categories": [
    { "id": "349", "name": "Skirts", "parentId": "200000345" },
    { "id": "201531101", "name": "Matching Sets", "parentId": "200000345" }
  ]
}

CategoryNode

与本结构的大多数字段不同，id 与 name 都是必填。类目列表存在的意义就是被使用：没有 id 的条目无法 使用，没有名称的条目无法阅读。

browsable——最值得仔细读的一个字段

缺失表示可以，这也是常态。false 标记的是真实存在、可以导航，但背后没有商品列表页的层级。

这里的每个平台都有这样的层级，而且并非个别情况：

遇到这种情况时，用 categories 再下钻一层，那里的 id 就可以列出商品了。

给 categories 传 browsableOnly=true，只会得到 browse 接受的 id——费用与何时返回 400，见 平台概览。

你不必信任这个标志

browsable 只在已经确认的情况下才会被填上，因此一个无法列出商品的层级仍可能以缺失该字段的形式——也就是 乐观地——返回给你。在Walmart上这无法避免：Electronics（3944）与 Toys（4171）都是有子类目的部门，其中 一个会列出商品，另一个不会，而分类数据里没有任何东西能区分它们。

所以 browse 会直接告诉你。对一个没有商品列表页的类目发起请求，返回的是

{ "success": false, "error": { "code": "CATEGORY_NOT_BROWSABLE", "message": "Walmart category 4171 is a navigation hub…" } }

而不是一个空列表——因为售罄的类目返回的同样是空列表，你将无从分辨"请下钻到子类目"与"这里没有在售商品"。 请把这个代码当作一条指令：用同一个 id 调用 categories，再浏览它的某个子类目。它是 400，而不是请求失败： 重试不会改变答案。

ShippingQuote

shipping 返回的内容：一件商品发往一个地区的全部配送方式，最便宜的在前。

{
  "marketplace": "aliexpress",
  "productId": "1005012143419303",
  "skuId": "12000057632572864",
  "region": "US",
  "quantity": 1,
  "available": true,
  "options": [
    { "carrier": "YunExpress Standard Shipping", "cost": { "currency": "USD", "amount": 3.13 },
      "free": false, "minDays": 7, "maxDays": 15, "guaranteedDays": 60,
      "estimate": "Oct. 30 - Nov. 07", "tracking": true, "shipsFrom": "CN" }
  ]
}

options 是 DeliveryOption。available: false 且没有选项，表示平台不向该地区发货—— 这是一个答案，而不是错误。

错误

{ "success": false, "error": { "code": "INVALID_PARAMS", "message": "…" } }

501 有意不是 404："这些评价无法提供"绝不能被读成"这个商品没有评价"。