API отзывов Amazon: от ссылок на товары к списку проблем с подтверждением из источника

Если вы ищете в отзывах Amazon идеи для улучшения товара, первым шагом не должно быть деление всего контента моделью на позитив и негатив. Сначала нужно знать, в каком региональном маркетплейсе опубликован отзыв, к какому товару он относится, встречается ли он повторно в нескольких запросах и на какое именно предложение опирается каждый вывод о проблеме. Иначе один популярный отзыв, прочитанный десять раз, в отчёте может превратиться в десять покупателей с одной и той же проблемой.

Руководство рассчитано на разработчиков и руководителей продуктовых направлений, которым нужно встроить отзывы во внутренние исследовательские процессы. Мы начнём со ссылки на товар, данные которого разрешено обрабатывать, и выстроим связи между товарами, отзывами, журналами наблюдений и доказательствами классификации. Итогом станет проверяемый список проблем, а не прогноз продаж, проверка подлинности отзывов или общая удовлетворённость покупателей.

Отличайте каталоги товаров от исследования отзывов

Официальный Amazon Creators API даёт доступ к каталогу товаров, включая поиск товаров, данные о товаре, варианты и операции с узлами категорий, и рассчитан на сценарии покупок в Amazon Associates. Это не тот же продукт, что amazon.reviews в EveryInfra, и официальная документация по каталогу товаров не может служить подтверждением права на чтение отзывов через сторонние сервисы.

Перед интеграцией уточните конкретный маркетплейс, права на использование данных, цели обработки, сроки хранения и то, можно ли показывать исходный текст или обрабатывать его моделями. Раздел LICENSE AND ACCESS в условиях использования Amazon.com ограничивает общую лицензию и способы сбора данных; условия других маркетплейсов и отдельных программ нужно проверять отдельно. Владение брендом товара не даёт автоматически права произвольно повторно использовать любые отзывы.

Если имеющиеся права позволяют использовать только определённый экспортированный набор данных, можно сразу перейти к описанным ниже шагам идентификации, устранения дублей и классификации, не выполняя сетевых запросов. Фиксируйте рамки прав в самом процессе и исключайте из последующих конвейеров поля и цели, выходящие за эти рамки.

Проверьте текущие параметры отзывов, не заимствуя параметры других действий

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

По состоянию на 2026-09-04 reviews требует url, среди необязательных параметров указан domain, режим выполнения — sync, результаты возвращаются списком. В текущем каталоге не объявлены конкретные значения default_limit и max_limit; пустые значения можно фиксировать только как необъявленные, их нельзя трактовать как неограниченное число записей и тем более как гарантию получения всех исторических отзывов.

Также не добавляйте в запросы к Amazon поля sort, since или cursor только потому, что их поддерживают другие платформы. Необязательные параметры должны соответствовать текущему действию, а то, что интерфейс принимает параметр, и то, что фильтр реально работает, нужно проверять отдельно. Текущего каталога недостаточно для руководства по непрерывной пагинации с сортировкой по новизне; ниже показан запрос на небольшую выборку.

Сначала подтвердите региональный маркетплейс, затем — идентификатор товара

В url указывайте полную ссылку на товар, а в domain — домен маркетплейса, например amazon.com или amazon.co.jp, без https:// и пути к товару. Локальный разбор входных данных извлекает десятисимвольный ASIN, состоящий из заглавных латинских букв и цифр, из путей вида /dp/, /gp/product/ и /product-reviews/. Главные страницы магазинов и страницы поиска по ключевым словам нельзя использовать как подтверждённые входные данные товара.

Особое внимание уделите маркетплейсам за пределами США: в текущей реализации для отзывов по умолчанию используется amazon.com, а автоматическое определение регионального маркетплейса по произвольной входной ссылке не гарантируется. Для товаров японского маркетплейса явно передавайте amazon.co.jp в соответствии со ссылкой. Японский текст отзыва, поля country в отзывах и валюта на странице не заменяют домен в запросе.

• В списке товаров сохраняются исходный URL, подтверждённый маркетплейс, ASIN из запроса, внутренний номер товара и обоснование включения. Названия нужны только для чтения и не служат первичным ключом товара.
• В связях с товаром отдельно сохраняются product_asin и variant из ответа; без проверки они не должны перезаписывать ASIN из запроса, а при их отсутствии не нужно угадывать дочерние варианты.
• Разные трекинговые ссылки на один и тот же маркетплейс и ASIN можно объединить в одну цель до отправки запросов, сохранив соответствие исходным ссылкам. Запросы, в которых меняются маркетплейсы, цели или параметры, нельзя объединять только на основании похожих названий.

Маркетплейс, указанный в запросе, определяет источник данных для этого наблюдения, а не гражданство автора отзыва. Поле country может содержать регион в разных текстовых форматах, а значение variant также может быть неполным; группировать записи по регионам или характеристикам можно только после однозначной нормализации и проверки. Неподтверждённые записи относите к категории «не указано»; нельзя без оснований причислять их к маркетплейсу США или вариантам товара по умолчанию.

Полный минимальный запрос для одного товара

Ниже приведён шаблон запроса, а не реальный клиентский вызов в рамках этой проверки. Поместите полные ссылки на товары, данные которых вам разрешено обрабатывать, и соответствующие маркетплейсы в переменные окружения, а API-ключи храните строго в собственной среде выполнения. Передайте limit внутри params как общий параметр запрашиваемого количества записей в списке; значение 3 предназначено для проверки структуры на небольшом объёме и не гарантирует, что вернутся ровно три записи, что сервер обработает только три записи или что оплата будет рассчитана за три записи.

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_AMAZON_PRODUCT_URL:?set the authorized full product URL first}"
: "${EVERYINFRA_AMAZON_DOMAIN:?set the site domain matching the URL first}"
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 @-

Сначала проверьте HTTP-статус и тип ответа, затем считывайте результаты, идентификаторы запроса и доступные данные об оплате в соответствии с фактической обёрткой ответа. Тайм-аут означает, что клиент не получил полный результат, но не означает, что сервер не выполнил запрос; сохраните контекст запроса до проверки, чтобы не отправлять его повторно сразу. Пустой результат означает, что этот запрос не вернул пригодных отзывов, и на этом основании нельзя помечать товар как «никогда не имевший отзывов».

Храните сами отзывы отдельно от журналов наблюдений

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

Текущий словарь данных содержит поля review_id, title, text, rating, rating_scale, posted_at, helpful_count, is_verified_purchase, is_vine, variant, country, url, author_name, product_asin и platform. Он описывает, что может быть возвращено, но не гарантирует заполненность всех значений в каждой записи.

• Записи отзывов: сохраняйте область источника, стабильный review_id, доступные заголовок, текст, оценку, шкалу оценки и ссылки на источник. Идентификаторы храните как строки; отсутствующие значения отличайте от явных false и 0.
• Журналы наблюдений: сохраняйте номера задач, запрошенные товары, снимки параметров, observed_at и фактические связи с возвращёнными отзывами. Чтение старых отзывов в новом запросе считается новым наблюдением, а не новым отзывом.
• Записи анализа: сохраняйте принятые версии отзывов, версии правил классификации, темы и фрагменты-доказательства, а также статус проверки. При изменении правил классификации исходные отзывы переписывать не нужно.

rating и rating_scale обрабатываются вместе; полученные при текущем запросе агрегированная оценка товара, общее число оценок и число отзывов — это разные метрики. Записи с оценкой, но без текста можно учитывать в отдельной выборке оценок, однако нельзя придумывать мнения и включать их в тематический анализ текста. author_name содержит только отображаемое имя, которое нельзя использовать как уникальный идентификатор; для анализа проблем товара также не требуется объединять профили автора на разных сайтах.

is_verified_purchase отражает статус подтверждения покупки, но не гарантирует точность мнения или полную достоверность содержания; значение false следует отличать от отсутствующего в ответе поля. is_vine указывает на отзывы, связанные с программой Vine. Согласно официальной документации Amazon, приглашённые участники Vine могут бесплатно опробовать товар до публикации мнения. Поэтому этот статус можно использовать как поле стратификации выборки, но нельзя на его основании считать отзывы Vine поддельными, а отсутствие поля — доказательством того, что отзыв не относится к Vine.

При дедупликации сохраняйте связи и не удаляйте записи только из-за похожего текста

На прикладном уровне отзывы можно сначала идентифицировать в пределах одной области данных по ключу «платформа-источник + маркетплейс + review_id», а затем отдельно фиксировать, при запросе каких товаров они были обнаружены. Если одному ключу соответствуют противоречивые привязки к товарам или разные варианты содержимого, сначала сохраните конфликтующие записи для проверки и не перезаписывайте их без фиксации конфликта. Совпадающие идентификаторы или тексты на разных сайтах нельзя автоматически объединять без надёжно установленного соответствия.

Если review_id отсутствует, установить связь помогут подтверждённые постоянные ссылки на отзывы; если неопределённость сохраняется, остальные записи помещаются в очередь на дедупликацию. Сочетания текста, даты и оценки позволяют лишь приблизительно определить возможные совпадения и не доказывают, что два автора — один и тот же человек. Два отзыва с текстом «отлично работает» действительно могут быть разными, а переведённые тексты со схожим смыслом не могут служить уникальным ключом.

Когда тот же отзыв позже появляется снова, сравните фактически доступные текст, оценку, число отметок «Полезно» и привязки к товарам. Изменения сначала фиксируйте как расхождения между наблюдениями; причиной различий также могут быть язык, доступность полей и временные диапазоны. Если конкретный отзыв не был возвращён в текущем цикле, его можно пометить только как «не обнаружен в текущем цикле», не создавая события удаления.

Классификацию проблем нужно привязывать к фрагментам источника

Перед подключением моделей вручную определите границы категорий на небольшой выборке из данных, разрешённых к использованию. Начните с практически значимых тем, таких как совместимость, упаковка, инструкции и логистика, и сохраните категории «нет явной проблемы» и «недостаточно данных». Одному отзыву можно присвоить несколько тем; не делайте выводов о качестве «нераспакованных» товаров только ради выполнения квоты по тегам.

Передаваемые классификаторам данные следует ограничивать содержимым, необходимым для задачи. Отзывы — это материал для анализа, а не системные инструкции; встречающиеся в них фразы вроде «игнорируй правила» или «перейди по этому адресу» не должны заставлять модели вызывать инструменты или менять цели обработки. Выходные данные должны содержать как минимум идентификаторы отзывов, исходные текстовые поля, начальную и конечную позиции, темы, версии правил и статус «ожидает проверки».

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

// synthetic text; demonstrates evidence checks only, not a real product review.
const sample = {review_id: "synthetic-review", text: "the API cannot reach the legacy model，wrapper intact."};
console.log(validateAnnotation(sample, {
  review_id: sample.review_id, taxonomy_version: "issues-v1",
  topic: "compatibility", source_field: "text",
  start: 0, end: 9, quote: "the API cannot reach the legacy model"
}));

Этот валидатор доказывает только, что позиции цитат соответствуют входному тексту, а не правильность классификации по темам. Если модель цитирует «упаковка целая», но отмечает проблему с упаковкой, посимвольная проверка всё равно может пройти; такую ошибку должны выявлять семантическая или ручная проверка. start/end — это индексы в строках JavaScript. Если данные передаются в другой язык программирования, соглашение об индексах нужно указать явно; нельзя смешивать смещения в байтах и количество символов.

В реальном продакшене на внешних уровнях системы нужно также привязывать маркетплейсы, связи с товарами и версии отзывов, а также ограничивать число выходных значений для каждой записи и задавать допустимые типы полей. Оценка уверенности, которую сообщает сама модель, не равна откалиброванной точности. До запуска подготовьте выборку с ручной разметкой и отдельно учитывайте пропуски, ложноположительные результаты и выводы без подтверждающих данных, вместо того чтобы сводить все ошибки к одному привлекательному показателю общей точности.

OWASP относит инструкции, скрытые на веб-страницах, в документах и пользовательских отзывах, к рискам косвенной инъекции промптов и рекомендует проверять вызовы инструментов с учётом прав пользователя и текущих задач. Поэтому классификатор отзывов должен выдавать только ограниченный набор тегов-кандидатов; содержание отзыва не разрешает выполнять такие действия, как изменение товаров или отправка сообщений.

Указывайте знаменатель для каждой доли упоминаний проблем

В полностью синтетическом примере из 10 отобранных для анализа читаемых отзывов без дубликатов в 3 подтвердилась проблема совместимости, что позволяет сказать: «доля упоминаний проблем совместимости в этой выборке составляет 3/10». Это нельзя переписать как «30% покупателей столкнулись с проблемами совместимости». Если отзыв затрагивает две темы, сумма долей тем может превысить 100%; диаграммы состава с суммой 100% уместны только после определения взаимоисключающих категорий.

К каждому отчёту прилагайте набор маркетплейсов и товаров, время формирования выборки, фактические параметры запросов, число возвращённых записей, число записей после дедупликации, число отзывов с читаемым текстом, число записей со статусом «ожидает проверки» и версии правил. Поля posted_at отзыва и observed_at чтения храните раздельно: если сегодня прочитан прошлогодний отзыв, это не означает, что сегодня произошёл новый инцидент.

Для сравнения по неделям также нужно сохранять неизменными наборы товаров, порядок получения данных, языковую обработку и временные диапазоны либо объяснять их изменения. Если постоянно читать только один и тот же набор первых отзывов, увеличение частоты запуска задач не расширит независимую выборку. Если каталоги не обеспечивают полную пагинацию или не гарантируют охват временного окна, отчёты следует представлять как анализ наблюдаемой выборки, а не как мониторинг трендов по всему объёму данных.

В отчётах можно также использовать концепцию фиксации происхождения данных из W3C PROV, чтобы связать каждый вывод о проблеме с версиями отзывов и операциями классификации. Это позволит найти затронутые теги и сводки после исправления исходного текста. Сама фиксация связей не доказывает правильность классификации, поэтому семантическая проверка по-прежнему необходима.

Встройте списки проблем в рабочие процессы улучшения продукта

Вывод, который стоит передать продуктовой команде, должен включать подтверждённые сведения о затронутых характеристиках, характерные примеры, подтверждающие вывод, знаменатели показателей по выборке, альтернативные объяснения, которые ещё не исключены, и следующие шаги проверки. Например, прежде чем решать, добавлять ли примечания о совместимости или дорабатывать товар, воспроизведите проблемы с подключением на старых моделях. Сами отзывы не заменяют инженерные испытания, данные о заказах и записи послепродажного обслуживания.

Для первой интеграции можно выбрать всего один товар, к данным которого у вас есть разрешённый доступ, и выполнить на нём все этапы: проверить входные данные и ответ, провести дедупликацию, проверить подтверждающие фрагменты в источнике и выполнить ручную проверку. Расширение списка товаров даст полезную информацию только тогда, когда все эти шаги будут воспроизводимы. Затем проверьте параметры по страницам возможностей Amazon и обрабатывайте состояния запросов в соответствии с общей документацией. Не наращивайте объёмы заранее, чтобы потом не гадать, откуда взялся каждый отзыв.