Riferimento API

Introduzione

AliExpress Reviews API restituisce le recensioni dei prodotti AliExpress in JSON. È un unico endpoint REST su HTTPS; ogni risposta, errori compresi, è in JSON.

URL di base

https://api.aliexpress-reviews.com

Autenticazione

Header x-api-key

Formato

JSON, UTF-8

Per iniziare: crea una chiave gratuita, poi provala nell’API tester della dashboard o esegui:

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

Autenticazione

Crea una API key nella dashboard e inviala nell’header x-api-key di ogni richiesta. Le chiavi iniziano con rv_.

La chiave viene mostrata una sola volta, al momento della creazione: noi conserviamo un hash, non la chiave. Se la perdi, rigenerala dalla dashboard; la vecchia chiave smette di funzionare entro 5 minuti.

Tieni la chiave lato server. Chiunque la possieda può consumare la tua quota.

GET /v1/reviews/{productId}

Restituisce una pagina di recensioni di un prodotto, insieme a un riepilogo delle sue valutazioni.

Parametri del percorso

Parametri della query

I parametri sconosciuti restituiscono 400. Un parametro non incluso nel tuo piano restituisce 403, anche se il suo valore è quello predefinito.

Esempio di richiesta

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

Filtri

I filtri sono gli stessi che AliExpress mostra nella pagina del prodotto, ed è AliExpress ad applicarli. Invia un solo filter per richiesta; non possono essere combinati.

summary.filterCounts nella risposta indica quante recensioni restituirebbe ciascun filtro, così puoi nascondere i filtri vuoti nella tua interfaccia senza richieste aggiuntive.

Lingue

Con lang (Pro), content e additionalFeedback arrivano tradotti da AliExpress. originalContent conserva sempre le parole originali dell’acquirente.

Risposta

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

Campi della pagina

Campi della recensione

images e thumbnails sono omessi nei piani Free e Pro.

Paginazione

Richiedi page=1, 2, … finché page non raggiunge totalPages. Ogni pagina è una richiesta conteggiata nella tua quota, quindi usa il pageSize più grande consentito dal tuo piano.

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

Rate limit

Le quote si azzerano alle 00:00 UTC. Ogni risposta che conta nella quota (200, 404, 429, 502) include:

Le richieste rifiutate con 400/401/403 non vengono conteggiate. Oltre la quota ricevi 429 fino all’azzeramento. Esiste inoltre un limite globale di 50 richieste al secondo condiviso da tutti gli utenti.

Cache

Ogni pagina (prodotto + parametri) viene messa in cache per un massimo di 24 ore, quindi le nuove recensioni possono impiegare fino a un giorno per comparire. Le risposte dalla cache contano comunque nella tua quota.

Errori

Gli errori usano i codici di stato HTTP standard e un corpo JSON:

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

OpenAPI

La specifica completa è su /openapi.json (OpenAPI 3.0). Importala in Postman, Insomnia o in un generatore di client.