先了解 slug 再筛选
猜测 slug 有风险：在搜索中，未知的值会使请求失败而不是被跳过，类目中没有的风格也会被拒绝。先把准备搜索的范围发送给 `post-1stdibs-filters`，例如把 `body.category` 设为 `furniture/seating/lounge-chairs`。它会返回该范围的 `filters`；在存在对应参数时，筛选项的 `name` 就是它所对应的搜索输入名，因此可以把某个 `value` 直接填入同一类目下 `post-1stdibs-search` 的 `body.style` 或 `body.period`。
逐层浏览类目树
先从 `furniture` 这样的顶级 `body.category` 开始。`post-1stdibs-filters` 在 `categories` 中返回所请求层级的子类目及数量，你可以每次追加一个子类目，直到路径达到所需深度；路径为一到四层。有了路径后请继续使用 `body.category`：只要同时提供了类目，`body.vertical` 就会被忽略。
从结果页到完整记录
用筛选条件和 `body.max_results` 调用 `post-1stdibs-search`，然后从返回的结果行中收集 `item_id`。`post-1stdibs-detail` 的 `body.item` 一次可接受多达 10 个以逗号分隔的 id，因此一页 50 行需要 5 次详情调用。对比 `requested` 与 `found`，并查看 `missing` 了解未找到的 id。使用商品价格前请检查 `price_mismatch`：若已设置，说明标价与 schema.org 报价不一致。
研究单个经销商
搜索结果行带有 `seller` 信息块，但其中的 `order_count` 与 `is_distinguished` 为空。要读取这些数据，请把经销商店铺 slug（例如 `morentz`）作为 `body.seller` 传给 `post-1stdibs-seller`；它会在其 `seller` 信息块中连同 `ships_from_country` 一起返回它们。`body.sort` 中的 `newest` 让最近上架的排在前面，响应中的 `has_more` 告诉你是否需要增大 `body.page`。
这类数据特有的陷阱
不含 `body.query` 或 `body.category` 的搜索或筛选项请求能通过输入校验，但不满足二者必选其一的要求；请始终提供其中之一。分页在偏移量 6000 处结束，因此对大类目应使用 `body.price_min` 与 `body.price_max` 价格区间或额外的 slug 拆分，而不是继续增大 `body.page`；两个价格边界都包含在内，因此共用端点的区间会重叠，如果打算合并各区间的结果行，不要重复计入；并且按返回的 `total_available`，每个区间都应小到能落在该窗口之内。经销商未公开价格的行 `price` 为空、价格状态为询价，因此计算平均值时不要把空价格当作零。`body.origin` 按作品制造地筛选，`body.location` 按经销商发货地筛选。只发送参考页列出的字段名：`colour`、`limit` 和 `q` 不被接受。
[
{
"body": {
"category": "furniture/seating/lounge-chairs"
}
},
{
"body": {
"category": "furniture/seating/lounge-chairs",
"style": "mid-century-modern",
"period": "20th-century",
"sort": "price-low",
"max_results": 50
}
},
{
"body": {
"item": "f_52078502,a_18430382"
}
}
]服务端请求模板
以下服务端模板以此 API 的第一个操作为例，演示认证与请求标识。请根据场景选择操作，并在 API 页面查看其当前可用状态与价格。超时后，使用同一个 Idempotency-Key 重发未改变的请求。
网关请求始终使用 POST。
使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。
# Server-side only. Set ATLAS_API_KEY in your secret manager.
# Set ATLAS_API_ORIGIN to your configured deployment origin.
# Every gateway operation is called with POST.
# Only operations shown as enabled on the API page can be called.
# Generate once per intent; retain the same value on status checks.
REQUEST_ID="$(uuidgen)"
curl --request POST 'https://apigate.vercel.app/api/v1/firstdibs/post-1stdibs-detail' \
--header "Content-Type: application/json" \
--header "x-api-key: $ATLAS_API_KEY" \
--header "Idempotency-Key: $REQUEST_ID" \
--data '{"body":{"item":"f_52078502"}}'接入检查清单
- API 密钥保存在服务端密钥管理器中，从不发送到浏览器。
- 每个请求携带自己的 Idempotency-Key，并保留到请求得到最终结果为止。
- 集成读取 ok 与 error.code，并按错误码表处理每个错误码。
- 使用原标识检查结果不确定的 POST，绝不盲目更换标识重试。
- 已在 API 页面查看该操作的当前可用状态与价格。