rewio-ru Links API

openapi: 3.2.0
info:
  title: Review Aggregator Links API
  description: 'Единый REST API для отзывов: сервис собирает отзывы с площадок (Яндекс Карты, 2ГИС, Google, Островок, ДокДок и др.), приводит их к общей модели и отдаёт с фильтрами и аналитикой.


    📚 **Гайды, quickstart и полный справочник – на портале разработчика: https://docs.rewio.ru**


    #### Как начать

    1. Создайте **объект** – единицу бизнеса, отзывы по которой собираем.

    2. Добавьте в него **ссылки** на страницы объекта на нужных площадках.

    3. Запрашивайте **отзывы** и **аналитику** – данные обновляются дважды в сутки.


    #### Что вы получаете по каждому отзыву

    - **Текст**, **автор**, **оценка** – приведена к единой шкале 1–5 независимо от площадки

    - **Ответ организации** – текст и дата

    - **Изображения и видео** – превью и полноразмерные ссылки


    #### Работа с отзывами

    На тарифе «Полный»:

    - **Ответы** – публикация, замена и удаление ответа от лица организации (на пробном доступе – 3 на площадку)

    - **Жалобы** – подача жалобы на отзыв через форму площадки и её итог (на пробном доступе – 3 на площадку)

    - **Дополнительный сбор** – новые отзывы по объекту вне расписания, раз в сутки (на пробном доступе – 5 сборов)


    #### Соглашения

    - **Базовый URL:** `https://api.rewio.ru`. Актуальная версия – `/v3`.

    - **Авторизация:** заголовок `X-API-Key: ` в каждом запросе. Области ключа: `read_only` / `full`.

    - **Формат:** JSON на вход и выход.

    - **Даты:** UTC, ISO 8601 без таймзоны (`2026-02-25T09:28:07`). Время площадки (`review_date`, `reply_date`) приводится к UTC везде, где это возможно; в противном случае – как на площадке.

    - **Оценки:** нормализованы к единой шкале 1–5 независимо от площадки; исходное значение площадки сохраняется отдельно (`rating_original`).

    - **Списки:** ключ элементов всегда `data`. Постраничные ответы – `{data, total, limit, offset, has_next}` (параметры `limit` 1–1000 и `offset`); полные списки – только `{data}`.

    - **Ошибки:** единый формат `{"detail": "...", "code": "..."}` с машиночитаемым `code`. Отдельно стоит `402`: доступ приостановлен (закончился пробный период или оплата) либо площадка не входит в тариф – повтор запроса не поможет.

    - **Ограничение частоты:** при слишком частых запросах – `429`; повторите с задержкой.


    #### Проба

    В блоке авторизации уже подставлен тестовый ключ (только чтение) – можно сразу выполнить любой GET-запрос.


    **Тестовый ключ (только чтение):** `hrev_FaDGMKJEDDeCR5BCBgEg0aEjMogI7O7hOzE53YY4T1M`

    **Тестовый объект:** Отель Националь, **object_id = 20**


    Бесплатный тестовый доступ на создание 30 объектов.

    **Подключение и доступ:** 📧 info@rewio.ru · ✈️ @const_rewio'
  version: 3.0.0
servers:
- url: https://api.rewio.ru
  description: Production
tags:
- name: Links
  description: Ссылки внутри объекта – страницы объекта на площадках, по одной на площадку. Добавление, изменение и удаление ссылок, статус сбора отзывов.
paths:
  /v3/objects/{object_id}/links:
    post:
      tags:
      - Links
      summary: Добавить ссылки
      description: 'Добавить ссылки в объект – до 200 за раз.


        Площадка определяется по домену URL. Ответ содержит итог по каждой ссылке

        отдельно: успех с `link_id` или `error` – часть ссылок может не добавиться,

        остальные при этом добавляются. Сбор по новым ссылкам стартует сразу.'
      operationId: add_links_v3_v3_objects__object_id__links_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: object_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор объекта
          title: Object Id
        description: Идентификатор объекта
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/LinkInputV3'
              title: Links
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLinksResponseV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Links
      summary: Список ссылок
      description: Все ссылки объекта. Метод отдаёт их целиком – страниц здесь нет.
      operationId: list_links_v3_v3_objects__object_id__links_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: object_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор объекта
          title: Object Id
        description: Идентификатор объекта
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnAll_LinkV3_'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/objects/{object_id}/links/{link_id}:
    put:
      tags:
      - Links
      summary: Обновить ссылку
      description: 'Обновить ссылку объекта: своё название (`link_name`) и/или участие в

        сборе (`is_active`).'
      operationId: update_link_v3_v3_objects__object_id__links__link_id__put
      security:
      - APIKeyHeader: []
      parameters:
      - name: object_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор объекта
          title: Object Id
        description: Идентификатор объекта
      - name: link_id
        in: path
        required: true
        schema:
          type: integer
          description: Encoded link ID
          title: Link Id
        description: Encoded link ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkUpdateV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Links
      summary: Удалить ссылку
      description: Убрать ссылку из объекта. Собранные по ней отзывы перестают отдаваться.
      operationId: remove_link_v3_v3_objects__object_id__links__link_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: object_id
        in: path
        required: true
        schema:
          type: integer
          description: Идентификатор объекта
          title: Object Id
        description: Идентификатор объекта
      - name: link_id
        in: path
        required: true
        schema:
          type: integer
          description: Encoded link ID
          title: Link Id
        description: Encoded link ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkRemoveResponseV3'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ReturnAll_LinkV3_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/LinkV3'
          type: array
          title: Data
          description: Все элементы (пагинации нет).
      type: object
      required:
      - data
      title: ReturnAll[LinkV3]
    ScrapeStatus:
      type: string
      enum:
      - pending
      - in_progress
      - success
      - failed
      title: ScrapeStatus
      description: "Статус последнего сбора отзывов по ссылке.\n\n    \n    "
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
        code:
          type: string
          title: Code
      type: object
      required:
      - detail
      - code
      title: ErrorResponse
      description: Standard error response returned by all exception handlers.
    LinkUpdateV3:
      properties:
        link_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Link Name
          description: Новое своё название ссылки внутри объекта. Не передано – не меняется.
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: Собирать ли отзывы по этой ссылке. Не передано – не меняется.
      type: object
      title: LinkUpdateV3
      description: Изменение ссылки внутри объекта. Передавайте только изменяемые поля.
    BulkLinksResponseV3:
      properties:
        object_id:
          type: integer
          title: Object Id
          description: Объект, в который добавлялись ссылки.
        link_results:
          items:
            $ref: '#/components/schemas/LinkResultV3'
          type: array
          title: Link Results
          description: Итог по каждой переданной ссылке.
      type: object
      required:
      - object_id
      - link_results
      title: BulkLinksResponseV3
      description: Итог массового добавления ссылок в объект.
    LinkResultV3:
      properties:
        url:
          type: string
          title: Url
          description: URL ссылки, к которой относится результат.
        link_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Link Id
          description: Идентификатор созданной ссылки. `null` при ошибке.
        source_slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Slug
          description: Машинное имя площадки, определённой по URL (`2gis`, `yandex_travel`). `null`, если определить не удалось.
        link_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Link Name
          description: Название ссылки, как оно сохранено.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Причина, по которой ссылка не добавлена. `null` при успехе.
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: 'Машинная причина отказа – по ней и следует ветвиться: `source_not_detected`, `source_url_invalid`, `source_requires_upgrade`, `source_already_linked` (площадка в объекте может быть только одна), `link_already_added`. `null` при успехе.'
      type: object
      required:
      - url
      title: LinkResultV3
      description: Итог добавления одной ссылки – успех с `link_id` либо `error`.
    LinkInputV3:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
          description: Адрес страницы объекта на площадке. Площадка определяется по домену.
        is_active:
          type: boolean
          title: Is Active
          description: Собирать ли отзывы по этой ссылке.
          default: true
        link_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Link Name
          description: Своё название ссылки внутри объекта.
      type: object
      required:
      - url
      title: LinkInputV3
      description: Ссылка, передаваемая при создании объекта или добавлении в него.
      example:
        link_name: Яндекс Карты
        url: https://yandex.ru/maps/org/natsional/1049256789/
    LinkV3:
      properties:
        id:
          type: integer
          title: Id
          description: Идентификатор ссылки.
        url:
          type: string
          title: Url
          description: URL страницы объекта на площадке.
        source_id:
          type: integer
          title: Source Id
          description: Идентификатор площадки ссылки (см. `GET /v3/sources`).
        link_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Link Name
          description: Своё название ссылки внутри объекта, если задано.
        auto_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Auto Name
          description: Название, определённое нами по ссылке, с подписью площадки через двоеточие. Показывать стоит `link_name`, если задано, иначе `auto_name`.
        is_active:
          type: boolean
          title: Is Active
          description: Включена ли ссылка в автосбор отзывов.
        scrape_status:
          $ref: '#/components/schemas/ScrapeStatus'
          description: 'Статус последнего сбора: `pending` / `in_progress` / `success` / `failed`.'
        scrape_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Scrape Error
          description: Текст ошибки последнего неудачного сбора. `null`, когда сбор успешен.
        last_scraped_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Scraped At
          description: Момент последнего сбора по ссылке (UTC, ISO 8601).
        last_scraped_review_date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Scraped Review Date
          description: Дата публикации самого свежего собранного отзыва по ссылке.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Момент добавления ссылки в объект (UTC, ISO 8601).
      type: object
      required:
      - id
      - url
      - source_id
      - is_active
      - scrape_status
      - created_at
      title: LinkV3
      description: Ссылка объекта на одной площадке.
    LinkRemoveResponseV3:
      properties:
        message:
          type: string
          title: Message
          description: Человекочитаемый итог операции.
        object_id:
          type: integer
          title: Object Id
          description: Объект, из которого удалена ссылка.
        link_id:
          type: integer
          title: Link Id
          description: Идентификатор удалённой ссылки.
      type: object
      required:
      - message
      - object_id
      - link_id
      title: LinkRemoveResponseV3
      description: Ответ на удаление ссылки из объекта.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    APIKeyCookie:
      type: apiKey
      in: cookie
      name: rewio_session