API 文档

BASE URLhttps://redfox.hk

暂无可用的 API 平台

Walmart关键词搜索商品

最低 ¥0.2/次起即将上线

通过关键词搜索商品并拿到productId（其他接口的入参），支持cursor/page分页与门店级定位

单价随接口累计调用量阶梯调整

POSThttps://redfox.hk/story/api/walmart/search

API 密钥获取与配置

获取密钥

调用 API 前，请先在控制台生成 API 密钥并完成配置。在 HTTP 请求头中添加API Key 字段，密钥用于身份校验与额度计费。

获取步骤

前往控制台页面，进入 API 密钥管理模块。
若无已生成的密钥，点击生成新密钥，复制并妥善保存密钥。
在请求头中添加 REDFOX_API_KEY或X-API-KEY字段并填入密钥后即可调用。

API说明

Method：POST

Host：https://redfox.hk

Path：/story/api/walmart/search

请求头

名称	类型	必填	说明	示例
REDFOX_API_KEY	string	是	平台鉴权令牌，每次请求必填	ak_xxxxxx
Content-Type	string	是	请求体数据类型	application/json

请求参数

参数	类型	必填	说明	示例
query	string	是	搜索关键词（必填）例：airpods pro	airpods pro
country	string	否	站点国家码（默认US）可选：US（walmart.com）、CA（walmart.ca）；product id 分站点不可跨用	US
zipCode	string	否	邮编传后返回门店级价格与库存，不传则为国家目录价	90210
state	string	否	州（配合定位取门店价）
storeId	string	否	门店ID（配合定位取门店价）
minPrice	number	否	价格下限
maxPrice	number	否	价格上限	200
sortBy	string	否	排序方式
facet	string	否	分面过滤
page	integer	否	分页页码
cursor	string	否	分页cursor 从上一次响应的paginationToken获取，用于翻页

返回值与结构

统一包装一般为 `code`、`message`/`msg`、`data`（以实际服务为准）。

响应字段

字段	类型	说明	示例
code	integer	业务状态码，2000表示成功	2000
msg	string	状态描述	成功
data	object
count	integer	本次返回的商品数量，数值型	29
hasMore	boolean	是否还有更多结果，布尔型（区别于抖音的数值1/0）	true
items	array	商品列表
availability	string	库存状态，In stock=有货，Out of stock=缺货	In stock
brand	null	品牌，可能为null
catalogId	string	商品目录ID（同一catalogId下可有多个卖家/成色的变体）	3RZ5BTN0KR6U
currency	string	货币单位	USD
description	string	商品描述，可能为null	IMMERSIVE SOUND - Experience Adaptive Audio...
imageUrl	string	商品主图URL	https://i5.walmartimages.com/asr/9adda7b8-956f-409b-80dc-748212f101b4.jpeg
priceCurrent	integer	当前售价，数值型（浮点）	127
priceOriginal	null	原价/划线价，无折扣时为null
productId	string	商品ID，字符串型避免精度丢失	5689919121
ratingAvg	integer	平均评分（0-5），可能为null	4
ratingCount	integer	评分人数，可能为null	351
seller	string	卖家名称	Walmart
sellerId	string	卖家ID，字符串型	66656029CC6541CBADDFA17547A98DE0
title	string	商品标题	(Open Box) Apple AirPods Pro 2 In-Ear Headphones with USB-C Charging Case, White
url	string	商品详情页URL	https://www.walmart.com/ip/AirPods-Pro-2nd-generation-with-MagSafe-Case-USB-C/5689919121
paginationToken	string	翻页游标（sc.前缀Base64编码），下一页请求时回传	sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJ3YWxtYXJ0L3NlYXJjaCIsInAiOiJwYWdlIiwicyI6ImQifQ

请求示例

{
  "query": "airpods pro",
  "country": "US",
  "zipCode": "90210",
  "maxPrice": 200
}

响应示例

{
  "code": 2000,
  "msg": "成功",
  "data": {
    "count": 29,
    "hasMore": true,
    "items": [
      {
        "productId": "5689919121",
        "catalogId": "3RZ5BTN0KR6U",
        "title": "(Open Box) Apple AirPods Pro 2 In-Ear Headphones with USB-C Charging Case, White",
        "description": "IMMERSIVE SOUND - Experience Adaptive Audio...",
        "brand": null,
        "imageUrl": "https://i5.walmartimages.com/asr/9adda7b8-956f-409b-80dc-748212f101b4.jpeg",
        "url": "https://www.walmart.com/ip/AirPods-Pro-2nd-generation-with-MagSafe-Case-USB-C/5689919121",
        "availability": "In stock",
        "currency": "USD",
        "priceCurrent": 127,
        "priceOriginal": null,
        "ratingAvg": 4,
        "ratingCount": 351,
        "seller": "Walmart",
        "sellerId": "66656029CC6541CBADDFA17547A98DE0"
      },
      {
        "productId": "20631813110",
        "catalogId": "2P29Z6D05RUK",
        "title": "Restored Apple AirPods Pro with MagSafe Charging Case (1st Generation), In-Ear Earbuds, Headphones, White",
        "description": "Apple AirPods Pro with MagSafe Charging Case (1st Generation)...",
        "brand": null,
        "imageUrl": "https://i5.walmartimages.com/asr/f1e93547-368d-4642-ae40-54237d906611.jpeg",
        "url": "https://www.walmart.com/ip/Apple-AirPods-Pro-with-MagSafe-Charging-Case-1st-Generation/20631813110",
        "availability": "In stock",
        "currency": "USD",
        "priceCurrent": 94.99,
        "priceOriginal": null,
        "ratingAvg": 4.5,
        "ratingCount": 2,
        "seller": "Top renew LLC",
        "sellerId": "66306FC579CE45AC878AD8F6B8B3DBC2"
      }
    ],
    "paginationToken": "sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJ3YWxtYXJ0L3NlYXJjaCIsInAiOiJwYWdlIiwicyI6ImQifQ"
  }
}

常见状态码说明

调用接口时，响应体中的 code 字段对应以下状态码。完整列表请查看 API 状态码说明页。

状态码	说明	排查建议
`400`	请求参数错误	检查请求体、Query 参数是否与文档一致，必填项是否齐全。
`401`	鉴权失败	确认请求头已添加 REDFOX_API_KEY 或 X-API-KEY，且密钥有效、未禁用。
`403`	无权限访问	当前密钥或账号无权调用该接口，请检查密钥状态与接口权限。
`500`	系统内部错误	服务端异常，请稍后重试；持续出现请联系技术支持。
`503`	服务暂不可用	服务维护或短暂过载，请间隔一段时间后重试。
`1001`	缺少必要参数	对照「请求参数」表，补全必填字段。
`1002`	参数格式不正确	检查字段类型与格式（如 URL、日期、枚举值）是否符合说明。
`1003`	参数类型错误	确认 JSON 中数字、字符串、布尔等类型与文档定义一致。
`3103`	密钥不存在	密钥可能已删除或填写错误，请前往控制台核对并重新复制。
`3105`	API Key 已禁用	在控制台启用该密钥，或创建新密钥后替换请求头中的值。
`3201`	积分不足	账户余额不足以支付本次调用，请前往控制台充值后再试。
`3202`	积分账户不存在	账号积分账户异常，请登录控制台确认账户状态。
`4004`	操作过于频繁，请稍后再试	触发频率限制，降低请求频率或增加调用间隔后重试。

调用步骤

在请求头配置REDFOX_API_KEY或X-API-KEY
按 API 说明示例构造请求参数或请求体。
发起请求。
解析 JSON 响应中的 code、message 与 data 字段。

Request（示例代码，仅供参考）

bash

curl -X POST "https://redfox.hk/story/api/walmart/search" \
  -H "REDFOX_API_KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "airpods pro",
  "country": "US",
  "zipCode": "90210",
  "state": "",
  "storeId": "",
  "minPrice": "",
  "maxPrice": 200,
  "sortBy": "",
  "facet": "",
  "page": "",
  "cursor": ""
}'

Response（示例代码，仅供参考）

json

{
  "code": 2000,
  "msg": "成功",
  "data": {
    "count": 29,
    "hasMore": true,
    "items": [
      {
        "productId": "5689919121",
        "catalogId": "3RZ5BTN0KR6U",
        "title": "(Open Box) Apple AirPods Pro 2 In-Ear Headphones with USB-C Charging Case, White",
        "description": "IMMERSIVE SOUND - Experience Adaptive Audio...",
        "brand": null,
        "imageUrl": "https://i5.walmartimages.com/asr/9adda7b8-956f-409b-80dc-748212f101b4.jpeg",
        "url": "https://www.walmart.com/ip/AirPods-Pro-2nd-generation-with-MagSafe-Case-USB-C/5689919121",
        "availability": "In stock",
        "currency": "USD",
        "priceCurrent": 127,
        "priceOriginal": null,
        "ratingAvg": 4,
        "ratingCount": 351,
        "seller": "Walmart",
        "sellerId": "66656029CC6541CBADDFA17547A98DE0"
      },
      {
        "productId": "20631813110",
        "catalogId": "2P29Z6D05RUK",
        "title": "Restored Apple AirPods Pro with MagSafe Charging Case (1st Generation), In-Ear Earbuds, Headphones, White",
        "description": "Apple AirPods Pro with MagSafe Charging Case (1st Generation)...",
        "brand": null,
        "imageUrl": "https://i5.walmartimages.com/asr/f1e93547-368d-4642-ae40-54237d906611.jpeg",
        "url": "https://www.walmart.com/ip/Apple-AirPods-Pro-with-MagSafe-Charging-Case-1st-Generation/20631813110",
        "availability": "In stock",
        "currency": "USD",
        "priceCurrent": 94.99,
        "priceOriginal": null,
        "ratingAvg": 4.5,
        "ratingCount": 2,
        "seller": "Top renew LLC",
        "sellerId": "66306FC579CE45AC878AD8F6B8B3DBC2"
      }
    ],
    "paginationToken": "sc.eyJ2IjoyLCJjIjoiMiIsImUiOiJ3YWxtYXJ0L3NlYXJjaCIsInAiOiJwYWdlIiwicyI6ImQifQ"
  }
}