Переход с API v2 на v3

Тело ответа

У площадки переименованы четыре поля:

Было		Стало	Что это
name	→	slug	машинное имя площадки: yandex_travel, 2gis
display_name	→	name	название для показа человеку: 2ГИС
has_reply	→	supports_replies	площадка вообще поддерживает ответы организации
has_images	→	supports_images	отзывы на площадке могут содержать картинки

Первые два поменялись местами: теперь name – это всегда название для человека, а машинное имя всегда slug. По этому же правилу читаются source_name и source_slug в остальных методах.

Два прежних имени has_reply и has_images значили у площадки одно, а в фильтрах отзывов – другое. Теперь у площадки это supports_* («умеет вообще»), а у отзыва остаётся has_* («есть у этого отзыва»). can_publish_reply не менялся: он показывает, может ли Rewio опубликовать ответ на этой площадке.

Тело ответа

Поля объекта те же, что были у группы (id, name, is_active, scrape_status, last_scraped_at, created_at, links), плюс новые review_count и is_demo. Постраничность не менялась: по умолчанию 100 за раз.

Тело запроса

Было		Стало	Что это
group_ids	→	object_ids	какие объекты включить или выключить одним вызовом

Поведение не менялось: недоступные идентификаторы молча пропускаются, в ответе – объекты, которые удалось изменить.

Было

{
  "id": 20,
  "name": "Националь",
  "deleted": true
}

Стало

{
  "id": 20,
  "name": "Националь"
}

Поле deleted убрано: оно всегда было true. Если объект не удалился, придёт ошибка, а не false. То же самое в DELETE /v3/folders/{folder_id}.

Тело ответа

Было		Стало	Что это
detail	→	message	человекочитаемый итог операции
group_id	→	object_id	объект, из которого удалена ссылка

В v3 поле detail есть только в теле ошибки. Если ваш код отличал успех от ошибки по наличию detail – в v3 это работает без исключений.

Тело ответа

Было		Стало	Что это
source_name	→	source_slug	машинное имя площадки, определённой по URL

Значение то же (2gis, yandex_travel). В v3 тело запроса на добавление ссылок – только массив.

Параметры запроса

Было		Стало	Что это
group_id	→	object_id	чьи отзывы отдать
include_deleted	→	show_deleted	показывать и удалённые площадкой отзывы
separate_pos_neg	→	split_pros_cons	отдать «достоинства» и «недостатки» отдельными полями
sort_by=date	→	sort_by=review_date	сортировка по дате публикации отзыва

show_hidden и show_pinned не менялись – теперь все три фильтра выдачи начинаются одинаково. Значения sort_by=rating и sort_by=reply_date тоже прежние: переименовано только date, потому что рядом стояло reply_date и было не видно, какая дата имеется в виду.

Параметр include_raw в v3 не поддерживается.

Тело ответа

В отзыве переименованы два поля – они приходят при split_pros_cons=true:

Было		Стало	Что это
positive	→	pros	блок «достоинства»
negative	→	cons	блок «недостатки»

И блок collecting, который приходит, пока идёт первый сбор:

Было		Стало
links_total	→	link_count
collecting_total	→	links_collecting
failed_total	→	links_failed

Остальные поля отзыва не менялись: author, text, rating, review_date, images, videos – всё как было. Блок access и его hidden_total тоже прежние.

Параметры запроса

Было		Стало	Что это
group_id	→	object_id	что синхронизировать в первом запросе

Адресат хранится в курсоре: со второго запроса по-прежнему достаточно cursor. Курсоры, выданные в v2, продолжают работать в v3 – курсор указывает место в данных, а не в версии, поэтому обход не нужно начинать заново.

Параметры запроса

Было		Стало	Что это
group_id	→	object_id	по какому объекту считать

Тело ответа

Переименованы счётчики – так, чтобы одна и та же величина везде называлась одинаково:

Было		Стало	Что это
total_reviews	→	review_count	так же называется в разбивке by_source
avg_rating	→	average_rating	так же, как в вебхуках
total_with_reply	→	reviews_with_reply	рядом с reviews_with_images и reviews_with_text
unanswered_negative	→	unanswered_negative_count	число негативных отзывов без ответа
meta.group_ids	→	meta.object_ids	какие объекты вошли в расчёт

Правило: total остаётся только в постраничном конверте («сколько всего подходит под запрос»), любой другой счётчик – *_count, а «сколько из них с чем-то» – reviews_with_*. source_name не менялся и по-прежнему содержит название площадки для показа.

Тело ответа

Было		Стало	Что это
series[].timeseries	→	series[].points	точки конкретного ряда

Было:

{ "series": [ { "source_id": 3, "timeseries": [ ...точки... ] } ] }

Стало:

{ "series": [ { "source_id": 3, "points": [ ...точки... ] } ] }

Раньше «ряд» лежал внутри «рядов» и назывался тем же словом. Сами точки и их поля не менялись, кроме счётчиков из таблицы выше.

Тело ответа

Было		Стало	Что это
detail	→	message	человекочитаемый итог операции

hidden_count не менялся. То же самое в DELETE того же адреса – «вернуть отзывы из скрытых».

Параметры запроса

Те же изменения, что у GET /v3/reviews: include_deleted → show_deleted, sort_by=date → sort_by=review_date. То же – в GET /v3/objects/{object_id}/pinned-reviews.

Тело запроса и ответа

Было		Стало	Что это
group_ids	→	object_ids	полный состав папки, присылается целиком
groups	→	objects	состав в ответе, объектами {id, name}
ignored_group_ids	→	ignored_object_ids	что не попало в состав: чужое, удалённое, несуществующее

Правила не менялись: состав всегда заменяется целиком, глубина – две ступени, один объект может лежать в скольких угодно папках. То же самое в PATCH /v3/folders/{folder_id}.

Тело запроса

Было		Стало	Что это
group_ids	→	object_ids	присылать события только по этим объектам

Остальная настройка не менялась: target, event_types, bucket_window, filters.

Что придёт на ваш адрес

Подписка, созданная через v3, получает тело версии "3". Подписки, созданные через v1 и v2, получают версию "2" без изменений – чтобы перейти на "3", создайте подписку заново.

Было (schema_version: "2")		Стало (schema_version: "3")
groups	→	objects
group_id	→	object_id
object_name	→	name
summary.negative_count	→	summary.negative_rating_count
source	→	source_id + source_slug

Стало:

{
  "schema_version": "3",
  "event": "reviews.new",
  "objects": [
    {
      "object_id": 20,
      "name": "Националь",
      "review_count": 2,
      "reviews": [ ... ]
    }
  ],
  "summary": { "review_count": 2, "average_rating": 4.5, "negative_rating_count": 0 }
}

Из отзыва внутри события убраны поля title и language: они всегда приходили пустыми. Счётчики приведены к общему правилу: total_reviews → review_count, average_rating – как в аналитике.

Что переименовано

Было		Стало	Когда приходит
group_or_folder_required	→	object_or_folder_required	не указан ни объект, ни папка
group_and_folder_conflict	→	object_and_folder_conflict	указаны оба сразу
group_limit_reached	→	object_limit_reached	исчерпан лимит объектов

В кодах ошибок слово group заменено на object. Остальные коды не менялись.