API 文档

库存搜索 API

通过编程方式访问跨零售商的实时球鞋库存数据。使用用户 API 密钥进行身份验证，支持按品牌、SKU、配色编号、尺码或关键词查询。

生成 API 密钥查看接口 →
Base URLhttps://api.sneakers.itbanque.com
认证头X-API-Key
响应格式JSON
请求方式GET
概览

你可以做什么

这是鞋价通的库存和市场接口，不是另一个产品。算上架价和底线价以本站说明为准，见上架价怎么算。

鞋价通 API 提供对多个零售商库存数据的直接访问。每个请求返回符合条件的分页 SKU 列表，每个 SKU 附带各门店的最新库存状态。

访问由用户级 API 密钥控制。密钥继承所属账户的速率限制和分页上限。

仅显示一次：密钥的原始 token 只在创建时显示一次。之后只有前 8 位前缀在账户页面可见。请在离开创建页面前将其保存到密钥管理工具中。
身份验证

X-API-Key 请求头

每个请求必须在 X-API-Key 头中传入一个有效且激活的密钥。后端将该密钥解析为对应的用户账户，并应用该账户的套餐限制。

请求头名称X-API-Key
密钥范围用户级
适用接口/v1/inventory/search
生成密钥

创建流程

  1. 登录后打开 /account。
  2. 滚动到 API 密钥部分，点击生成新密钥。
  3. 可选填写标签，用于标识该密钥的使用方。
  4. 点击创建。token 仅显示一次，请立即复制。
  5. 将 token 作为 X-API-Key 请求头的值传入每个请求。

可随时在账户页面撤销密钥，撤销立即生效。

请求格式

示例请求

请求方式GET
路径/v1/inventory/search
参数位置Query string
curl --request GET \
  --url 'https://api.sneakers.itbanque.com/v1/inventory/search?brand=Nike&limit=5&offset=0' \
  --header 'X-API-Key: sr_live_your_api_key'
查询参数

支持的参数

参数名类型是否必填说明
style_colorstring可选模糊匹配商品配色编号。
brandstring可选模糊匹配品牌名称。
retailerstring可选模糊匹配零售商代码或名称。
sizestring可选精确匹配规范化尺码值。
retailer_skustring可选模糊匹配零售商 SKU。
supplier_skustring可选模糊匹配供应商 SKU。
qstring可选跨配色编号、品牌、零售商、尺码、标题、SKU 的全文搜索。
limitinteger可选分页大小，默认 9。始终不超过套餐 max_page_size。
offsetinteger可选行偏移量，默认 0。开启 provider 权限时无页数约束；否则不超过 (max_page_number - 1) × max_page_size。
响应结构

返回数据

{
  "total_skus": 1284,
  "count": 2,
  "limit": 2,
  "offset": 0,
  "has_next_page": true,
  "items": [
    {
      "sku": {
        "id": 184221,
        "retailer": "NIKE",
        "size": "10.0",
        "retailer_sku": "HF1234-100",
        "supplier_sku": "HF1234",
        "title": "Nike Air Max 1 White University Red",
        "original_price": 140.0,
        "price": 119.99
      },
      "product": {
        "id": 55120,
        "style_color": "HF1234-100",
        "brand": "Nike",
        "model_name": "Air Max 1",
        "gender": "MEN"
      },
      "inventory": [
        { "location_code": "CA-ON", "stock_level": "HIGH", "as_of": "2026-04-30T14:52:18+00:00" },
        { "location_code": "US-NY", "stock_level": "LOW", "as_of": "2026-04-30T14:52:18+00:00" }
      ]
    }
  ]
}

Root

total_skus
分页前符合条件的 SKU 总数。
count
当前页返回的条目数。
limit
实际接受的分页大小。
offset
实际接受的偏移量。
has_next_page
布尔值，true 表示还有更多结果。
items
结果对象数组。

items[].sku

id
内部 SKU 标识符。
retailer
零售商代码，如 NIKE、JD_SPORTS、FOOTLOCKER。
size
规范化尺码值。
retailer_sku
零售商 SKU。
supplier_sku
供应商 SKU（如有）。
title
从来源抓取的 SKU 标题。
original_price
原始零售价（如有）。
price
当前抓取价格（如有）。

items[].product

id
内部商品标识符。
style_color
配色编号。
brand
品牌名称。
model_name
型号或产品系列名称。
gender
规范化性别值（如有）。

items[].inventory[]

location_code
门店或区域代码。
stock_level
最新库存状态：HIGH、MEDIUM、LOW、OOS 或 IN_STOCK。
as_of
该门店最新快照的 ISO 8601 时间戳。
SKU 历史记录

接口行为

返回指定零售商下某 SKU 的库存历史，按时间倒序。每条记录包含库存状态、门店代码、快照时间和当时价格。

若账户已开启该零售商的 download_provider 权限，历史记录条数不受 sku_history 约束，只受 hours 时间窗口限制。否则返回条数不超过套餐 sku_history 上限。
请求方式GET
路径/v1/reporting/retailers/{retailer}/skus/{retailer_sku}/history
认证X-API-Key
curl --request GET \
  --url 'https://api.sneakers.itbanque.com/v1/reporting/retailers/DICKS/skus/11943996/history?hours=4320' \
  --header 'X-API-Key: sr_live_your_api_key'

路径参数

参数名类型是否必填说明
retailerstring必填零售商代码，如 DICKS、NIKE、JD_SPORTS。
retailer_skustring必填零售商 SKU 编号。

查询参数

参数名类型是否必填说明
hoursinteger可选时间窗口（小时），默认 168（7 天），最大 8760（365 天）。
{
  "retailer": "DICKS",
  "cutoff_ts": "2026-04-01T00:00:00+00:00",
  "sku": {
    "retailer_sku": "11943996",
    "size": "10.0",
    "style_color": "HF1234-100",
    "model_name": "Air Max 1",
    "brand": "Nike"
  },
  "history": [
    { "stock_level": "HIGH", "location": "US-EAST", "record_created_at": "2026-04-28T09:14:00+00:00", "price": 119.99 },
    { "stock_level": "LOW", "location": "US-EAST", "record_created_at": "2026-04-21T07:30:00+00:00", "price": 119.99 }
  ],
  "count": 2,
  "limit": 5,
  "has_more": false
}

Root

retailer
零售商代码。
cutoff_ts
查询时间窗口起点的 ISO 8601 时间戳。
sku
SKU 基本信息对象。
history
历史库存记录数组，按时间倒序。
count
当前返回的记录条数。
limit
套餐允许的最大条数（provider 模式下为 null）。
has_more
布尔值，true 表示还有更早的记录未返回。

history[]

stock_level
库存状态：HIGH、MEDIUM、LOW、OOS 或 IN_STOCK。
location
门店或区域代码。
record_created_at
该条记录的快照时间（ISO 8601）。
price
当时抓取的价格（如有）。
StockX 市场数据

接口行为

通过 StockX style_id 查询该商品所有变体的最新市场数据。优先读取平台共享缓存（默认 TTL 为 1 小时），缓存未命中时向 StockX 发起实时请求并回填缓存。返回统一后的变体数组。具体缓存时效以账户套餐为准，如需更短的刷新周期，请联系升级套餐。

请求方式GET
路径/v2/stockx/market/search
认证X-API-Key
curl --request GET \
  --url 'https://api.sneakers.itbanque.com/v2/stockx/market/search?style_id=555088-711' \
  --header 'X-API-Key: sr_live_your_api_key'
参数名类型是否必填说明
style_idstring必填StockX 商品 style ID，如 555088-711。必须与 StockX 目录中第一个搜索结果精确匹配。
sizestring可选按尺码过滤，如 "9" 或 "10.5"。必须为数字。
forceboolean可选绕过缓存，直接从 StockX 获取最新数据。默认 false。

返回统一格式对象，包含 platform、style_id 和 variants 数组。每个 variant 对应一个尺码。

{
  "platform": "stockx",
  "style_id": "555088-711",
  "fetched_at": "2026-05-07T12:34:56.789000+00:00",
  "variants": [
    { "size": "9", "lowestAsk": 222.00, "highestBid": 198.00, "lastSale": null, "currency": "USD" },
    { "size": "10", "lowestAsk": 235.00, "highestBid": null, "lastSale": null, "currency": "USD" }
  ]
}

Root

platform
数据平台，固定为 "stockx"。
style_id
查询所用的 style ID。
fetched_at
从平台抓取原始数据时的 ISO 8601 时间戳（含时区），不是这次 API 请求的时间。
variants
变体数组，每个对象对应一个尺码。

variants[]

size
可读尺码，如 "9"、"10"。
lowestAsk
当前最低要价（美元）。
highestBid
当前最高出价（美元），无则为 null。
lastSale
最近成交价（美元）。StockX 固定为 null。
currency
货币代码，如 USD。
StockX 快速上架

接口行为

通过 style ID 和尺码在 StockX 创建单条挂单。

请求方式POST
路径/v2/stockx/simple-listing
认证X-API-Key
curl --request POST \
  --url 'https://api.sneakers.itbanque.com/v2/stockx/simple-listing' \
  --header 'X-API-Key: sr_live_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{"styleId":"DD1391-100","size":"10","amount":"150"}'
请求体参数

支持的参数

参数名类型是否必填说明
styleIdstring必填StockX style ID，如 DD1391-100。
sizestring必填尺码，如 "10" 或 "10.5"。
amountstring必填挂单价格（美元），自动四舍五入为整数。
costnumber可选采购成本，可选，用于利润追踪。
currencyCodestring可选货币代码，默认使用账户设置中的市场货币。
activeboolean可选是否立即激活挂单，默认 true。
expiresAtstring可选ISO 8601 过期时间，可选。
inventoryTypestring可选库存类型，可选，如 "standard"。

上架成功后返回 ok: true。

{ "ok": true }
GOAT 市场数据

接口行为

通过 style ID 查询 GOAT 上该商品所有尺码的最新市场数据。优先读取平台共享缓存（默认 TTL 为 1 小时），缓存未命中时向 GOAT 发起实时请求并回填缓存。返回格式与 StockX 市场接口相同。

请求方式GET
路径/v2/goat/market/search
认证X-API-Key
curl --request GET \
  --url 'https://api.sneakers.itbanque.com/v2/goat/market/search?style_id=U9060JBR' \
  --header 'X-API-Key: sr_live_your_api_key'
参数名类型是否必填说明
style_idstring必填款式编号，如 U9060JBR。用于在 GOAT 目录中搜索对应商品。
country_codestring可选国家或地区代码，默认使用账户设置里的 country_code（通常为 US）。

结构和 StockX 市场数据一样。platform 固定为 "goat"。highestBid 固定为 null，GOAT 不提供买家出价。

{
  "platform": "goat",
  "style_id": "U9060JBR",
  "fetched_at": "2026-05-07T12:34:56.789000+00:00",
  "variants": [
    { "size": "9", "lowestAsk": 197.00, "highestBid": null, "lastSale": 198.00, "currency": "USD" },
    { "size": "9.5", "lowestAsk": 294.00, "highestBid": null, "lastSale": null, "currency": "USD" }
  ]
}

Root

platform
数据平台，固定为 "goat"。
style_id
查询所用的 style ID。
fetched_at
从平台抓取原始数据时的 ISO 8601 时间戳（含时区），不是这次 API 请求的时间。
variants
变体数组，每个对象对应一个尺码。

variants[]

size
可读尺码，如 "9"、"9.5"。
lowestAsk
当前最低挂单价（美元），无库存则为 null。
highestBid
固定为 null。GOAT 不支持买家出价。
lastSale
最近成交价（美元），无成交记录则为 null。
currency
货币代码，如 USD。
错误处理

错误响应

401 未授权API 密钥缺失或无效
{ "detail": "Not authenticated" }
400 错误请求分页超出套餐上限
{ "detail": "limit exceeds your plan cap" }

401 是身份验证失败：检查密钥是否还有效，请求头名称是否正好是 X-API-Key。400 是参数错误：把 limit 或 offset 降到套餐允许的范围内。