Reviews API

Отзывы 2GIS, рейтинги локаций и аналитика организации — для вашей CRM, ERP, BI или любого другого продукта.

API решает три задачи:

• читать отзывы, локации и аналитику организации;
• синхронизировать отзывы со своей базой, забирая только изменения;
• узнавать о событиях — новом отзыве, ответе компании, изменении рейтинга — через вебхук или ленту событий.

Адрес API: https://api.review.cerebralabs.kz/v1. Описание в формате OpenAPI: https://api.review.cerebralabs.kz/v1/openapi.json — его можно импортировать в Postman или использовать для генерации клиента.

Быстрый старт

1. Получите API-ключ. Его создаёт владелец организации в кабинете: раздел «Интеграции» → «Создать ключ». Ключ показывается один раз.
2. Передавайте ключ в заголовке Authorization каждого запроса:

curl -H "Authorization: Bearer rk_ВАШ_КЛЮЧ" \
  "https://api.review.cerebralabs.kz/v1/reviews?limit=1"

Ответ:

{
  "data": [
    {
      "id": "317202675",
      "location_id": "70000001012345678",
      "location_name": "Кофейня на Абая",
      "author_name": "Айгерим К.",
      "rating": 5,
      "text": "Очень вкусный кофе и приветливый бариста!",
      "created_at": "2026-11-14T14:07:35.479718Z",
      "edited_at": null,
      "changed_at": "2026-11-14T14:10:38.921527Z",
      "is_rated": true,
      "is_hidden": false,
      "likes_count": 0,
      "photo_urls": [],
      "answer": null,
      "removed_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiY3JlYXRlZF9kZXNjIiwidiI6IjIwMjYtMTEtMTRUMTQ6MDc6MzUuNDc5NzE4IiwiaSI6MTk2NTh9"
}

Дальше: как держать свою базу отзывов в актуальном состоянии и как получать события на свой сервер.

Ключи и права

Ключ принадлежит одной организации и даёт доступ только к её данным. Это строка вида rk_…; храните её как пароль и не встраивайте в код, который выполняется в браузере или мобильном приложении.

У ключа есть набор прав. Запрос без нужного права получает ответ 403 с кодом insufficient_scope.

Владелец может ограничить ключ отдельными локациями и задать срок действия. Локации, недоступные ключу, для него не существуют: запрос к ним отвечает 404.

Отозванный или просроченный ключ сразу перестаёт приниматься (401, код invalid_api_key). Вебхуки, которые система настроила этим ключом, при отзыве отключаются.

Общие правила

Время и идентификаторы

• Моменты времени — в UTC, формат ISO 8601: 2026-11-14T14:07:35.479718Z. В параметрах запроса можно указывать время со смещением (…+05:00); время без смещения считается UTC.
• Идентификаторы отзывов и локаций — строки. Идентификатор локации совпадает с номером карточки в 2GIS.
• Поле без значения приходит как null, а не пропадает из ответа.

Листание

Списки отдаются частями. В ответе есть has_more и указатель на продолжение: next_cursor у отзывов, next_after у событий. Передайте его в следующем запросе и повторяйте, пока has_more равно true. Размер части задаёт параметр limit.

Лимит запросов

Не больше 120 запросов в минуту на ключ. В каждом ответе есть заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (через сколько секунд счётчик обнулится). При превышении приходит ответ 429 с заголовком Retry-After — подождите указанное число секунд и повторите запрос.

Ошибки

Любая ошибка приходит в одном формате. Опирайтесь в коде на поле code: оно не меняется, а текст message может уточняться.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Ключу не разрешено: analytics:read",
    "request_id": "req_9584d029f63a754f"
  }
}

Номер запроса есть и в заголовке X-Request-Id каждого ответа, в том числе успешного.

Свежесть данных

• Новый отзыв появляется в API в течение примерно 5 минут после публикации в 2GIS.
• Правки и ответы компании на свежих отзывах замечаются так же быстро. На старых отзывах, а также пропажа отзыва из 2GIS — раз в сутки, ночью.
• Отзывы новой локации загружаются в течение нескольких минут после её подключения; пока загрузка идёт, у локации initial_load_done равно false.

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

Чтобы держать у себя копию отзывов, не нужно каждый раз выгружать всё заново. Запросите отзывы в порядке их изменения — sort=changed_asc — и сохраните последний next_cursor. В следующий раз запрос с этим курсором вернёт только то, что изменилось: новые отзывы, правки, ответы компании, пропажи.

import pathlib
import time

import requests

API = "https://api.review.cerebralabs.kz/v1"
HEADERS = {"Authorization": "Bearer rk_ВАШ_КЛЮЧ"}
CURSOR_FILE = pathlib.Path("reviews_cursor.txt")  # где хранить курсор между запусками


def sync(save):
    """Забирает всё, что изменилось с прошлого запуска. save(review) — создать или обновить отзыв по review["id"]."""
    cursor = CURSOR_FILE.read_text().strip() if CURSOR_FILE.exists() else None
    while True:
        params = {"sort": "changed_asc", "limit": 200}
        if cursor:
            params["cursor"] = cursor
        response = requests.get(f"{API}/reviews", headers=HEADERS, params=params, timeout=30)
        if response.status_code == 429:  # превышен лимит — ждём столько, сколько просит сервер
            time.sleep(int(response.headers["Retry-After"]))
            continue
        response.raise_for_status()
        page = response.json()

        for review in page["data"]:
            save(review)  # у пропавшего из 2GIS отзыва заполнено review["removed_at"]

        if page["next_cursor"]:
            cursor = page["next_cursor"]
            CURSOR_FILE.write_text(cursor)  # сохраняем после каждой страницы: сбой не заставит начинать заново
        if not page["has_more"]:
            break

• В этом режиме next_cursor возвращается всегда, даже когда изменений нет, — сохраняйте его после каждой части.
• Один и тот же отзыв может прийти повторно, если он изменился ещё раз. Создавайте или обновляйте запись по id.
• Отзывы, пропавшие из 2GIS, в этом режиме тоже приходят — с заполненным removed_at. Если отзыв вернётся, он придёт снова с removed_at: null.
• Первая выгрузка большой организации — это десятки запросов. Обрабатывайте ответ 429, как в примере.

Если вашей системе важны не сами отзывы, а факты — «появился отзыв», «компания ответила», — используйте события.

События

Сервис записывает каждое замеченное изменение как событие. Получать события можно двумя способами — формат одинаковый:

• вебхук — сервис сам отправляет событие на ваш сервер;
• лента GET /v1/events — вы периодически запрашиваете новые события, передавая в after значение next_after из прошлого ответа. Подходит, если ваш сервер не может принимать входящие запросы.

Формат

У события есть id (растёт в порядке появления), type, момент occurred_at, локация и содержимое data.

Новый отзыв — в data.review тот же объект, что отдаёт GET /v1/reviews:

{
  "id": 1042,
  "type": "review.created",
  "occurred_at": "2026-11-14T14:10:38.921527Z",
  "location_id": "70000001012345678",
  "location_name": "Кофейня на Абая",
  "data": {
    "review": {
      "id": "317202675",
      "location_id": "70000001012345678",
      "location_name": "Кофейня на Абая",
      "author_name": "Айгерим К.",
      "rating": 5,
      "text": "Очень вкусный кофе и приветливый бариста!",
      "created_at": "2026-11-14T14:07:35.479718Z",
      "edited_at": null,
      "changed_at": "2026-11-14T14:10:38.921527Z",
      "is_rated": true,
      "is_hidden": false,
      "likes_count": 0,
      "photo_urls": [],
      "answer": null,
      "removed_at": null
    }
  }
}

У событий review.updated и review.answered дополнительно есть changed — что изменилось, и previous — прежние значения этих полей:

{
  "id": 1057,
  "type": "review.answered",
  "occurred_at": "2026-11-14T15:05:40.310000Z",
  "location_id": "70000001012345678",
  "location_name": "Кофейня на Абая",
  "data": {
    "review": {
      "id": "317202675",
      "location_id": "70000001012345678",
      "location_name": "Кофейня на Абая",
      "author_name": "Айгерим К.",
      "rating": 5,
      "text": "Очень вкусный кофе и приветливый бариста!",
      "created_at": "2026-11-14T14:07:35.479718Z",
      "edited_at": null,
      "changed_at": "2026-11-14T15:05:40.310000Z",
      "is_rated": true,
      "is_hidden": false,
      "likes_count": 0,
      "photo_urls": [],
      "answer": {
        "text": "Спасибо за отзыв! Ждём вас снова.",
        "answered_at": "2026-11-14T15:02:11.120000Z",
        "first_answered_at": "2026-11-14T15:02:11.120000Z"
      },
      "removed_at": null
    },
    "changed": [
      "answer"
    ],
    "previous": {
      "answer": null
    }
  }
}

Изменение рейтинга карточки:

{
  "id": 1060,
  "type": "location.rating_changed",
  "occurred_at": "2026-11-14T15:10:02.500000Z",
  "location_id": "70000001012345678",
  "location_name": "Кофейня на Абая",
  "data": {
    "rating": 4.6,
    "previous_rating": 4.7,
    "rating_confirmed": true,
    "reviews_count": 321
  }
}

Локация показывает события только с момента её подключения к организации; события за время первичной загрузки отзывов не создаются.

Вебхуки

Вебхук — это адрес на вашем сервере, на который сервис отправляет события запросом POST с телом в формате JSON. Настроить его можно двумя способами:

• владелец организации — в кабинете, раздел «Интеграции» → «Добавить вебхук»;
• ваша система сама — запросом к API. Ключу нужно право webhooks:manage:

curl -X POST "https://api.review.cerebralabs.kz/v1/webhooks" \
  -H "Authorization: Bearer rk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://crm.example.com/hooks/reviews", "event_types": ["review.created", "review.answered"]}'

В ответе придёт secret — секрет для проверки подписи. Он показывается один раз; при необходимости его можно сменить методом rotate-secret.

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

Требования к получателю

• Адрес — только https, с действующим сертификатом, на сервере, доступном из интернета по IPv4.
• На сообщение нужно ответить кодом 2xx за 10 секунд. Отвечайте сразу, а долгую обработку выполняйте в фоне.
• Перенаправления не выполняются: ответ 3xx считается неудачей.

Повторы и порядок

• Если сообщение не доставлено, оно отправляется повторно: через 1 мин, 5 мин, 15 мин, 1 ч, 3 ч, 6 ч, 12 ч, 24 ч — всего до 9 попыток примерно за двое суток.
• Повтор несёт тот же заголовок webhook-id. Запоминайте принятые значения и не обрабатывайте сообщение дважды.
• Пока получатель отвечает, события приходят по порядку. После сбоев порядок может нарушаться — ориентируйтесь на id и occurred_at события.
• Адрес, на который ничего не удаётся доставить 3 дня подряд, отключается; ответ 410 отключает его сразу. События за время отключения не досылаются — заберите их из ленты GET /v1/events.

Проверка связи

Метод POST /v1/webhooks/{id}/test (или кнопка «Отправить проверочное сообщение» в кабинете) отправляет событие типа ping. Результат и ответ вашего сервера видны в журнале доставок: GET /v1/webhooks/{id}/deliveries.

Проверка подписи

Адрес вебхука могут узнать посторонние, поэтому каждое сообщение подписано. Проверяйте подпись, прежде чем доверять содержимому. Подпись соответствует открытой спецификации Standard Webhooks — для неё есть готовые библиотеки на многих языках.

Как проверить:

1. Соберите строку {webhook-id}.{webhook-timestamp}.{тело запроса}. Тело берите как есть, байт в байт, — не разобранный и заново собранный JSON.
2. Ключ — это часть секрета после whsec_, декодированная из base64.
3. Посчитайте HMAC-SHA256 от строки с этим ключом, закодируйте в base64 и сравните с подписью из заголовка.
4. Отклоняйте сообщения, у которых webhook-timestamp отличается от текущего времени больше чем на 5 минут.

Python

import base64
import hashlib
import hmac
import time


def verify_webhook(secret: str, headers, body: bytes, tolerance: int = 300) -> bool:
    """secret — whsec_…; headers — заголовки запроса (имена в нижнем регистре); body — тело запроса как есть."""
    message_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > tolerance:
        return False  # слишком старое сообщение: возможно, кто-то повторяет перехваченный запрос

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{message_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    # В заголовке может быть несколько подписей через пробел: "v1,<подпись> v1,<подпись>"
    received = [part.split(",", 1)[1] for part in headers["webhook-signature"].split() if part.startswith("v1,")]
    return any(hmac.compare_digest(expected, candidate) for candidate in received)

const crypto = require("crypto");

// body — тело запроса как есть (Buffer или строка), до JSON.parse; имена заголовков в нижнем регистре
function verifyWebhook(secret, headers, body, tolerance = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerance) return false; // слишком старое сообщение

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.`).update(body).digest("base64");

  // В заголовке может быть несколько подписей через пробел: "v1,<подпись> v1,<подпись>"
  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, signature] = part.split(",");
    if (version !== "v1" || !signature) return false;
    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

module.exports = { verifyWebhook };

<?php

// $body — тело запроса как есть: file_get_contents('php://input'); имена заголовков в нижнем регистре
function verify_webhook(string $secret, array $headers, string $body, int $tolerance = 300): bool
{
    $id = $headers['webhook-id'];
    $timestamp = $headers['webhook-timestamp'];
    if (abs(time() - (int) $timestamp) > $tolerance) {
        return false; // слишком старое сообщение
    }

    $key = base64_decode(substr($secret, strlen('whsec_')));
    $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));

    // В заголовке может быть несколько подписей через пробел: "v1,<подпись> v1,<подпись>"
    foreach (explode(' ', $headers['webhook-signature']) as $part) {
        [$version, $signature] = array_pad(explode(',', $part, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $signature)) {
            return true;
        }
    }
    return false;
}

from flask import Flask, request

from verify import verify_webhook  # функция из примера выше

app = Flask(__name__)
SECRET = "whsec_ВАШ_СЕКРЕТ"
seen = set()  # в настоящей системе — таблица в базе


@app.post("/hooks/reviews")
def reviews_hook():
    body = request.get_data()  # именно сырое тело: подпись считается по нему
    headers = {name.lower(): value for name, value in request.headers.items()}
    if not verify_webhook(SECRET, headers, body):
        return "", 401

    if headers["webhook-id"] in seen:  # повтор уже принятого сообщения
        return "", 204
    seen.add(headers["webhook-id"])

    event = request.get_json()
    if event["type"] == "review.created":
        review = event["data"]["review"]
        print(f'Новый отзыв {review["rating"]}★ в «{event["location_name"]}»: {review["text"]}')
    # Незнакомые типы событий просто пропускайте: со временем появятся новые

    return "", 204  # отвечайте сразу, долгую обработку выносите в фон

С готовой библиотекой проверка занимает одну строку — например, Webhook(secret).verify(body, headers) в пакете standardwebhooks для Python.

Справочник методов

Пути указаны относительно адреса https://api.review.cerebralabs.kz. Этот же справочник в машинном виде — описание OpenAPI.

Организация

Локации

Отзывы

События

Аналитика

Вебхуки

Объекты

Delivery

DeliveryList

ErrorBody

ErrorResponse

Event

EventList

Location

LocationSummary

Organization

PeriodMetrics

RatingHistoryPoint

RatingWindow

Review

ReviewAnswer

ReviewList

Summary

TimeseriesPoint

Webhook

WebhookCreated

WebhookInput

WebhookPatch

WebhookSecret

Версии и изменения

Версия API указана в пути: /v1. В пределах версии мы можем добавлять методы, необязательные параметры, поля в ответах и типы событий. Удалять и переименовывать поля, менять их смысл и тип — только в новой версии; прежняя при этом продолжит работать, а о сроках её отключения мы предупредим заранее.