API de reseñas de Amazon: de la URL del producto al listado de problemas con evidencia textual

Si buscas pistas de mejora de producto en las reseñas de Amazon, el primer paso no consiste en hacer que el modelo clasifique todo en opiniones positivas y negativas. Primero debes saber a qué sitio nacional pertenece la reseña, qué producto está asociado, si aparece repetida en varias solicitudes y qué frase exacta respalda cada conclusión de problema. De lo contrario, leer diez veces la misma reseña popular podría interpretarse en los informes como diez compradores que plantearon el mismo problema.

Este artículo está dirigido a desarrolladores y responsables de producto que necesitan integrar reseñas en los flujos de investigación internos. Partimos de una URL de producto autorizada para establecer la relación entre el producto, las reseñas, los registros de observación y la evidencia de clasificación. El resultado final es un listado de problemas verificables, y no una predicción de ventas, una validación de la autenticidad de las reseñas ni la satisfacción total de los compradores.

Distingue el catálogo de productos de la investigación de reseñas

La Creators API oficial de Amazon proporciona acceso al catálogo de productos, e incluye operaciones de búsqueda de artículos, detalles, variantes y nodos de clasificación, orientada a las experiencias de compra de Amazon Associates. No es el mismo producto que amazon.reviews de EveryInfra en este documento; la documentación oficial del catálogo de productos no puede utilizarse como comprobante de autorización para la lectura de reseñas de terceros.

Antes de la integración, confirma el sitio específico, el permiso para obtener datos, el propósito de procesamiento, el período de retención y si se pueden mostrar los textos originales o procesarlos con un modelo. Las condiciones de uso de Amazon.com en LICENSE AND ACCESS establecen restricciones sobre la licencia general y los métodos de recopilación de datos; otros sitios y planes específicos deben verificarse por separado. Que un producto pertenezca a tu propia marca no otorga automáticamente el derecho de reutilización ilimitada de todo el contenido de las reseñas.

Si tu autorización actual solo permite utilizar un conjunto de datos exportado determinado, puedes comenzar desde los pasos de identidad, deduplicación y clasificación descritos más adelante sin necesidad de ejecutar lecturas de red. Mantén el alcance de los permisos dentro del flujo y evita incluir campos o propósitos que excedan dicho alcance en las fases posteriores del proceso.

Revisa el contrato de reseñas actual sin tomar prestados parámetros de otras acciones

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=amazon' \
  | jq -e '.capabilities[] | select(.action == "reviews") | {
      platform, action, required_params, optional_params, param_meanings,
      mode, returns_list, default_limit, max_limit, response_fields
    }'

Al verificar 2026-09-04, reviews requiere una URL, el parámetro opcional domain, el modo de ejecución sync y devuelve una lista como resultado. Dicho catálogo no declara los valores específicos de default_limit ni max_limit; un valor vacío solo puede registrarse como no declarado, sin interpretarse como ausencia de límite en la cantidad de elementos ni como garantía de obtener todo el historial de reseñas.

Tampoco agregues estos campos a las solicitudes de Amazon solo porque otras plataformas admitan sort, since o cursor. Los parámetros opcionales deben corresponderse con la acción actual, y es necesario validar por separado que la API acepte los parámetros y que los filtros surtan efecto. El catálogo actual no es suficiente para respaldar un tutorial sobre "paginación continua ordenada por fecha de publicación", por lo que a continuación solo se muestra una solicitud de muestra pequeña.

Confirma primero el sitio nacional y después la identidad del producto

Usa una URL completa de producto para url y el dominio del sitio para domain, por ejemplo amazon.com o amazon.co.jp, sin incluir https:// ni la ruta del producto. El análisis de la entrada local identifica el ASIN de diez letras mayúsculas o números a partir de rutas como /dp/, /gp/product/ o /product-reviews/. Las páginas principales de tiendas y los resultados de búsqueda de palabras clave no pueden utilizarse como entradas de productos confirmadas.

Presta especial atención a los sitios que no son de EE. UU.: en la implementación actual, el valor predeterminado del sitio de reseñas es amazon.com y no se garantiza la inferencia automática del sitio nacional a partir de cualquier enlace de entrada. Al preparar artículos para el sitio de Japón, pasa explícitamente amazon.co.jp para que coincida con el enlace. No utilices el texto en japonés, el parámetro country de las reseñas o la moneda mostrada en la página como sustitutos del dominio de solicitud.

• El listado de productos conserva la URL original, el sitio verificado, el ASIN solicitado, el número de artículo comercial y el motivo de inclusión. El título se utiliza únicamente para lectura y no actúa como clave principal del producto.
• La asociación de productos almacena por separado los campos product_asin y variant de la respuesta; estos no deben sobrescribir el ASIN solicitado sin verificación previa, ni se debe adivinar una subvariante si faltan datos.
• Varios enlaces de seguimiento para el mismo sitio y ASIN se pueden combinar en un único objetivo antes de realizar la solicitud, siempre que se conserve la correspondencia de los enlaces originales. Las solicitudes que cambien de sitio, objetivo o parámetros no deben fusionarse basándose únicamente en la similitud de los títulos.

El sitio de solicitud define el ámbito de origen de esta observación y no la nacionalidad del autor de la reseña. El campo country puede contener textos de región en distintos formatos y variant también podría estar incompleta; solo tras una normalización y verificación claras resulta adecuado realizar agrupaciones por región o especificación. Los registros que no se puedan confirmar se clasificarán como "no especificados" y no deben asignarse de forma silenciosa al sitio de EE. UU. ni a una especificación predeterminada.

Completa una solicitud mínima con un solo objetivo

A continuación se muestra una plantilla de solicitud y no una llamada real de clientes de esta ronda. Coloca la URL completa autorizada del producto y el sitio correspondiente en las variables de entorno, y mantén la clave de API únicamente en tu propio entorno de ejecución. limit se incluye en params como una solicitud general de cantidad de elementos; configurarlo en 3 sirve para comprobar una estructura pequeña, sin garantizar que se devuelvan exactamente tres elementos, que el servidor procese solo tres ni que se facture en función de tres.

: "${EVERYINFRA_API_KEY:?configura primero la API Key}"
: "${EVERYINFRA_AMAZON_PRODUCT_URL:?configura primero la URL completa autorizada del producto}"
: "${EVERYINFRA_AMAZON_DOMAIN:?configura primero el dominio del sitio que coincida con la URL}"
jq -cn --arg url "${EVERYINFRA_AMAZON_PRODUCT_URL}" \
  --arg domain "${EVERYINFRA_AMAZON_DOMAIN}" '{
    platform: "amazon",
    action: "reviews",
    params: {url: $url, domain: $domain, limit: 3}
  }' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

Verifica el estado HTTP y el tipo de respuesta antes de leer los resultados, el identificador de solicitud y la información de facturación disponible según la estructura real. Un tiempo de espera agotado indica que el cliente no obtuvo el resultado completo, pero no demuestra que el servidor no lo haya ejecutado; conserva el contexto de la solicitud antes de verificar para evitar reenvíos directos. Un resultado vacío indica que esta solicitud no proporcionó reseñas utilizables, por lo que no se debe etiquetar un producto como "sin reseñas previas" basándose en ello.

Separa las reseñas propiamente dichas de los registros de observación

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=amazon&action=reviews' \
  | jq '{fields, undocumented}'

El diccionario actual contiene review_id, title, text, rating, rating_scale, posted_at, helpful_count, is_verified_purchase, is_vine, variant, country, url, author_name, product_asin y platform. Describe qué datos es posible que se devuelvan, sin garantizar que cada registro contenga valores completos.

• Registro de reseñas: almacena el ámbito de origen, el review_id estable, el título, el texto, la calificación y el enlace de origen disponibles. El identificador se conserva como cadena de texto; los valores faltantes se separan de los valores false explícitos y de 0.
• Registro de observación: almacena el número de tarea, el producto solicitado, la instantánea de parámetros, observed_at y las asociaciones de reseñas devueltas realmente. Leer una reseña antigua en una solicitud representa una nueva observación y no una reseña nueva.
• Registro de análisis: almacena la versión de la reseña utilizada, la versión de las reglas de clasificación, el tema, los fragmentos de evidencia y el estado de revisión. Si se modifican las reglas de clasificación, no es necesario reescribir la reseña original.

rating y rating_scale se gestionan conjuntamente; la puntuación agregada a nivel de producto, el volumen total de calificaciones y el número de reseñas obtenidas en esta ocasión son métricas distintas. Los registros de calificación sin texto se pueden incluir en una muestra de puntuación independiente, pero no se deben generar opiniones de la nada para mezclarlas en el análisis de temas de texto. author_name es únicamente un nombre visible, inadecuado como identidad única y prescindible para fusionar perfiles multiplataforma del autor con fines de análisis de problemas de producto.

is_verified_purchase indica el estado de verificación de compra y no constituye una garantía de que el punto de vista sea correcto o su contenido completamente auténtico; es obligatorio distinguir entre false y la ausencia del campo en la respuesta. is_vine identifica las evaluaciones asociadas al programa Vine. Las explicaciones oficiales de Amazon señalan que los evaluadores invitados por Vine pueden probar productos de forma gratuita antes de publicar opiniones; por lo tanto, este estado se puede emplear como campo de segmentación de muestras, pero no se debe clasificar directamente una reseña de Vine como falsa ni interpretar un campo faltante como no perteneciente a Vine.

Conserva las asociaciones al deduplicar en lugar de eliminar directamente por similitud de texto

A nivel de aplicación, puedes identificar reseñas dentro del mismo ámbito mediante "plataforma de origen + sitio web + review_id" y registrar por separado en qué productos solicitados se ha observado dicha reseña. Si una misma clave apunta a atribuciones de producto o contenidos contradictorios, conserva primero los registros en conflicto para su verificación y evita sobrescribirlos de forma silenciosa. La aparición de un mismo ID o texto idéntico en distintos sitios tampoco debe fusionarse automáticamente si no existe una correspondencia fiable.

Cuando falte el review_id, puedes emplear el enlace permanente verificado de la reseña para ayudar en la asociación; si la incertidumbre persiste, la entrada pasará al área pendiente de deduplicación. La combinación de texto, fecha y calificación solo ofrece candidatos aproximados y no demuestra que dos autores sean la misma persona. Dos apariciones de "funciona muy bien" podrían ser realmente reseñas diferentes, y los textos sinónimos traducidos tampoco sirven como clave única.

Si la misma reseña aparece de nuevo más adelante, compara el texto, la calificación, los recuentos de utilidad y las asociaciones de productos disponibles de manera real. Los cambios deben registrarse primero como discrepancias de observación; las diferencias en el idioma, la disponibilidad de los campos y los intervalos temporales también pueden provocar variaciones. Si una reseña concreta no se devuelve en esta ronda, limítate a marcarla como "no observada en esta ronda" y evita generar eventos de eliminación.

La clasificación de problemas debe vincularse de nuevo a la ubicación en el texto original

Emplea un conjunto reducido de muestras autorizadas para que seres humanos determinen los límites de las categorías antes de conectar el modelo. Los temas pueden iniciarse a partir de problemas accionables como compatibilidad, embalaje, instrucciones y logística, al tiempo que se reservan las opciones de "sin problema claro" e "insuficiencia de evidencia". Se admiten múltiples temas para una misma reseña; evita reescribir conclusiones de calidad para un artículo "que aún no se ha desempacado" solo con el propósito de completar etiquetas.

Los datos enviados al clasificador deben reducirse al mínimo estrictamente necesario para la tarea. Las reseñas son material de análisis y no instrucciones del sistema; frases como "ignora las reglas" o "visita esta dirección" contenidas en ellas no deben inducir al modelo a invocar herramientas ni a alterar el objetivo de procesamiento. La salida debe vincular como mínimo el ID de la reseña, el campo de texto original, las posiciones de inicio y fin, el tema, la versión de las reglas y el estado pendiente de revisión.

function validateAnnotation(review, annotation) {
  const topics = new Set(["compatibility", "packaging", "instructions", "shipping"]);
  if (typeof review.review_id !== "string" || !review.review_id.trim()) {
    throw new Error("review id required");
  }
  if (annotation.review_id !== review.review_id
      || annotation.taxonomy_version !== "issues-v1"
      || !topics.has(annotation.topic)) {
    throw new Error("unknown review or classification rule");
  }
  const field = annotation.source_field;
  if (!["title", "text"].includes(field)) throw new Error("invalid source field");
  const source = review[field];
  const {start, end, quote} = annotation;
  if (typeof source !== "string" || typeof quote !== "string"
      || !quote.trim() || !Number.isInteger(start) || !Number.isInteger(end)
      || start < 0 || end <= start || end > source.length
      || source.slice(start, end) !== quote) {
    throw new Error("evidence does not match source");
  }
  return {
    review_id: review.review_id, topic: annotation.topic,
    source_field: field, start, end, quote,
    taxonomy_version: "issues-v1", review_status: "unreviewed"
  };
}

// texto sintético; solo demuestra comprobaciones de evidencia, no es una reseña real.
const sample = {review_id: "synthetic-review", text: "la API no puede conectar con el modelo antiguo，el envoltorio está intacto."};
console.log(validateAnnotation(sample, {
  review_id: sample.review_id, taxonomy_version: "issues-v1",
  topic: "compatibility", source_field: "text",
  start: 0, end: 9, quote: "la API no puede conectar con el modelo antiguo"
}));

Este validador solo comprueba que la posición de la cita coincida con el texto de entrada, pero no certifica la validez del juicio temático. Si el modelo cita "embalaje intacto" pero lo etiqueta como un problema de embalaje, la verificación de caracteres podría superarse aun así, por lo que resulta indispensable la intervención de controles semánticos o revisiones humanas. start y end utilizan índices de cadena de JavaScript; si transfieres los datos a otro lenguaje, especifica claramente la convención de índices y evita mezclar desplazamientos de bytes con cantidades de caracteres.

La producción real requiere además asociar en la capa externa el sitio web, las relaciones de producto y la versión de la reseña, restringiendo la cantidad y los tipos de campo de cada salida. El valor de confidence proporcionado por el modelo no constituye una tasa de acierto calibrada; antes del lanzamiento, selecciona muestras etiquetadas por personas para contabilizar por separado los falsos negativos, los falsos positivos y los casos sin respaldo de evidencia, en lugar de resumir todos los errores en una única métrica de precisión global.

OWASP clasifica las instrucciones ocultas en páginas web, documentos y reseñas de usuarios como un riesgo de inyección de indirect prompts, y recomienda verificar las llamadas a herramientas según los permisos del usuario y la tarea actual. Por consiguiente, el clasificador de reseñas debe generar únicamente etiquetas candidatas restringidas; acciones como modificar productos o enviar mensajes no obtienen autorización a partir del contenido de las reseñas.

Especifica el denominador al calcular la proporción de problemas

En un ejemplo puramente sintético, si de 10 reseñas deduplicadas, legibles e incorporadas al análisis, 3 están relacionadas con problemas de compatibilidad tras su verificación, se puede escribir "la tasa de menciones de problemas de compatibilidad en esta muestra es de 3/10". No se puede reescribir como "el 30% de los compradores experimentó problemas de compatibilidad". Cuando una misma reseña abarca dos temas, la suma de las proporciones de cada tema puede superar el 100%; solo al definir primero categorías mutuamente excluyentes resulta adecuado elaborar un gráfico de composición que sume hasta el 100%.

Adjunta a cada informe el conjunto de sitios y productos, el tiempo de muestreo, los parámetros reales de solicitud, la cantidad devuelta, la cantidad tras la deduplicación, la cantidad de textos legibles, la cantidad de elementos pendientes de revisión y la versión de las reglas. posted_at de la reseña y observed_at en el momento de la lectura deben mantenerse separados: leer hoy una reseña del año pasado no significa que hoy haya ocurrido una nueva incidencia.

Las comparaciones semanales también exigen mantener constantes o explicar los cambios en el conjunto de productos, el orden de obtención, el procesamiento de idiomas y los intervalos de tiempo. Si de forma continuada solo se leen las mismas reseñas situadas al principio, incrementar el número de ejecuciones de tareas no ampliará la muestra independiente. Si el catálogo no ofrece garantías de paginación completa o de ventana temporal, el informe debe definirse como un análisis de muestras observadas y no como un monitoreo de tendencias globales.

El informe también puede adoptar el concepto de registros de derivación de W3C PROV para vincular cada conclusión de problema con la versión de la reseña y la actividad de clasificación. De este modo, al corregir el texto original, es posible rastrear las etiquetas y resúmenes afectados; la relación de registro en sí misma no demuestra que la clasificación sea correcta, por lo que debe preservarse la verificación semántica.

Integra el listado de problemas en el flujo de mejora real

Una conclusión digna de ser entregada al equipo de producto debe incluir las especificaciones confirmadas afectadas, evidencia representativa, el denominador de la muestra, otras explicaciones aún no descartadas y la siguiente acción de verificación. Por ejemplo, reproduce primero el problema de conectividad de un modelo anterior antes de decidir si agregas una aclaración de compatibilidad o ajustas el producto; las reseñas por sí mismas no sustituyen a las pruebas de ingeniería, los pedidos ni los registros de servicio posventa.

La primera integración puede limitarse a un solo producto autorizado para completar la verificación de entradas, la revisión de respuestas, la deduplicación, la validación de evidencia textual y la revisión humana. Solo cuando estas fases sean reproducibles, la ampliación del listado de productos aportará información útil. A continuación, verifica los parámetros según la página de capacidades de Amazon y procesa los estados de solicitud mediante la documentación general; evita incrementar el volumen de datos para adivinar después el origen de cada reseña.