1stDibs API 参考

调用约定

共有 4 个 action，均以 POST /api/v1/firstdibs/ 加 action id 的方式调用：`post-1stdibs-search`（POST /api/v1/firstdibs/post-1stdibs-search）、`post-1stdibs-filters`（POST /api/v1/firstdibs/post-1stdibs-filters）、`post-1stdibs-detail`（POST /api/v1/firstdibs/post-1stdibs-detail）和 `post-1stdibs-seller`（POST /api/v1/firstdibs/post-1stdibs-seller）。输入放在 `body` 下的 JSON 对象中。只接受本参考列出的字段名：其他名称，例如 `q`、`limit`、`colour`、`item_id` 或 `dealer`，会作为未声明的键被拒绝。输入校验不检查 slug 与 id 的格式。

bodypost-1stdibs-searchpost-1stdibs-filterspost-1stdibs-detailpost-1stdibs-seller

post-1stdibs-search：范围输入

在这个 action 上，输入校验中的输入均为可选，但该 action 需要提供 `body.query` 或 `body.category` 之一；两者都缺失的请求能通过输入校验，但不满足这一要求，因此请始终提供其中之一。`body.query` 是与站点搜索框相同形式的自由文本，例如 `eames lounge chair`。`body.category` 是一到四层、以斜杠分隔的小写路径，与站点 URL 中的写法一致，例如 `furniture/seating/lounge-chairs`。`body.vertical` 取 `furniture`、`art`、`jewelry` 或 `fashion` 之一；它是顶级类目的简写，只要提供了 `body.category` 就会被忽略。slug 筛选 `body.style`、`body.period`、`body.material`、`body.origin`、`body.creator`、`body.location` 和 `body.color` 接受 1stDibs 的 slug，例如 `art-deco`、`20th-century`、`mahogany`、`austrian`、`nestor-toro`、`france-europe` 和 `blue`。年代还接受世纪 slug 以及 1920s 到 1990s 的十年 slug，对艺术品而言材质维度标注为 Medium。origin 是作品的制造地，location 是经销商的发货地；颜色维度由 1stDibs 根据照片判定。可用的 slug 取决于类目，1stDibs 不认识的值会使请求失败，而不会被丢弃。

post-1stdibs-searchbody.querybody.categorybody.verticalbody.stylebody.periodbody.materialbody.originbody.creatorbody.locationbody.color

post-1stdibs-search：价格、促销、排序与分页

`body.price_min` 和 `body.price_max` 是不小于 0 的美元数值；只给其中一个即可作为单侧边界。`body.on_sale` 是布尔值，默认 `false`；为 true 时只返回经销商已降价的商品。`body.sort` 取 `recommended`（默认）、`newest`、`price-high`、`price-low` 或 `popular` 之一；两种价格排序按美元标价排列。`body.max_results` 是 1 到 200 的整数，默认 50；设上限是为了控制响应大小和耗时。`body.page` 是 1 到 6001 的整数，默认 1。结果窗口在偏移量 6000 处结束：最后可达页为 6000 除以 `body.max_results` 再加 1，超出该页时 `page_exists` 为 false 且没有结果行。

post-1stdibs-searchbody.price_minbody.price_maxbody.on_salebody.sortbody.max_resultsbody.page

post-1stdibs-search：返回字段

返回的页面级字段包括 `total_available`、`page_size`、`last_reachable_page`、`has_more`、`applied_filters` 和 `results`。`results` 中的每一行含 `item_id`、`url`、`title`、`category_path`、`price`、`currency`、`price_status`、`discount_percent`、`is_sold`、`is_on_hold`、`creators`、`seller`、`ships_from_country` 和 `images` 等字段。`seller` 中的 `order_count` 与 `is_distinguished` 在这些列表行中为空，需从详情和店铺操作中获取。

post-1stdibs-searchdata

post-1stdibs-filters

输入：`body.query`、`body.category`、`body.vertical`、`body.style`、`body.period`、`body.material`、`body.origin`、`body.creator` 和 `body.location`，含义和规则与搜索相同，包括必须提供 `body.query` 或 `body.category` 之一（两者都缺失的请求能通过输入校验，但不满足这一要求），以及给出类目时忽略 `body.vertical`。这里没有颜色、价格、排序或分页输入。返回 `total_available`、`filter_count`、`categories`（所请求层级的子类目）和 `filters`；每个筛选项含 `name`、`label`、`value_count` 和 `values`，其中条目含 `value`、`label`、`count`、`linkable`、`currency` 和 `hex_code`。在存在对应参数时，筛选项的 `name` 就是它所对应的搜索输入名，筛选维度的集合取决于类目。

post-1stdibs-filtersbody.querybody.categorybody.verticalbody.stylebody.periodbody.materialbody.originbody.creatorbody.location

post-1stdibs-detail

`body.item` 是必填字符串：站点上显示的商品 id，例如 `f_52078502`（前缀为：家具 f_、艺术品 a_、珠宝 j_、腕表 v_），或一个 1stdibs.com 商品链接，id 从链接中的 /id- 路径段读取。一次调用可接受用逗号分隔的多达 10 个 id。返回 `requested`、`found`、`missing` 和 `items`。`items` 中的每个条目是在搜索行基础上增加字段，包括 `description`、`condition`、`condition_notes`、`materials`、`dimensions_display`、`seller_location`、`shipping`、`sku`、`listing_views_6m`、`schema_org_offer` 和 `price_mismatch`，最后一个字段报告标价与 schema.org 报价之间的不一致。

post-1stdibs-detailbody.item

post-1stdibs-seller

`body.seller` 必填：1stdibs.com/dealers/ 链接中的店铺 slug，例如 `morentz`，或完整的店铺链接。`body.sort`、`body.page` 和 `body.max_results` 的取值、默认值和边界与搜索相同，分页窗口同样在偏移量 6000 处结束。返回 `seller_slug`、含 `seller_id`、`name`、`order_count`、`is_distinguished` 和 `ships_from_country` 的 `seller` 信息块，以及 `total_available`、`page`、`page_size`、`page_exists`、`has_more` 和 `results`，其中的行与搜索结果行相同。

post-1stdibs-sellerbody.sellerbody.sortbody.pagebody.max_results

商品详情

POST /api/v1/firstdibs/post-1stdibs-detail

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "item": "f_52078502"
  }
}

null

筛选项与类目

POST /api/v1/firstdibs/post-1stdibs-filters

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "category": "furniture/seating/lounge-chairs"
  }
}

null

商品搜索

POST /api/v1/firstdibs/post-1stdibs-search

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "category": "furniture/seating/lounge-chairs",
    "max_results": 10
  }
}

null

经销商店铺

POST /api/v1/firstdibs/post-1stdibs-seller

使用 JSON 对象，按文档将参数放入 path、query、headers 和 body，省略未使用的位置。input.headers 是受结构校验的数据，不是浏览器请求头。请勿在此填写凭证。按文档保留 body 的数组、标量或 null；省略与 null 含义不同。

{
  "body": {
    "max_results": 10,
    "seller": "morentz"
  }
}

null