Referencia de la API

Introducción

AliExpress Reviews API devuelve reseñas de productos de AliExpress en JSON. Es un único endpoint REST sobre HTTPS; todas las respuestas, errores incluidos, son JSON.

URL base

https://api.aliexpress-reviews.com

Autenticación

Cabecera x-api-key

Formato

JSON, UTF-8

Inicio rápido: crea una clave gratuita y pruébala en el probador de API del panel o ejecuta:

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

Autenticación

Crea una API key en el panel y envíala en la cabecera x-api-key de cada petición. Las claves empiezan por rv_.

La clave solo se muestra una vez, al crearla: guardamos un hash, no la clave. Si la pierdes, rótala desde el panel; la clave anterior deja de funcionar en un plazo de 5 minutos.

Mantén la clave en el servidor. Cualquiera que la tenga puede gastar tu cuota.

GET /v1/reviews/{productId}

Devuelve una página de reseñas de un producto, junto con un resumen de sus valoraciones.

Parámetros de ruta

Parámetros de consulta

Los parámetros desconocidos devuelven 400. Un parámetro que tu plan no incluye devuelve 403, incluso si su valor es el predeterminado.

Ejemplo de petición

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

Los filtros son los mismos que AliExpress muestra en la página del producto, y es AliExpress quien los aplica. Envía un solo filter por petición; no se pueden combinar.

El campo summary.filterCounts de la respuesta te indica cuántas reseñas devolvería cada filtro, para que puedas ocultar los filtros vacíos en tu interfaz sin peticiones adicionales.

Idiomas

Con lang (Pro), content y additionalFeedback llegan traducidos por AliExpress. originalContent conserva siempre las palabras originales del comprador.

Respuesta

{
  "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 de la página

Campos de la reseña

images y thumbnails se omiten en Free y Pro.

Paginación

Solicita page=1, 2, … hasta que page alcance totalPages. Cada página es una petición contra tu cuota, así que usa el pageSize más grande que permita tu plan.

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

Límites de uso

Las cuotas se restablecen a las 00:00 UTC. Toda respuesta que cuenta para la cuota (200, 404, 429, 502) incluye:

Las peticiones rechazadas con 400/401/403 no cuentan. Si superas la cuota recibes 429 hasta el restablecimiento. También hay un límite global de 50 peticiones por segundo compartido por todos los usuarios.

Caché

Cada página (producto + parámetros) se guarda en caché hasta 24 horas, así que las reseñas nuevas pueden tardar hasta un día en aparecer. Las respuestas en caché también cuentan para tu cuota.

Errores

Los errores usan códigos de estado HTTP estándar y un cuerpo JSON:

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

OpenAPI

La especificación completa está en /openapi.json (OpenAPI 3.0). Impórtala en Postman, Insomnia o un generador de clientes.