Referência da API

Introdução

A AliExpress Reviews API retorna avaliações de produtos do AliExpress em JSON. É um único endpoint REST sobre HTTPS; toda resposta, inclusive os erros, é JSON.

URL base

https://api.aliexpress-reviews.com

Autenticação

Header x-api-key

Formato

JSON, UTF-8

Início rápido: crie uma chave grátis e teste no testador de API do painel ou execute:

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

Autenticação

Crie uma chave de API no painel e envie-a no header x-api-key de cada requisição. As chaves começam com rv_.

A chave é exibida apenas uma vez, quando você a cria: armazenamos um hash, não a chave. Se você a perder, gere uma nova pelo painel; a chave antiga deixa de funcionar em até 5 minutos.

Mantenha a chave no servidor. Qualquer pessoa com ela pode consumir sua cota.

GET /v1/reviews/{productId}

Retorna uma página de avaliações de um produto, junto com o resumo das notas.

Parâmetros de caminho

Parâmetros de consulta

Parâmetros desconhecidos retornam 400. Um parâmetro que seu plano não inclui retorna 403, mesmo que o valor seja o padrão.

Exemplo de requisição

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()

Filtros

Os filtros são os mesmos que o AliExpress mostra na página do produto, e é o AliExpress que os aplica. Envie um filter por requisição; eles não podem ser combinados.

O summary.filterCounts da resposta informa quantas avaliações cada filtro retornaria, para você ocultar filtros vazios na sua interface sem requisições extras.

Idiomas

Com lang (Pro), content e additionalFeedback vêm traduzidos pelo AliExpress. originalContent sempre mantém as palavras do próprio comprador.

Resposta

{
  "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://..."]
    }
  ]
}

Campos da página

Campos da avaliação

images e thumbnails são omitidos nos planos Free e Pro.

Paginação

Solicite page=1, 2, … até que page chegue a totalPages. Cada página é uma requisição na sua cota, então use o maior pageSize que seu plano permitir.

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;
  }
}

Limites de requisições

As cotas são renovadas às 00:00 UTC. Toda resposta que conta na cota (200, 404, 429, 502) traz:

Requisições rejeitadas com 400/401/403 não contam. Ao exceder a cota, você recebe 429 até a renovação. Há também um limite global de 50 requisições por segundo compartilhado por todos os usuários.

Cache

Cada página (produto + parâmetros) fica em cache por até 24 horas, então novas avaliações podem levar até um dia para aparecer. Respostas em cache também contam na sua cota.

Erros

Os erros usam códigos de status HTTP padrão e um corpo JSON:

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

OpenAPI

A especificação completa está em /openapi.json (OpenAPI 3.0). Importe-a no Postman, no Insomnia ou em um gerador de clientes.