{"openapi":"3.1.0","info":{"title":"Reviews API","description":"\nОтзывы 2GIS, рейтинги локаций и аналитика организации — для CRM, ERP, BI и других систем.\n\n**Вход.** Каждый запрос несёт API-ключ организации: `Authorization: Bearer rk_…`.\nКлюч создаёт владелец организации; у ключа есть набор прав и, при необходимости, список локаций.\n\n**Листание.** Списки отдаются частями. В ответе есть `has_more` и курсор — передайте его в следующем запросе.\n\n**Время.** Все моменты времени — в UTC, формат ISO 8601 (`2026-11-14T08:35:15Z`).\n\n**Лимит.** Не больше 120 запросов в минуту на ключ. Остаток — в заголовках\n`X-RateLimit-Remaining` и `X-RateLimit-Reset`; при превышении — ответ 429 с заголовком `Retry-After`.\n\n**Ошибки.** `{\"error\": {\"code\": \"...\", \"message\": \"...\", \"request_id\": \"...\"}}` — опирайтесь на `code`.\n\n**Вебхуки.** Чтобы не опрашивать API, подпишитесь на события: `POST /v1/webhooks` (ключу нужно право\n`webhooks:manage`). Сервис сам отправит событие на ваш адрес и повторит отправку, если адрес не ответил.\n\n**Свежесть данных.** Новый отзыв появляется в течение ~5 минут после публикации в 2GIS. Правки и ответы\nна старых отзывах, а также пропажа отзывов замечаются раз в сутки.\n","version":"1.0.0"},"servers":[{"url":"https://api.review.cerebralabs.kz","description":"Рабочий адрес API"}],"paths":{"/v1/organization":{"get":{"tags":["Организация"],"summary":"Организация, которой принадлежит ключ","operationId":"get_organization_v1_organization_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/locations":{"get":{"tags":["Локации"],"summary":"Список локаций","description":"Действующие локации организации с рейтингом карточки 2GIS и числом отзывов.","operationId":"list_locations_v1_locations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Location"},"type":"array","title":"Response List Locations V1 Locations Get"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/locations/{location_id}":{"get":{"tags":["Локации"],"summary":"Одна локация","operationId":"get_location_v1_locations__location_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/reviews":{"get":{"tags":["Отзывы"],"summary":"Список отзывов","description":"Отзывы организации.\n\n**Лента.** `sort=created_desc` (по умолчанию) — от новых к старым; листайте по `next_cursor`, пока `has_more`.\n\n**Синхронизация.** `sort=changed_asc` отдаёт отзывы в порядке, в котором сервис замечал изменения\n(появление, правка, ответ компании, пропажа из 2GIS). Пройдите список до конца и сохраните последний\n`next_cursor`; следующий запрос с ним вернёт только то, что изменилось с тех пор.","operationId":"list_reviews_v1_reviews_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Одна или несколько локаций; по умолчанию все","title":"Location Id"},"description":"Одна или несколько локаций; по умолчанию все"},{"name":"rating","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"description":"Оценки от 1 до 5, можно несколько","title":"Rating"},"description":"Оценки от 1 до 5, можно несколько"},{"name":"created_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Написанные не раньше этого момента (ISO 8601)","title":"Created Since"},"description":"Написанные не раньше этого момента (ISO 8601)"},{"name":"created_until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Написанные раньше этого момента","title":"Created Until"},"description":"Написанные раньше этого момента"},{"name":"changed_since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Изменившиеся не раньше этого момента","title":"Changed Since"},"description":"Изменившиеся не раньше этого момента"},{"name":"has_answer","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true — с ответом компании, false — без ответа","title":"Has Answer"},"description":"true — с ответом компании, false — без ответа"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Поиск по тексту отзыва","title":"Search"},"description":"Поиск по тексту отзыва"},{"name":"include_removed","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Показывать отзывы, пропавшие из 2GIS. По умолчанию: нет для sort=created_desc, да для sort=changed_asc — иначе при синхронизации пропажа отзыва останется незамеченной","title":"Include Removed"},"description":"Показывать отзывы, пропавшие из 2GIS. По умолчанию: нет для sort=created_desc, да для sort=changed_asc — иначе при синхронизации пропажа отзыва останется незамеченной"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","pattern":"^(created_desc|changed_asc)$","description":"created_desc — сначала новые; changed_asc — в порядке изменения, для синхронизации","default":"created_desc","title":"Sort"},"description":"created_desc — сначала новые; changed_asc — в порядке изменения, для синхронизации"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Значение next_cursor из предыдущего ответа","title":"Cursor"},"description":"Значение next_cursor из предыдущего ответа"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewList"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/reviews/{review_id}":{"get":{"tags":["Отзывы"],"summary":"Один отзыв","description":"Отзыв по его ID, в том числе пропавший из 2GIS.","operationId":"get_review_v1_reviews__review_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"review_id","in":"path","required":true,"schema":{"type":"string","title":"Review Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/events":{"get":{"tags":["События"],"summary":"Лента событий","description":"Что изменилось в отзывах и рейтингах: новые отзывы, правки, ответы компании, пропажи.\n\nСобытия идут в порядке появления. Запомните `next_after` из ответа и передайте его в `after`\nпри следующем запросе — получите только новые события. Локация показывает события с момента\nеё подключения к организации.","operationId":"list_events_v1_events_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"ID последнего полученного события; 0 — с начала","default":0,"title":"After"},"description":"ID последнего полученного события; 0 — с начала"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Только события не раньше этого момента (ISO 8601)","title":"Since"},"description":"Только события не раньше этого момента (ISO 8601)"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Типы событий, можно несколько","title":"Type"},"description":"Типы событий, можно несколько"},{"name":"location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Одна или несколько локаций; по умолчанию все","title":"Location Id"},"description":"Одна или несколько локаций; по умолчанию все"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/summary":{"get":{"tags":["Аналитика"],"summary":"Сводка за период","description":"Показатели за период, те же показатели за предыдущий период и таблица локаций с тремя рейтингами.\n\nВ расчёты идут только отзывы, которые сейчас есть в 2GIS и учитываются им в рейтинге.","operationId":"summary_v1_analytics_summary_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Начало периода; по умолчанию 30 дней назад","title":"Date From"},"description":"Начало периода; по умолчанию 30 дней назад"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Конец периода включительно; по умолчанию сегодня","title":"Date To"},"description":"Конец периода включительно; по умолчанию сегодня"},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1098,"minimum":1},{"type":"null"}],"description":"Последние N дней, включая сегодня","title":"Days"},"description":"Последние N дней, включая сегодня"},{"name":"location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Локации; по умолчанию все","title":"Location Id"},"description":"Локации; по умолчанию все"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Summary"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/analytics/timeseries":{"get":{"tags":["Аналитика"],"summary":"Динамика по дням, неделям или месяцам","description":"Число отзывов, средняя оценка и негатив по дням, неделям или месяцам.","operationId":"timeseries_v1_analytics_timeseries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date To"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1098,"minimum":1},{"type":"null"}],"description":"Последние N дней, включая сегодня","title":"Days"},"description":"Последние N дней, включая сегодня"},{"name":"location_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Location Id"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","pattern":"^(day|week|month)$","default":"day","title":"Granularity"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TimeseriesPoint"},"title":"Response Timeseries V1 Analytics Timeseries Get"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/locations/{location_id}/rating-history":{"get":{"tags":["Аналитика"],"summary":"История рейтинга карточки 2GIS","description":"Как менялся рейтинг карточки в 2GIS. Снимки делаются раз в сутки с момента подключения сбора.","operationId":"rating_history_v1_locations__location_id__rating_history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"location_id","in":"path","required":true,"schema":{"type":"string","title":"Location Id"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date To"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1098,"minimum":1},{"type":"null"}],"description":"Последние N дней, включая сегодня","title":"Days"},"description":"Последние N дней, включая сегодня"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RatingHistoryPoint"},"title":"Response Rating History V1 Locations  Location Id  Rating History Get"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks":{"get":{"tags":["Вебхуки"],"summary":"Вебхуки этого ключа","operationId":"list_webhooks_v1_webhooks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Webhook"},"type":"array","title":"Response List Webhooks V1 Webhooks Get"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Вебхуки"],"summary":"Создать вебхук","description":"Сервис начнёт отправлять события организации на указанный адрес.\n\nСообщение — тот же объект, что отдаёт `GET /v1/events`. Оно подписано по спецификации\nStandard Webhooks (заголовки `webhook-id`, `webhook-timestamp`, `webhook-signature`); секрет для\nпроверки подписи есть только в ответе на этот запрос. На сообщение нужно ответить кодом 2xx\nза 10 секунд, иначе оно будет отправлено повторно (до 9 попыток за двое суток).","operationId":"create_webhook_v1_webhooks_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/webhooks/{webhook_id}":{"get":{"tags":["Вебхуки"],"summary":"Один вебхук","operationId":"get_webhook_v1_webhooks__webhook_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Вебхуки"],"summary":"Изменить вебхук","operationId":"update_webhook_v1_webhooks__webhook_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Вебхуки"],"summary":"Удалить вебхук","operationId":"delete_webhook_v1_webhooks__webhook_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/{webhook_id}/rotate-secret":{"post":{"tags":["Вебхуки"],"summary":"Сменить секрет подписи","description":"Прежний секрет перестаёт действовать сразу.","operationId":"rotate_secret_v1_webhooks__webhook_id__rotate_secret_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/{webhook_id}/test":{"post":{"tags":["Вебхуки"],"summary":"Отправить проверочное сообщение","description":"На адрес уйдёт сообщение типа `ping`. Результат — в журнале доставок через несколько секунд.","operationId":"send_test_v1_webhooks__webhook_id__test_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delivery"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/{webhook_id}/deliveries":{"get":{"tags":["Вебхуки"],"summary":"Журнал доставок","description":"Что и когда отправлялось на адрес, от новых к старым.","operationId":"list_deliveries_v1_webhooks__webhook_id__deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"integer","title":"Webhook Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(pending|succeeded|failed)$"},{"type":"null"}],"title":"Status"}},{"name":"before","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Показать отправки старше этой (её id)","title":"Before"},"description":"Показать отправки старше этой (её id)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryList"}}}},"401":{"description":"Ключ не передан или недействителен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Ключу это не разрешено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Не найдено","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Некорректные параметры запроса","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Delivery":{"properties":{"id":{"type":"integer","title":"Id"},"event_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Event Id","description":"ID события; null у проверочного сообщения"},"type":{"type":"string","title":"Type"},"status":{"type":"string","title":"Status","description":"pending | succeeded | failed"},"attempts":{"type":"integer","title":"Attempts"},"next_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Attempt At"},"last_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Attempt At"},"last_status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Status Code"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error"},"created_at":{"type":"string","title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"}},"type":"object","required":["id","event_id","type","status","attempts","next_attempt_at","last_attempt_at","last_status_code","last_error","created_at","delivered_at"],"title":"Delivery"},"DeliveryList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Delivery"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["data","has_more"],"title":"DeliveryList"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Код ошибки для программы: unauthorized, invalid_api_key, insufficient_scope, not_found, validation_error, invalid_cursor, rate_limited, internal_error и др."},"message":{"type":"string","title":"Message","description":"Пояснение для человека"},"request_id":{"type":"string","title":"Request Id","description":"Номер запроса — назовите его поддержке"},"details":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message","request_id"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"Event":{"properties":{"id":{"type":"integer","title":"Id","description":"Растёт в порядке появления событий; годится как курсор (параметр after)"},"type":{"type":"string","title":"Type","description":"review.created | review.updated | review.answered | review.removed | review.restored | location.rating_changed"},"occurred_at":{"type":"string","title":"Occurred At","description":"Когда сервис заметил изменение"},"location_id":{"type":"string","title":"Location Id"},"location_name":{"type":"string","title":"Location Name"},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Для событий review.*: review — отзыв на момент события; у review.updated и review.answered ещё changed (что изменилось) и previous (прежние значения). Для location.rating_changed: rating, previous_rating, rating_confirmed, reviews_count"}},"type":"object","required":["id","type","occurred_at","location_id","location_name","data"],"title":"Event"},"EventList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Event"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_after":{"type":"integer","title":"Next After","description":"Передайте в параметре after, чтобы получить следующие события"}},"type":"object","required":["data","has_more","next_after"],"title":"EventList"},"Location":{"properties":{"id":{"type":"string","title":"Id","description":"ID локации — он же номер карточки в 2GIS"},"name":{"type":"string","title":"Name","description":"Название локации внутри организации"},"card_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Name","description":"Название карточки по данным 2GIS, если оно известно"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"rating_2gis":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating 2Gis","description":"Рейтинг карточки в 2GIS, как на карте"},"reviews_count_2gis":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count 2Gis","description":"Число отзывов по данным 2GIS"},"rating_2gis_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rating 2Gis Updated At"},"rating_target":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Target","description":"Цель по рейтингу, заданная владельцем"},"reviews_count":{"type":"integer","title":"Reviews Count","description":"Отзывов в сервисе (без пропавших из 2GIS)"},"last_review_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Review At"},"initial_load_done":{"type":"boolean","title":"Initial Load Done","description":"false — отзывы новой локации ещё загружаются (до нескольких минут)"}},"type":"object","required":["id","name","card_name","city","address","rating_2gis","reviews_count_2gis","rating_2gis_updated_at","rating_target","reviews_count","last_review_at","initial_load_done"],"title":"Location"},"LocationSummary":{"properties":{"location_id":{"type":"string","title":"Location Id"},"name":{"type":"string","title":"Name"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"rating_2gis":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating 2Gis","description":"Рейтинг карточки в 2GIS, как на карте"},"reviews_count_2gis":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count 2Gis"},"rating_calculated":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Calculated","description":"Расчётный рейтинг за последние 90 дней со сглаживанием"},"avg_rating_90d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rating 90D","description":"Обычное среднее за те же 90 дней, без сглаживания"},"reviews_90d":{"type":"integer","title":"Reviews 90D"},"rating_target":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Target"},"target_gap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Target Gap","description":"Расчётный рейтинг минус цель; отрицательное — ниже цели"},"target_gap_2gis":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Target Gap 2Gis","description":"Рейтинг 2GIS минус цель"},"period":{"$ref":"#/components/schemas/PeriodMetrics"},"previous":{"$ref":"#/components/schemas/PeriodMetrics"}},"type":"object","required":["location_id","name","city","rating_2gis","reviews_count_2gis","rating_calculated","avg_rating_90d","reviews_90d","rating_target","target_gap","target_gap_2gis","period","previous"],"title":"LocationSummary"},"Organization":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"locations_count":{"type":"integer","title":"Locations Count","description":"Число локаций, доступных этому ключу"}},"type":"object","required":["id","name","locations_count"],"title":"Organization"},"PeriodMetrics":{"properties":{"reviews":{"type":"integer","title":"Reviews"},"avg_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rating"},"negative":{"type":"integer","title":"Negative","description":"Отзывов с оценкой 3★ и ниже"},"negative_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Negative Share","description":"Доля негатива, от 0 до 1"},"response_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Response Rate","description":"Доля отзывов с ответом компании, от 0 до 1"},"negative_response_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Negative Response Rate","description":"Доля негативных отзывов с ответом, от 0 до 1"},"unanswered_negative":{"type":"integer","title":"Unanswered Negative"},"median_response_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Response Hours","description":"Медианное время до ответа компании, часы"},"distribution":{"additionalProperties":{"type":"integer"},"type":"object","title":"Distribution","description":"Число отзывов по оценкам: ключи '1'..'5'"}},"type":"object","required":["reviews","avg_rating","negative","negative_share","response_rate","negative_response_rate","unanswered_negative","median_response_hours","distribution"],"title":"PeriodMetrics"},"RatingHistoryPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count"}},"type":"object","required":["date","rating","reviews_count"],"title":"RatingHistoryPoint"},"RatingWindow":{"properties":{"avg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg"},"reviews":{"type":"integer","title":"Reviews"},"days":{"type":"integer","title":"Days"}},"type":"object","required":["avg","reviews","days"],"title":"RatingWindow"},"Review":{"properties":{"id":{"type":"string","title":"Id"},"location_id":{"type":"string","title":"Location Id"},"location_name":{"type":"string","title":"Location Name"},"author_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Name"},"rating":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating","description":"Оценка от 1 до 5"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"Когда отзыв написан"},"edited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Edited At","description":"Когда автор его правил, по данным 2GIS"},"changed_at":{"type":"string","title":"Changed At","description":"Когда сервис заметил последнее изменение отзыва: появление, правку, ответ, пропажу, возврат"},"is_rated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Rated","description":"Учитывает ли 2GIS отзыв в рейтинге карточки"},"is_hidden":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Hidden"},"likes_count":{"type":"integer","title":"Likes Count"},"photo_urls":{"items":{"type":"string"},"type":"array","title":"Photo Urls"},"answer":{"anyOf":[{"$ref":"#/components/schemas/ReviewAnswer"},{"type":"null"}],"description":"Официальный ответ компании; null — ответа нет"},"removed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Removed At","description":"Когда отзыв пропал из 2GIS; null — отзыв на месте"}},"type":"object","required":["id","location_id","location_name","author_name","rating","text","created_at","edited_at","changed_at","is_rated","is_hidden","likes_count","photo_urls","answer","removed_at"],"title":"Review"},"ReviewAnswer":{"properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"answered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answered At","description":"Дата текущего ответа по данным 2GIS"},"first_answered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Answered At","description":"Когда компания ответила впервые; не меняется, если ответ переписали"}},"type":"object","required":["text","answered_at"],"title":"ReviewAnswer"},"ReviewList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Review"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Передайте в параметре cursor, чтобы получить продолжение. При sort=changed_asc возвращается всегда: сохраните его и в следующий раз получите только новые изменения"}},"type":"object","required":["data","has_more","next_cursor"],"title":"ReviewList"},"Summary":{"properties":{"date_from":{"type":"string","format":"date","title":"Date From"},"date_to":{"type":"string","format":"date","title":"Date To"},"previous_from":{"type":"string","format":"date","title":"Previous From"},"previous_to":{"type":"string","format":"date","title":"Previous To"},"timezone":{"type":"string","title":"Timezone","description":"Часовой пояс, в котором считаются сутки"},"period":{"$ref":"#/components/schemas/PeriodMetrics"},"previous":{"$ref":"#/components/schemas/PeriodMetrics","description":"Те же показатели за предыдущий период такой же длины"},"rating_window":{"$ref":"#/components/schemas/RatingWindow","description":"Средняя оценка по выбранным локациям за 90 дней"},"locations":{"items":{"$ref":"#/components/schemas/LocationSummary"},"type":"array","title":"Locations"}},"type":"object","required":["date_from","date_to","previous_from","previous_to","timezone","period","previous","rating_window","locations"],"title":"Summary"},"TimeseriesPoint":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Начало дня, недели (понедельник) или месяца"},"reviews":{"type":"integer","title":"Reviews"},"avg_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Rating"},"negative":{"type":"integer","title":"Negative"}},"type":"object","required":["date","reviews","avg_rating","negative"],"title":"TimeseriesPoint"},"Webhook":{"properties":{"id":{"type":"integer","title":"Id"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Пусто — все события"},"location_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Location Ids","description":"null — все локации организации"},"is_active":{"type":"boolean","title":"Is Active"},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason","description":"manual — отключён вручную; failures — несколько дней ничего не удавалось доставить; gone — получатель ответил 410; key_revoked — отозван ключ"},"failing_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failing Since","description":"С какого момента ничего не удаётся доставить"},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success At"},"last_failure_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Failure At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","url","description","event_types","location_ids","is_active","disabled_reason","failing_since","last_success_at","last_failure_at","created_at"],"title":"Webhook"},"WebhookCreated":{"properties":{"secret":{"type":"string","title":"Secret","description":"Секрет для проверки подписи (Standard Webhooks). Показывается один раз"},"id":{"type":"integer","title":"Id"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Пусто — все события"},"location_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Location Ids","description":"null — все локации организации"},"is_active":{"type":"boolean","title":"Is Active"},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason","description":"manual — отключён вручную; failures — несколько дней ничего не удавалось доставить; gone — получатель ответил 410; key_revoked — отозван ключ"},"failing_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failing Since","description":"С какого момента ничего не удаётся доставить"},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success At"},"last_failure_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Failure At"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["secret","id","url","description","event_types","location_ids","is_active","disabled_reason","failing_since","last_success_at","last_failure_at","created_at"],"title":"WebhookCreated"},"WebhookInput":{"properties":{"url":{"type":"string","maxLength":2000,"minLength":1,"title":"Url","description":"Адрес получателя: только https, публичный сервер"},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Типы событий; пусто — все"},"location_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Location Ids","description":"Локации; не задано — все доступные ключу"}},"type":"object","required":["url"],"title":"WebhookInput"},"WebhookPatch":{"properties":{"url":{"anyOf":[{"type":"string","maxLength":2000,"minLength":1},{"type":"null"}],"title":"Url"},"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Description"},"event_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Event Types"},"location_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Location Ids","description":"Пустой список — все доступные ключу"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"WebhookPatch"},"WebhookSecret":{"properties":{"secret":{"type":"string","title":"Secret","description":"Секрет для проверки подписи (Standard Webhooks). Показывается один раз"}},"type":"object","required":["secret"],"title":"WebhookSecret"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"API-ключ организации: `Authorization: Bearer rk_…`","scheme":"bearer"}}}}