Reviews: buyer reviews, moderation, seller replies
/docs/reviewscurrentМашинный перевод с английского· проверено 2026-10-31
Статус: current · проверенный: 2026-10-31, интеграционные испытания на временной базе данных и own стоять prod и dev ключи (§7)) · владелец: отзывы line Служить: GET /docs/reviews
1.Что вы можете сделать здесь
Беги. shop's Обзоры того, как работают крупные рынки: buyers пост rating, pros, cons, а comment, фото и видео; ничто не является public до тех пор, пока shop одобряет его; shop отвечает, удаляет, утверждает партиями и решает, кто может публиковать. С помощью key Вы управляете seller side: читать feed (включая pending отзывы), добавить отзыв от имени оффлайн клиент, умеренный, reply, Удалить и изменить обзор settings. Опубликовать как a buyer, голосование "helpful" и buyer's own государство buyer-действиями сессии и не доступны для key. Это не рекорды sets (/docs/record-sets): рекорд sets есть rows тот seller Типы в; отзывы приходят из buyers И пройти через умеренность.
2. Решать first (вилки)
| Если ты хочешь… | Возьми это path | Стоимость/улов/улов |
|---|---|---|
| Показать отзывы, но never пускать buyers Post (reviews "для наших own использовать") | PUT /reviews/settings {"post_mode":"nobody"}, Добавить отзывы с POST /reviews/seller | Витрина скрывает form; POST /reviews ответы REVIEWS_POSTING_CLOSED |
| Пусть только реальные buyers пост | PUT /reviews/settings {"post_mode":"buyers"} | а buyer нуждается в done (status 3) order содержащий это product; для shop Обзор - любой done order |
| Пусть любой подписанный посетитель пост | post_mode: "anyone" (тот default) | "Проверенная покупка"" badge Но это происходит только тогда, когда сервер находит order |
| Добавить оффлайн клиента's обзор | POST /reviews/seller с а prod key | source: "seller", немедленно approved, never Проверенная покупка; это live операция |
| approve Или отвергнуть сразу многих | PUT /reviews/moderate до 100 человек ids | атомная: один id другого shop → NOT_FOUND, Ничего не меняет |
| Показать отзывы об одном product в твоем own разметка | public GET /reviews?product_id= | тот feed последующий product's обзор scope (own / category / shop / off) |
| Список точно один product's Отзывы в бэк-офисе | GET /reviews?product_id=&exact_product=true с catalog:read | игнорирует scope (members Только: посетитель все еще получает объем feed); owner view Показать все status |
| Скачать обзор Webhook рассказал о | GET /reviews/{id} с catalog:read | owner view: любой status; Посетитель получает только approved Обзор видимого shop |
3. Объекты и где они находятся live
Обзор. id, company_id, product_id (0 — обзор этого shop), source (buyer | seller), author (buyer) или author_name (seller-добавленный), rating (1–5, 0 — none), body, pros, cons, files[] (id, url), seller_reply, replied_at, helpful_count, status (pending | approved | rejected), verified_purchase, created_at. order_id Наследие: это badge читать verified_purchase только.
Feed. GET /reviews Принимает ровно один source — product_id, category_id или company_id — и возвраты result.items[], total, current_page, summary, media_total. summary = rating_avg, rating_count, histogram ([0] = Одна звезда … [4] = пять) выше approved Отзывы о целом source; Фильтры не меняются это. total Счет с фильтрами. media_total считать files в approved обзоры по source (тот "buyers' Фото и видео" галерея - это pages из has_media=true).
| Параметр | ценности | Эффект |
|---|---|---|
sort | new (default), helpful, with_media, rating_desc, rating_asc | order |
rating | повторять 1-5, e.g. rating=4&rating=5 | Только эти звезды |
has_media | true | только отзывы с фотографиями или видео |
status | pending, approved, rejected | owner view только (catalog:read из этого shop); Все else always получать approved |
exact_product | true | это product Только, независимо от scope — для shop members (owner view) |
page.number, page.limit | default 1 / 20, limit до 100 | offset pages; new Отзывы могут измениться page — drop повторяется через id |
Настройки. GET /reviews/settings → {post_mode, scope_default}; PUT изменениях, fields посылать. scope_default То же самое value как shop's настройка витрины (own, category, shop, off, "" = own).
Государство покупателя (GET /reviews/me?product_id= или ?company_id=, buyer сессия): my_review в любой status, can_post, post_block_reason (login, closed, disabled, purchase_required, already_posted, no_target — не было ни одной или двух целей; voted_ids для review_ids Ты проходишь. key Получить анонимный ответ can_post: false, login.
Веб-хуки. review.submitted — а buyer Рецензия на модерацию (ids и rating только). review.created — Рецензия стала public (в виде одного или нескольких банок, с одной стороны, и с другой) approved Обзор отправляет Ничего. /docs/webhooks §6.
4. Рецепты
Каждая запись ниже нуждается в prod key с catalog:write; first читать GET /v1/account/token проверить scopes и contour.
4.1 Отзывы только от shop
PUT /reviews/settings{"post_mode":"nobody"}.POST /reviews/seller{"product_id":<PRODUCT_ID>,"author_name":"Anna","rating":5,"pros":"Soft","cons":"","body":"Great chair","file_ids":[]}.- проверять:
GET /reviews?product_id=<PRODUCT_ID>Перечислите обзор сstatus: "approved",verified_purchase: false;GET /reviews/settingsшоуpost_mode: "nobody".
4.2 Умеренная очередь
GET /reviews?company_id=<SHOP_ID>&status=pending&page.limit=50(owner view).- одобрять:
PUT /reviews/moderate{"ids":[<ID>,<ID>],"approve":true}→{"updated": 2}. Отклонить один:PUT /reviews/<ID>/moderate{"approve":false}. - проверять: перечитывать с
status=approved;summary.rating_countвыросший в approved рейтинги.
Всегда посылать approve. Без этого ответ будет APPROVE_REQUIRED (Он отклонялся молча).
4.3 Ответить, а затем удалить reply
PUT /reviews/<ID>/reply {"reply":"Thank you!"}; {"reply":""} удаляет его. проверять: перечитывать feed — seller_reply и replied_at есть set, затем empty.
4.4 Исключить
DELETE /reviews/<ID> → {"deleted_after": "<+30 days>"}. Обзор удаляется из feed немедленно. rating удаляется из product rating немедленно.
4.5 Ваша own компонент обзора
The public feed Достаточно для a level-3 компонента или ваш own разметка: читать GET /reviews на API Происхождение с помощью source, sort фильтры; показ summary.histogram; load следующий page с page.number + 1 ("Шоу more" или нет прокручивать); render files[].url (images И видео. Никогда не кэшировать /reviews/me с помощью page: Это пер buyer.
4.6 Что такое buyer (внешность, а не key)
А. buyer загружает каждый photo или video с POST /v1/storages/files груз metadata.review_target = {"product_id": N} (или {"company_id": N}), закладывает bytes Возвращаясь к возвращенному URL, звонки /done, затем POST /reviews с file_ids. The file принадлежит к shop (Только его квота. buyer кто начал Загрузка может закончиться, в buyer сессия: а key получать REVIEW_UPLOAD_SESSION_ONLY, а shop член получает NOT_FOUND. Звонить /done Опять на законченной загрузке удаётся и ничего не меняет. seller Рецензия принимает только shop's own медиа библиотека files. А. rejected Обзор может быть fixed: Опубликовать снова в том же target заменить его и возвращает его обратно pending; старый files может быть сохранен.
Правила медиа-покупателя.
| Правило | ценность |
|---|---|
| форматы | jpg, jpeg, png, webp; video mp4, mov, webm (проверенные расширением и first bytes из file) |
| size | image до 10 MB, video до 200 MB (проверенный after Загрузка; более крупная file это deleted, REVIEW_MEDIA_TOO_LARGE) |
| за обзор | до 10 files, до 2-х видео |
| загрузка в день | 20 за штуку buyer, 200 за штуку shop (REVIEW_UPLOAD_LIMIT) |
| прикрепить | в течение 24 часов после загрузки; неприкрепленная загрузка deleted after 24 часа |
| квота | тот shop's План хранения (STORAGE_LIMIT_REACHED) |
| video | Играть как загружено: нет транскодирования, нет проверки длины сервера |
Перед модерацией обзор hidden. Его files иметь длинный случайный URL, и anyone с этим URL Они могут открыть их. The files не показаны в медиа-библиотеке. files не показаны в public feed. Загрузить URL действителен для 15 минут. В течение этих 15 минут buyer может загружать file Опять же. shop Видит, что files внутри обзора.
5.Безмолвно ignored
| снабженный | Что происходит |
|---|---|
order_id в POST /reviews | ignored; Сервер принимает решение о подтвержденной покупке |
status=pending от посетителя или другого shop | замененный на approved (public прогноз) |
product_id Вместе с тем, company_id в GET /reviews | product_id победа |
а key на GET /reviews/me | Ответ: анонимный посетитель (login) |
helpful повторение голосования | считать один раз; helpful:false Без голосования ничего не меняется |
review_upload, review_state, review_target, uploader в metadata регулярной загрузки | rejected с BAD_METADATA: Только сервер их записывает. |
scope_default/post_mode опущенный в PUT /reviews/settings | это field хранится |
6. Пределы
| Поле/операция | Limit |
|---|---|
author_name | 1-255 символов |
body, reply | до 10000 символов |
pros, cons | до 2000 символов в каждом |
rating | optional, 1–5 |
file_ids | до 10 на рецензию |
| live buyer отзывы на каждый target | за один раз product и один на shop; а rejected Можно заменить |
| пакетная модерация | 1–100 ids (more — INVALID_ARGUMENT из validation) |
page.limit | 1–100, default 20 |
| окно удаления | 30 дней |
Коды: REVIEWS_POSTING_CLOSED, REVIEW_PURCHASE_REQUIRED, REVIEWS_DISABLED, REVIEW_ALREADY_EXISTS, EMPTY_REVIEW, APPROVE_REQUIRED, REVIEWS_FORBIDDEN (не current член shop, или settings с помощью editor), REVIEW_NOT_FOUND / PRODUCT_NOT_FOUND (Пропавший, другой shop's или hidden — Тот же ответ), PAT_SCOPE_MISSING, PAT_CONTOUR_MISMATCH (а draft key На любой странице: отзывы live, Нет никакого draft из них), PAT_METHOD_NOT_ALLOWED (POST /reviews, POST /reviews/{id}/helpful с а key).
| Конечная точка | Сфера охвата | Проект key |
|---|---|---|
GET /reviews, GET /reviews/{id} | catalog:read Открывается owner view; Без него — это public один | читать |
GET /reviews/settings | catalog:read | читать |
POST /reviews/seller, PUT /reviews/{id}/moderate, PUT /reviews/moderate, PUT /reviews/{id}/reply, DELETE /reviews/{id}, PUT /reviews/settings | catalog:write | PAT_CONTOUR_MISMATCH |
POST /reviews, POST /reviews/{id}/helpful | buyer только сеанс | — |
GET /reviews/me | public; а key Посмотреть Анонимный ответ | — |
Настройки нуждаются в owner или администратором; другой пишет, что ему нужно current член (owner, admin, editor).
7.Как это было проверено
2026-10-31, интеграционные испытания на временной основе PostgreSQL (-run TestReviews, -run TestReviewUpload):
- Другой shop получать
NOT_FOUNDумеренный, reply, удалять, seller обзор и пакет. - Каждый shop имеет свой own settings. Пользователь, который не является участником, получает
REVIEWS_FORBIDDEN. Ан editor получатьREVIEWS_FORBIDDENна settings. - Режимы
nobody,buyersиanyoneРабота, как описано.order_idне дает в badge. - А. rejected исправление, что гонки с одобрением или удалением не перезаписывают их.
- Две параллельные страницы создают только 1 shop Голоса засчитываются один раз.
- Фильтры, виды, pages,
media_totalиexact_productГосударство покупателя работает на посетителя, author и а new buyer. - 6 параллельных утверждений 1 product отдавать exact
rating_count. - В целом, одна партия не срабатывает, если один обзор deleted одновременно.
- Загрузка: только uploader Закончите их; limits - по 30 параллельным запросам; file старше 24 часов не Прилагается; 3 видео отказано.
Ключевая матрица: tools/mcpcheck/scenarios/reviews.json на own стоять (prod, только для чтения, draft и другие-shop ключи). Ранее проведенные измерения seller конечные точки с prod и dev ключи (2026-10-28) хранятся в отзывах line folder.