API 参考

简介

AliExpress Reviews API 以 JSON 返回 AliExpress 商品评价。它是一个基于 HTTPS 的 REST 接口；所有响应（包括错误）均为 JSON。

基础 URL

https://api.aliexpress-reviews.com

认证

x-api-key 请求头

格式

JSON, UTF-8

快速开始：创建免费密钥，然后在控制台的 API 测试工具中试用，或运行：

curl "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789?filter=5&pageSize=20" \
  -H "x-api-key: $REVIEWS_API_KEY"

身份验证

在控制台中创建 API key，并在每个请求的 x-api-key 请求头中发送。密钥以 rv_ 开头。

密钥仅在创建时显示一次：我们只存储其哈希值，而非密钥本身。如果丢失，请在控制台中轮换密钥；旧密钥将在 5 分钟内失效。

请将密钥保存在服务器端。任何持有密钥的人都可以消耗您的配额。

GET /v1/reviews/{productId}

返回商品的一页评价，以及其评分汇总。

路径参数

查询参数

未知参数返回 400。您的套餐不包含的参数将返回 403，即使其值为默认值。

请求示例

curl "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789?filter=5&pageSize=20" \
  -H "x-api-key: $REVIEWS_API_KEY"

const url = new URL('https://api.aliexpress-reviews.com/v1/reviews/1005006123456789');
url.search = new URLSearchParams({ filter: '5', pageSize: '20' }).toString();

const res = await fetch(url, { headers: { 'x-api-key': process.env.REVIEWS_API_KEY } });
if (!res.ok) throw new Error((await res.json()).error.message);
const { summary, data } = await res.json();

import os, requests

res = requests.get(
    "https://api.aliexpress-reviews.com/v1/reviews/1005006123456789",
    params={"filter": "5", "pageSize": 20},
    headers={"x-api-key": os.environ["REVIEWS_API_KEY"]},
)
res.raise_for_status()
body = res.json()

筛选条件

筛选条件与 AliExpress 商品页面上显示的相同，并由 AliExpress 执行。每次请求发送一个 filter；不能组合使用。

响应中的 summary.filterCounts 会告诉您每个筛选条件对应的评价数量，因此无需额外请求即可在界面中隐藏空的筛选项。

语言

使用 lang（Pro）时，content 和 additionalFeedback 由 AliExpress 翻译。originalContent 始终保留买家的原文。

响应

{
  "productId": "1005006123456789",
  "filter": "all",
  "page": 1,
  "pageSize": 20,
  "total": 452,
  "totalPages": 23,
  "summary": {
    "averageRating": 4.4,
    "totalReviews": 452,
    "ratingDistribution": { "5": 323, "4": 54, "3": 33, "2": 12, "1": 30 },
    "filterCounts": { "all": 452, "image": 32, "additional": 6, "local": 63 }
  },
  "data": [
    {
      "id": "60012345678901234",
      "author": "J***n",
      "country": "ES",
      "rating": 5,
      "content": "Very good quality, arrived in 10 days",
      "originalContent": "Muy buena calidad, llegó en 10 días",
      "additionalFeedback": null,
      "date": "2026-08-09",
      "sku": "Color:Black",
      "helpfulVotes": 3,
      "images": ["https://..."],
      "thumbnails": ["https://..."]
    }
  ]
}

分页字段

评价字段

在 Free 和 Pro 套餐中不返回 images 和 thumbnails。

分页

依次请求 page=1、2……直到 page 达到 totalPages。每页都计为一次请求并消耗配额，因此请使用您的套餐允许的最大 pageSize。

async function allReviews(productId, filter = 'all') {
  const reviews = [];
  for (let page = 1; ; page++) {
    const url = `https://api.aliexpress-reviews.com/v1/reviews/${productId}?filter=${filter}&page=${page}`;
    const res = await fetch(url, { headers: { 'x-api-key': process.env.REVIEWS_API_KEY } });
    const body = await res.json();
    reviews.push(...body.data);
    if (page >= body.totalPages) return reviews;
  }
}

速率限制

配额在 00:00 UTC 重置。每个计入配额的响应（200、404、429、502）都会携带：

被 400/401/403 拒绝的请求不计入配额。超出配额后，在重置前将返回 429。此外还有所有用户共享的每秒 50 次请求的全局限制。

缓存

每页（商品 + 参数）最多缓存 24 小时，因此新评价最多可能需要一天才会出现。缓存的响应同样计入配额。

错误

错误使用标准 HTTP 状态码和 JSON 响应体：

{ "error": { "message": "filter=image requires the MAX plan" } }

OpenAPI

完整规范位于 /openapi.json（OpenAPI 3.0）。可导入 Postman、Insomnia 或客户端代码生成器。