Переход с 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 не менялся: он про нас, а не про площадку.

Тело ответа

Поля объекта те же, что были у группы: id, name, is_active, scrape_status, last_scraped_at, created_at, links. Постраничность тоже не менялась — по 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	объект, из которого удалена ссылка

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

Тело ответа

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

Значение то же самое (2gis, yandex_travel) — прежнее имя обещало название, а отдавало слаг.

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

Было		Стало	Что это
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	столько же, сколько в разбивке по площадкам
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. Адрес объекта — {object_id}. Списки закреплённых отзывов меняются так же.

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

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

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

Тело запроса

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

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

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

Подписка, созданная через v3, получает тело версии "3". Подписки, созданные раньше, продолжают получать версию "2" без единого изменения — переключение происходит только тогда, когда вы сами создадите подписку заново.

Было (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	указаны оба сразу
not_found	→	review_not_found, api_key_not_found	теперь код всегда называет сущность
api_key_limit	→	api_key_limit_reached	исчерпан лимит ключей
pinned_limit_exceeded	→	pinned_limit_reached	исчерпан лимит закреплённых

Правило: <сущность>_not_found и <что>_limit_reached, без исключений — по имени кода видно, что произошло, даже если вы его раньше не встречали. Остальные коды не менялись.