API доставки отзывов

PUT /shopping/reviews принимает новые и изменённые отзывы о товарах, включая скрытие и удаление. Используйте его для обновлений между полными выгрузками по CSV-контракту. Названия полей и допустимые значения совпадают с форматом файла.

Сейчас API сохраняет отзывы. Shopping Assistant пока не использует их в ответах, а автоматический импорт CSV ещё не реализован. Успешная доставка не означает, что саммари по отзывам уже доступно покупателю.

Подключение и доступ

Отправляйте запросы из серверной системы, в которой хранятся отзывы. Перед подключением получите у специалиста Gravity Field идентификатор раздела (tenant_id) и согласуйте исходящие IP-адреса серверов.

В теле запроса передавайте идентификатор раздела в поле sec. Доступ проверяется по списку разрешённых IP-адресов и подсетей, если он настроен для раздела. Запрос с другого IP получает 403 IP_NOT_ALLOWED. Если список не настроен или пуст, ограничение по IP не применяется. Отдельный заголовок авторизации для этой ручки не предусмотрен.

PUT https://shopping-assistant-api.gravityfield.ai/shopping/reviews
Content-Type: application/json

Запрос

Пример доставки

Замените YOUR_TENANT_ID на идентификатор своего раздела, а sku — на точный SKU из товарного фида.

curl --request PUT \
  --url 'https://shopping-assistant-api.gravityfield.ai/shopping/reviews' \
  --header 'Content-Type: application/json' \
  --data '{
    "sec": "YOUR_TENANT_ID",
    "data": [
      {
        "reviewId": "rv-123",
        "sku": "sku-456",
        "rating": 5,
        "title": "Отличный крем",
        "text": "Быстро впитывается, хорошо увлажняет",
        "pros": "Текстура",
        "cons": "Сильный запах",
        "status": "published",
        "helpfulCount": 12,
        "locale": "ru-RU",
        "createdAt": "2026-08-20T09:00:00Z",
        "updatedAt": "2026-08-31T10:00:00Z"
      }
    ]
  }'

Поля отзыва

Передавайте числа как JSON-числа, без кавычек. У reviewId, sku и sec удаляются пробелы по краям. Необязательные текстовые поля, переданные пустой строкой или строкой из пробелов, сохраняются как null.

Необязательное поле, отсутствующее в отзыве, также сохраняется как null: прежнее значение не сохраняется. Поэтому при обновлении отправляйте полное состояние отзыва, а не только изменённые поля. Отзывы только с оценкой допустимы.

Неизвестные поля внутри отзыва отклоняются с 400. Используйте точные имена в camelCase: например, reviewId, а не review_id. Не добавляйте имя, email, телефон и другие персональные данные автора.

Обновление, скрытие и удаление

Отзыв определяется сочетанием раздела sec и reviewId. Для всех обновлений одного отзыва сохраняйте тот же reviewId и передавайте время изменения в updatedAt.

• Новый отзыв сохраняется.
• Обновление с updatedAt новее сохранённого заменяет состояние отзыва.
• Обновление с равным updatedAt тоже применяется. Для разных версий используйте разные даты изменения, чтобы порядок доставки не определял итоговое состояние.
• Обновление со старым updatedAt игнорируется и учитывается в stale.
• Повторная доставка того же состояния безопасна и может снова учитываться в applied.

Для скрытия отправьте полное состояние со статусом hidden, для удаления — со статусом deleted и новым updatedAt. Обязательные поля нужны и для этих статусов. Например, тело запроса на удаление:

{
  "sec": "YOUR_TENANT_ID",
  "data": [
    {
      "reviewId": "rv-123",
      "sku": "sku-456",
      "rating": 5,
      "status": "deleted",
      "createdAt": "2026-08-20T09:00:00Z",
      "updatedAt": "2026-09-01T10:00:00Z"
    }
  ]
}

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

Если хотя бы один элемент не проходит валидацию или reviewId повторяется внутри массива, весь запрос отклоняется без сохранения отзывов. В корректном запросе устаревшие элементы игнорируются, а остальные сохраняются.

Успешный ответ

API возвращает 200 OK:

{
  "received": 1,
  "applied": 1,
  "stale": 0
}

Ответ подтверждает сохранение данных, а не построение саммари.

Ошибки и повторная доставка

При 400, 403 или 404 исправьте причину перед повтором. После сетевого сбоя, 500 или 503 повторяйте тот же пакет с задержкой и постепенным увеличением интервала. Сохраняйте исходный updatedAt: время повтора не является временем изменения отзыва.

Для объёма больше 1000 отзывов разделите обновления на несколько запросов. Ограничение на один файл для полной CSV-выгрузки сохраняется.

Проверка интеграции

• sec содержит идентификатор нужного раздела.
• Исходящие IP серверов согласованы для раздела.
• Один запрос содержит от 1 до 1000 отзывов без повторяющихся reviewId.
• sku совпадает с товарным фидом.
• Обновления содержат полное состояние, а updatedAt отражает время изменения в исходной системе.
• Скрытие и удаление передаются явно через status.
• Обрабатываются applied, stale и ошибки; повтор сохраняет исходные данные и даты.