Синхронизация отзывов

Поток изменений: отзывы, которые появились или изменились у нас после точки, на которой вы остановились. Нужен там, где у вас своя база и её надо держать в актуальном состоянии.

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

curl -X GET "https://example.com/v3/reviews/sync?object_id=20"

{  "data": [    {      "id": 143046,      "link_id": 177,      "source_id": 1,      "author": "Сергей",      "text": "Замечательно. Приеду ещё. ",      "review_date": "2026-07-21T18:07:03",      "rating_original": "5",      "rating": 5,      "review_url": "https://yandex.ru/maps/org/1020542995/reviews?reviews[publicId]=u182gzp1r9rg4urew906ky9dd0",      "reply_text": "Уважаемый Гость,\nБлагодарим Вас за визит в гостиницу «Националь» и высокую оценку нашего обслуживания. Ждем Вас снова!\nС наилучшими пожеланиями,\t\nЕлена Позолотина\nДиректор по операционной деятельности.\n",      "reply_date": "2026-07-23T13:27:07",      "has_images": true,      "images": [        {          "template_url": "https://avatars.mds.yandex.net/get-altay/17743308/2a0000019f85dc34d7ee3b24b4b9ec82bdbd/{size}",          "preview": "https://avatars.mds.yandex.net/get-altay/17743308/2a0000019f85dc34d7ee3b24b4b9ec82bdbd/M",          "image": "https://avatars.mds.yandex.net/get-altay/17743308/2a0000019f85dc34d7ee3b24b4b9ec82bdbd/XXXL"        },        {          "template_url": "https://avatars.mds.yandex.net/get-altay/18473509/2a0000019f85dc42d3b7bbf4e10e375c612e/{size}",          "preview": "https://avatars.mds.yandex.net/get-altay/18473509/2a0000019f85dc42d3b7bbf4e10e375c612e/M",          "image": "https://avatars.mds.yandex.net/get-altay/18473509/2a0000019f85dc42d3b7bbf4e10e375c612e/XXXL"        },        {          "template_url": "https://avatars.mds.yandex.net/get-altay/20191917/2a0000019f85dc255b9c227cfbc55fc57724/{size}",          "preview": "https://avatars.mds.yandex.net/get-altay/20191917/2a0000019f85dc255b9c227cfbc55fc57724/M",          "image": "https://avatars.mds.yandex.net/get-altay/20191917/2a0000019f85dc255b9c227cfbc55fc57724/XXXL"        }      ],      "has_videos": false,      "videos": []    },    {      "id": 143051,      "link_id": 177,      "source_id": 1,      "author": "Марина",      "text": "Номер не соответствовал описанию.",      "review_date": "2026-07-19T09:14:00",      "rating_original": "2",      "rating": 2,      "review_url": "https://yandex.ru/maps/org/1020542995/reviews?reviews[publicId]=u182gzp1r9rg4urew906ky9dd0",      "has_images": false,      "images": [],      "has_videos": false,      "videos": [],      "is_deleted": true,      "deleted_at": "2026-08-23T04:12:07"    }  ],  "next_cursor": "eyJhIjoiMjAyNi0wOC0yM1QxNDowMzoxMSIsImQiOjE0MzA1MSwiaSI6MjAsImwiOjEwMCwibSI6ImFsbCIsInQiOiJnIiwidSI6MzAsInYiOjF9.k3Qw9x0nJ8Zr5wQfB2vLZA",  "has_next": true}

Как это работает

Первый запрос — с адресом объекта, дальше достаточно одного cursor:

GET /v3/reviews/sync?object_id=20&limit=200
  → 200 отзывов, next_cursor: "eyJ…", has_next: true

GET /v3/reviews/sync?cursor=eyJ…
  → следующие 200, next_cursor: "eyJ…", has_next: true
  …
  → has_next: false — вы догнали текущее состояние

Сохраните последний next_cursor у себя и вернитесь с ним завтра — придёт только то, что изменилось за сутки.

cursor = load_cursor()          # None при первом запуске
params = {"cursor": cursor} if cursor else {"object_id": 20, "limit": 200}

while True:
    page = get("/v3/reviews/sync", params=params).json()
    for review in page["data"]:
        upsert(review)          # склейка по review["id"]
    cursor = page["next_cursor"]
    save_cursor(cursor)         # сохраняем ПОСЛЕ каждой страницы
    if not page["has_next"]:
        break
    params = {"cursor": cursor}

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

Один отзыв может прийти дважды

Если отзыв изменится, пока вы читаете страницы, он придёт ещё раз — уже с новым содержимым и с тем же id: новой строки мы не заводим. Поэтому в режиме all кладите к себе UPSERT по id, а не INSERT — иначе дубли или ошибка уникальности. В режиме new достаточно INSERT: там ничего не приходит дважды.

Потерять отзыв поток не может: это и есть его единственная твёрдая гарантия.

Что считается изменением

Правка текста или оценки на площадке, появившийся или изменившийся ответ организации, изменившийся набор фотографий и видео, пропажа отзыва с площадки (is_deleted: true) и обратное восстановление. Пересбор сам по себе изменением не считается: если на площадке ничего не поменялось, отзыв в поток не попадёт.

Два режима

Режим запекается в курсор: курсор одного режима не подходит другому — у них разные оси. Если нужны оба потока сразу, держите два курсора, это нормально.

mode=new удобен, когда отзывы уходят в CRM или в оповещения: правки и пропажи вас не интересуют, апсерт не нужен, каждая строка приходит ровно один раз.

Первый обход — всегда с начала истории

Переключателя «начать с сегодняшнего дня» нет: первый запрос отдаёт самые давние записи, и обход идёт до конца. Синхронизация — это сперва полная копия, потом приращения.

Если полная копия вам не нужна и интересны только новые отзывы по мере появления, это не эта ручка, а вебхуки: они и присылают только новое, без архива.

Свежесть

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

Опрашивать чаще раза в минуту смысла нет — отзывы на площадках так быстро не появляются. Практичный режим для актуальной копии: раз в 5–15 минут.

Границы

• Синхронизация не следит за составом объекта. Убрали ссылку из объекта, выключили объект или перенесли его — отзывы по нему просто перестанут приходить, отдельного события об этом не будет. Такие строки чистите у себя по link_id. Если ссылку потом вернули, её старые отзывы заново не поедут: курсор идёт по времени изменения, а возврат ссылки ничего в отзывах не меняет. Начните для этого объекта обход с нуля, без сохранённого курсора.
• Скрытые и закреплённые отзывы приходят обычными строками, без флагов is_hidden и is_pinned: скрытие и закрепление — настройка витрины объекта, а не свойство отзыва, и в поток изменений они не попадают.
• Ограниченная выдача работает здесь ровно так же, как в ленте: не больше access.limit_per_link последних отзывов на каждую площадку объекта (на пробном доступе — 20), и в ответе появляется блок access. Пропажи отзывов, оставшихся за этой границей, в поток не попадают.

Ошибки курсора

Остальные коды общие для всего API и описаны на странице Ошибки.