快速入门

概览

Apinoa 是一个面向电商平台商品数据的 API。亚马逊、eBay、Shopify、沃尔玛和速卖通通过同一个密钥、以同一套规范化结构返回数据：平台只是路径中的一段，请求的其余部分完全相同。同一个密钥也可以使用图片翻译。

快速开始

1. 创建账号

在 apinoa.com 注册并验证邮箱地址。

2. 充值额度

没有套餐需要选择，注册也无需绑定银行卡。按调用从预付余额中扣费，单价见价格页。在 控制台 > 余额 查看剩余额度并充值。如想先行评估，可在控制台的免费额度卡片中申请 $1 免费额度。

3. 生成 API 密钥

前往 控制台 > API 密钥 创建新密钥。可以选择设置前缀，方便识别。

# API 密钥的格式如下：
myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

请妥善保管 API 密钥，它只在创建时显示一次。一个密钥即可调用所有平台。

4. 发送第一个请求

在 x-api-key 请求头中携带密钥：

curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: YOUR_API_KEY"

同样的请求也可以用 JSON 请求体代替查询字符串传参，两种方式完全等价：

curl -X POST https://gateway.apinoa.com/v1/walmart/search \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "wool socks", "priceMax": 30}'

const url = new URL("https://gateway.apinoa.com/v1/walmart/search");
url.searchParams.set("query", "wool socks");

const res = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" } });
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);

5. 理解响应

所有响应都使用同一个信封：success，然后是 data 或 error 之一。搜索会在 data 中返回 SearchResult：

{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 40, "total": 1000 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "996425081",
        "title": "Merino Wool Hiking Socks, 3 Pack",
        "price": { "currency": "USD", "amount": 18.97 },
        "rating": { "average": 4.6, "count": 1204 },
        "inStock": true
      }
    ]
  }
}

price.amount 使用带小数的主单位。字段缺失表示平台没有提供该信息，绝不会用默认值填充，所以没有 price 不代表价格为 0。

出错时，信封里会带上错误码和错误信息：

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "brands: Unrecognized key(s) in object: 'brands'"
  }
}

6. 换一个平台试试

只需修改路径中的平台。密钥、参数和响应结构都保持不变：

curl "https://gateway.apinoa.com/v1/ebay/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"

GET /v1/marketplaces 会列出所有平台、支持的操作、每个操作的费用，以及每个操作输入参数的 JSON Schema。

可用 API

API	接口	说明
平台	`search`、`browse`、`categories`、`image-search`、`product`、`reviews`	用一套结构获取亚马逊、eBay、Shopify、沃尔玛和速卖通的商品数据
图片翻译	翻译、OCR、支持的字体	在保留原始视觉风格的同时替换商品图片中的文字
速卖通	`search`、`product`、`categories`、`browse`、`image-search`	速卖通商品数据

下一步

平台 -- 各平台之间相同与不同的地方
响应结构 -- 你可能收到的全部字段
筛选 -- 所有平台通用的价格、品牌、评分、成色和排序
认证 -- API 密钥认证
版本管理 -- /v1、已弃用的无版本 URL 及其停用日期
错误码 -- 完整错误参考

本页内容