# Менеджмент-ключи

Менеджмент-ключи (`vibe_live_`) не привязаны к одному порталу и предназначены для автоматизации администрирования: управления API-ключами, просмотра порталов и работы с обратной связью.

## Отличие от ключей портала

| Возможность | API-ключ (`vibe_api_`) | Ключ авторизации (`vibe_app_`) | Менеджмент-ключ (`vibe_live_`) |
|-------------|------------------------|--------------------------------|--------------------------------|
| Привязка к порталу | Да (один портал) | Да (один портал) | Нет (все порталы пользователя) |
| Доступ к сущностям Битрикс24 (deals, tasks и др.) | Да | Да | Нет |
| Управление API-ключами | Нет | Нет | Да |
| Просмотр списка порталов | Нет | Нет | Да |
| Работа с обратной связью | Только свои тикеты | Только свои тикеты | Все тикеты платформы |
| Справочник API (`/v1/guide`) | Отфильтрован по скоупам | Отфильтрован по скоупам | Полный (все сущности) |

## Скоупы менеджмент-ключа

Каждый менеджмент-ключ создаётся с одним или несколькими скоупами. Без нужного скоупа конкретный эндпоинт возвращает `403 MANAGEMENT_SCOPE_REQUIRED` — даже если эндпоинт в принципе доступен менеджмент-ключам.

| Скоуп | Открывает |
|-------|-----------|
| `vibe:mgmt:keys` | `/v1/keys` (список, создание, изменение, удаление, перевыпуск) |
| `vibe:mgmt:portals` | `/v1/portals` |
| `vibe:mgmt:feedback` | `/v1/feedback` (список тикетов, чтение, обновление, комментарии) |

Эндпоинты `/v1/me`, `/v1/guide` и `/v1/openapi.json` доступны любому менеджмент-ключу без отдельного скоупа.

При создании ключа выбирайте только нужные скоупы — если ключ предназначен только для управления API-ключами, скоуп `vibe:mgmt:feedback` ему не нужен.

## Состояние аккаунта владельца

Менеджмент-ключ действует от лица своего владельца, поэтому состояние его аккаунта проверяется на **каждом** эндпоинте контура — и на чтении, и на записи. Проверка идёт раньше проверки скоупа, поэтому эти коды приходят даже там, где нужного скоупа у ключа нет.

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 403 | `OWNER_DELETED` | Аккаунт владельца ключа удалён |
| 403 | `OWNER_BLOCKED` | Аккаунт владельца ключа заблокирован платформой |
| 503 | `ACCOUNT_PENDING_ERASURE` | Владелец запросил удаление своих данных — до конца срока отмены ключ заморожен. В ответе заголовок `Retry-After: 3600`. Отмена запроса возвращает ключу работу, перевыпуск не нужен |
| 409 | `B24_USER_DELETED` | Владелец ключа больше не активный сотрудник целевого аккаунта Битрикс24 — выписать ключ на него нельзя. Проверяется на выпуске (`POST /v1/keys`) и перевыпуске (`POST /v1/keys/:id/rotate`), то есть там, где у нового ключа появляется владелец. Отличается от `NOT_PORTAL_MEMBER`: тот приходит, когда владельца в аккаунте нет вовсе, а этот — когда запись есть, но сотрудник удалён или деактивирован |

Заморозка распространяется на все операции контура, включая выпуск, перевыпуск и удаление API-ключей.

## Доступные эндпоинты

При обращении к эндпоинтам сущностей Битрикс24 возвращается `403 MANAGEMENT_KEY_NO_ENTITY_ACCESS`.

### `GET /v1/me` — самоописание ключа

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

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/me
```

Ответ:
```json
{
  "success": true,
  "data": {
    "type": "management",
    "keyPrefix": "vibe_live_abc123",
    "keySuffix": "f9d2",
    "expiresAt": null,
    "scopes": [],
    "capabilities": [
      "GET https://vibecode.bitrix24.tech/v1/me — this endpoint (management key self-description)",
      "GET https://vibecode.bitrix24.tech/v1/guide — full API reference (portal-agnostic)",
      "GET https://vibecode.bitrix24.tech/v1/keys — list APP keys for a portal (requires portalId query param)",
      "POST https://vibecode.bitrix24.tech/v1/keys — create APP key (requires portalId in body)",
      "GET https://vibecode.bitrix24.tech/v1/portals — list your portals",
      "GET https://vibecode.bitrix24.tech/v1/feedback — list ALL platform feedback (management key sees everything)",
      "GET https://vibecode.bitrix24.tech/v1/feedback/:id — feedback details including comment thread",
      "PATCH https://vibecode.bitrix24.tech/v1/feedback/:id — update status/resolution (legacy, prefer /comments)",
      "POST https://vibecode.bitrix24.tech/v1/feedback/:id/comments — post a team comment, changes status"
    ],
    "portals": [
      {
        "id": "portal-uuid",
        "domain": "mycompany.bitrix24.ru",
        "status": "ACTIVE",
        "role": "ADMIN",
        "appKeyCount": 3
      }
    ],
    "totalAppKeys": 3,
    "quickstart": {
      "step1": "GET https://vibecode.bitrix24.tech/v1/portals — list available portals",
      "step2": "GET https://vibecode.bitrix24.tech/v1/keys?portalId=<id> — list APP keys for a portal",
      "step3": "POST https://vibecode.bitrix24.tech/v1/keys { portalId, name, scopes } — create an APP key",
      "step4": "Use the APP key for entity API calls (deals, tasks, etc.)"
    },
    "docs": "https://vibecode.bitrix24.tech/docs/management-keys"
  }
}
```

В ответе также присутствует объект `feedback` со справочником эндпоинтов, статусов и фильтров для работы с тикетами обратной связи — он используется AI-моделями для автоматической обработки тикетов.

### `GET /v1/guide` — справочник API

Возвращает полный справочник API со всеми сущностями (без фильтрации по скоупам). Используется для подбора нужных эндпоинтов перед созданием API-ключей.

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/guide
```

### `GET /v1/openapi.json` — OpenAPI-спецификация

Возвращает машинно-читаемую OpenAPI 3.1 спецификацию платформы Вайбкод.

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/openapi.json
```

### `GET /v1/portals` — список порталов

Возвращает порталы, к которым пользователь имеет доступ, с ролью на каждом портале.

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/portals
```

### `GET /v1/keys` — список API-ключей портала

Параметр `portalId` обязателен. Возвращаются ключи владельца менеджмент-ключа на указанном портале — и личные `vibe_api_`, и ключи авторизации `vibe_app_`. Значения ключей не возвращаются: свой ключ узнаётся в списке по полям `prefix` и `suffix`.

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.tech/v1/keys?portalId=portal-uuid"
```

| Поле | Тип | Описание |
|------|-----|---------|
| `data[].id` | string | Идентификатор записи ключа. Его принимают эндпоинты, которым нужен ключ как ресурс — например `targetApiKeyId` в [переносе владения ботом](/docs/bots/management/transfer) |
| `data[].name` | string | Название ключа, заданное при создании |
| `data[].prefix` | string | Начало значения ключа |
| `data[].suffix` | string | Последние символы значения ключа |
| `data[].type` | string | Тип ключа. У ключей портала — `APP` |
| `data[].userId` | string | Идентификатор владельца ключа |
| `data[].portalId` | string | Идентификатор портала |
| `data[].clientId` | string \| null | Идентификатор OAuth-приложения у ключа авторизации, `null` у личного ключа |
| `data[].scopes` | array | Скоупы ключа |
| `data[].ipWhitelist` | array | Разрешённые IP-адреса, пустой массив — без ограничения |
| `data[].rateLimit` | number \| null | Индивидуальный лимит запросов, `null` — общий лимит платформы |
| `data[].status` | string | `ACTIVE`, `REVOKED` или `BLOCKED` |
| `data[].accessMode` | string | `READWRITE` или `READONLY` |
| `data[].issuedVia` | string \| null | Канал, которым выписан вебхук ключа: `per-portal` и `cloud-shared` — модуль-коннектор на аккаунте, `dev_key` — ключ разработчика владельца, `legacy` — регистрация через Битрикс24 Network, `none` — вебхук не заводился, у ключа только права `vibe:*`. `null` у ключей, выпущенных до появления поля |
| `data[].expiresAt` | string \| null | Дата окончания срока действия, `null` — бессрочный |
| `data[].lastUsedAt` | string \| null | Дата последнего запроса этим ключом |
| `data[].createdAt` | string | Дата создания |
| `data[].updatedAt` | string | Дата последнего изменения |

```json
{
  "success": true,
  "data": [
    {
      "id": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33",
      "name": "Бот техподдержки",
      "prefix": "vibe_api_XXXXXXXXX",
      "suffix": "XXXX",
      "type": "APP",
      "userId": "a02e7b64-91c3-4f5a-8d20-7e1b3c95a4dc",
      "portalId": "d41f0b93-6c85-42e7-9a13-58bd0e7c2f46",
      "clientId": null,
      "scopes": ["imbot"],
      "ipWhitelist": [],
      "rateLimit": null,
      "status": "ACTIVE",
      "accessMode": "READWRITE",
      "issuedVia": "legacy",
      "expiresAt": null,
      "lastUsedAt": "2026-07-29T09:12:44.301Z",
      "createdAt": "2026-07-14T08:03:17.118Z",
      "updatedAt": "2026-07-14T08:03:17.118Z"
    }
  ]
}
```

Отказы этого запроса:

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 400 | `MISSING_PORTAL_ID` | Не передан обязательный параметр `portalId` |
| 401 | `WRONG_KEY_TYPE` | Запрос отправлен ключом портала — список ключей отдаётся только менеджмент-ключу |
| 403 | `NOT_PORTAL_MEMBER` | Владелец ключа не состоит в портале с указанным `portalId` |
| 403 | `PORTAL_ACCESS_BLOCKED` | Доступ владельца ключа к этому порталу заблокирован |
| 401 | `KEY_INACTIVE` | Менеджмент-ключ отозван или заблокирован |
| 401 | `KEY_EXPIRED` | Срок действия менеджмент-ключа закончился |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | У ключа нет скоупа `vibe:mgmt:keys` |

### `POST /v1/keys` — создание API-ключа

Создаёт новый API-ключ (`vibe_api_`) для указанного портала. В теле передаётся `portalId`, имя и список скоупов. Полный ключ возвращается в поле `rawKey` один раз — сохраните его сразу.

```bash
curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "My Key", "scopes": ["crm", "task"]}' \
  https://vibecode.bitrix24.tech/v1/keys
```

По умолчанию к запрошенным правам добавляются четыре платформенных: `vibe:infra`, `vibe:ai`, `vibe:search`, `vibe:storage`. Ключ из примера выше получит `crm`, `task` и эти четыре.

Нужен ключ ровно с перечисленным — передайте `exactScopes: true`:

```bash
curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "Storage only", "scopes": ["crm", "vibe:storage"], "exactScopes": true}' \
  https://vibecode.bitrix24.tech/v1/keys
```

Такой ключ получит только `crm` и `vibe:storage`, а на `POST /v1/infra/servers` и вызовы AI ответит `403`. Права такого ключа считаются окончательными: платформа не расширяет их на лету, поэтому `GET /v1/me` вернёт ровно то, что было сохранено при выпуске.

| Поле | Тип | Описание |
|------|-----|----------|
| `exactScopes` | boolean | Необязательное, по умолчанию `false`. `true` — сохранить ровно перечисленные права, без четырёх платформенных |

Дополнительные коды ошибок:

| Код | HTTP | Когда возвращается |
|-----|------|---------------------|
| `MISSING_PORTAL_ID` | 400 | В теле запроса не указан `portalId` |
| `BILLING_MODE_NOT_SUPPORTED` | 400 | В теле передано `billing: "subscription"`. Ключи, оплачиваемые подпиской Cowork/Code, выдаются только из кабинета платформы Вайбкод — см. [Свой агент на подписке](/docs/cowork/harness) |
| `NOT_PORTAL_MEMBER` | 403 | Владелец ключа не состоит в указанном портале |
| `PORTAL_NOT_LINKED` | 400 | Портал не подключён к Битрикс24 Network — создать ключ невозможно |
| `PERSONAL_KEY_WEBHOOK_SCOPES_INVALID` | 400 | В `scopes` не осталось ни одного права на данные. Ключ портала выписывается входящим вебхуком Битрикс24, а права `placement`, `entity` и `userfieldtype` требуют контекста приложения и персональному ключу недоступны. Добавьте хотя бы одно право на данные, например `crm` или `user_brief`, либо заведите OAuth-приложение для возможностей приложения |
| `INVALID_SCOPES` | 400 | Часть запрошенных прав недоступна на аккаунте Битрикс24 |
| `MARKETPLACE_REQUIRED` | 402 | На портале нет активной подписки BitrixGPT + Маркетплейс. Приходит только там, где доступ к платформе открывает подписка |
| `BY_PAID_ONLY` | 402 | Доступ открывает платный или демо-тариф Битрикс24. Открывает его и платная подписка Битрикс24 Маркет Плюс — в Беларуси она продаётся |
| `KZ_PAID_ONLY` | 402 | Регион портала открывает доступ по тарифу: платный или демо-тариф Битрикс24, подписка в регионе не продаётся |
| `UZ_PAID_ONLY` | 402 | То же для региона UZ: платный или демо-тариф Битрикс24, подписка в регионе не продаётся |
| `INT_TARIFF_REQUIRED` | 402 | Портал международного сегмента на бесплатном тарифе Битрикс24. На `.com` инфраструктура и выпуск ключей дополнительно требуют тарифа Vibe+ (`INT_VIBE_PLUS_REQUIRED`) |
| `B24_MARKET_SUBSCRIPTION_REQUIRED` | 403 | На аккаунте нет действующей подписки маркетплейса, и вебхук не выписывается. Ссылка на оформление — в `error.details.upgradeUrl` |
| `B24_MARKET_TRIAL_USED` | 403 | Пробный период подписки маркетплейса израсходован — нужна платная подписка. Ссылка на оформление — в `error.details.upgradeUrl` |
| `INT_TARIFF_REQUIRED` | 403 | Тот же отказ по подписке в регионе, где доступ определяется платным тарифом Битрикс24. Ссылки на оформление нет: подписка там не продаётся |
| `B24_INSUFFICIENT_SCOPE` | 403 | Ключу разработчика владельца не хватает прав на аккаунте. Переподключите аккаунт, чтобы ключ разработчика выписался заново |
| `B24_ACCESS_DENIED` | 403 | Битрикс24 не выдал вебхук по правам сотрудника |
| `CONNECTOR_KEY_ISSUE_FORBIDDEN` | 403 | Аккаунт запрещает этому сотруднику выписывать ключи. Право выдаёт администратор аккаунта |
| `CONNECTOR_MODULE_NOT_INSTALLED` | 409 | Модуль-коннектор на аккаунте не установлен, выписать ключ через него нельзя. Состояние постоянное — повтор без установки модуля не поможет |
| `B24_USER_DELETED` | 409 | Владелец ключа удалён из аккаунта Битрикс24 — ключ не создаётся |
| `STALE_DEVELOPER_KEY` | 410 | Ключ разработчика владельца недействителен и автоматически не перевыпускается. Переподключите аккаунт |
| `RECOVERY_FAILED` | 502 | Перевыпуск ключа разработчика не удался, состояние временное — повторите запрос |
| `CONNECTOR_REST_UNAVAILABLE` | 502 | Подписка или пробный период действуют, но Битрикс24 отказал в выписке. Исходная причина — в `error.details.reason`, состояние временное |
| `CONNECTOR_KEY_ISSUE_FAILED` | 502 | Другой отказ модуля-коннектора или недоступность его транспорта. Исходная причина — в `error.details.reason` |
| `DEVKEY_MINT_FAILED` | 502 | Другой отказ выписки через ключ разработчика. Диагностика — в `error.details.b24Code` и `error.details.b24Status` |
| `BITRIX_UNAVAILABLE` | 502 | Битрикс24 не ответил на регистрацию входящего вебхука |

Отказы выписки со статусом `403`, `409`, `410` и `502` из таблицы выше приходят и на перевыпуске `POST /v1/keys/:id/rotate` — оба метода выписывают ключ одним и тем же путём. Тело такого отказа несёт необязательное поле `error.reason` с точной причиной в таксономии платформы, тогда как `error.code` остаётся прежним. Разбирайте отказ по `error.code`, а не по тексту `message`.

Пять отказов со статусом 402 приходят от проверки доступа портала. Какой именно придёт, решает не регион лицензии сам по себе, а то, чем платформа открывает доступ на этом портале: где его открывает подписка — `MARKETPLACE_REQUIRED`, где тариф Битрикс24 — `BY_PAID_ONLY`, `KZ_PAID_ONLY`, `UZ_PAID_ONLY` или `INT_TARIFF_REQUIRED`. Проверка касается **только выписки нового ключа**: перевыпуск `POST /v1/keys/:id/rotate`, автоматическое восстановление ключа и передача владения ей не подчиняются, а уже выданные ключи продолжают работать.

Права `placement`, `entity` и `userfieldtype` не сохраняются и на успешном пути: у созданного персонального ключа они не вернутся в `scopes` ответа, даже если были в запросе рядом с правами на данные. `userfieldconfig` остаётся доступным.

### `GET /v1/keys/:id` — данные одного ключа

Возвращает одну запись ключа без его значения. Состав полей тот же, что у `GET /v1/keys` выше.

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid
```

### `PATCH /v1/keys/:id` — обновление ключа

Можно изменить любое из полей ниже (все необязательны, передавайте только то, что меняете):

| Поле | Тип | Описание |
|------|-----|----------|
| `name` | string | Имя ключа в личном кабинете |
| `scopes` | string[] | Список скоупов — см. [Скоупы](./scopes.md) |
| `status` | `"ACTIVE"` \| `"REVOKED"` | Активация или отзыв ключа |
| `ipWhitelist` | string[] | Список разрешённых IP-адресов |
| `rateLimit` | number \| null | Индивидуальный лимит запросов в секунду |
| `expiresAt` | ISO-8601 \| null | Срок действия ключа (`null` — бессрочный) |

Новый список `scopes` проходит ту же проверку, что и при создании: если после отбрасывания `placement`, `entity` и `userfieldtype` не осталось ни одного права на данные, приходит `400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID`.

Ключи, выданные платформой на её собственных эндпоинтах, возвращаются в работу по особым правилам. Ключ, оплачиваемый подпиской, снова становится активным значением `status` и продлевается полем `expiresAt` только при открытых проверках выдачи: закрытая проверка отвечает `403` со своим кодом — те же пять, что и на перевыпуске, их таблица в разделе `POST /v1/keys/:id/rotate` ниже. Остальные такие ключи — настольного приложения Cowork/Code, агента, проектный ключ для деплоя — здесь не возвращаются в работу вовсе: они выдаются заново там, где выдавались.

| Код | HTTP | Когда возвращается |
|-----|------|---------------------|
| `SYSTEM_KEY_REACTIVATE_FORBIDDEN` | 403 | Запрос переводит в `ACTIVE` или продлевает срок ключа, который выдаёт платформа на своём эндпоинте: настольного приложения Cowork/Code, агента, проектного ключа для деплоя. В тексте ответа сказано, где именно этот ключ выдаётся заново |

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

```bash
curl -X PATCH \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status": "REVOKED"}' \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid
```

### `DELETE /v1/keys/:id` — удаление ключа

Удаляет ключ. Если на ключе есть активные серверы, возвращается `409 KEY_HAS_ACTIVE_SERVERS` — серверы нужно удалить первыми. Если ключом управляется агент или бот, удаление возвращает `409 KEY_HAS_LINKED_AGENT` с полями `details.linkedAgentCount`, `details.linkedBotCount` и списком `details.agents` — сначала удалите агента или бота.

```bash
curl -X DELETE \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid
```

### `POST /v1/keys/:id/rotate` — перевыпуск ключа

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

Если у прежнего ключа портала остались только права контекста приложения — `placement`, `entity`, `userfieldtype`, — перевыпуск не пройдёт. Набор прав проверяется до обращения к порталу, поэтому на любом аккаунте приходит один и тот же отказ `400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID`. Сначала добавьте прежнему ключу право на данные через `PATCH /v1/keys/:id`.

Перевыпуск подчиняется требованию подписки маркетплейса наравне с созданием ключа: без действующей подписки приходит `403 B24_MARKET_SUBSCRIPTION_REQUIRED`, а в регионах, где доступ определяется платным тарифом Битрикс24, — `403 INT_TARIFF_REQUIRED`. Остальные отказы выписки у перевыпуска те же, что у создания, — таблица кодов в разделе `POST /v1/keys` выше. Не относятся к перевыпуску только четыре отказа со статусом `402`: платформенная проверка доступа касается выписки нового ключа. Уже выданные ключи продолжают работать, а перевыпуск возобновляется сразу после активации подписки.

```bash
curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid/rotate
```

Ключи, выданные платформой на её собственных эндпоинтах, перевыпускаются по особым правилам. У ключа, оплачиваемого подпиской, перенос прав не безусловен: перед перевыпуском проходят те же проверки, что и при выдаче такого ключа, и закрытая проверка отвечает `403` со своим кодом. Остальные такие ключи — настольного приложения Cowork/Code, агента, проектный ключ для деплоя — не перевыпускаются здесь вовсе: они выдаются заново там, где выдавались. Прежний ключ во всех этих случаях продолжает работать.

| Код | HTTP | Когда возвращается |
|-----|------|---------------------|
| `SYSTEM_KEY_ROTATE_FORBIDDEN` | 403 | Перевыпускается ключ, который выдаёт платформа на своём эндпоинте: настольного приложения Cowork/Code, агента, проектный ключ для деплоя. В тексте ответа сказано, где именно этот ключ выдаётся заново |
| `COWORK_HARNESS_DISABLED` | 403 | Выдача ключей подписки для сторонних агентов отключена на платформе |
| `COWORK_PLATFORM_DISABLED` | 403 | Cowork/Code отключён на уровне платформы |
| `COWORK_ACCESS_REQUIRED` | 403 | Владельцу ключа доступ к Cowork/Code не открыт |
| `COWORK_EXTERNAL_CLIENTS_DISABLED` | 403 | Администратор портала запретил сторонние клиенты |
| `COWORK_SUBSCRIPTION_INACTIVE` | 403 | Подписка Cowork/Code приостановлена или отменена |

Обычных ключей кабинета эти проверки не касаются — они перевыпускаются как раньше. Что умеет ключ подписки и как его выписать — [Свой агент на подписке](/docs/cowork/harness).

### `GET /v1/feedback` — список тикетов обратной связи

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

```bash
curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.tech/v1/feedback?status=NEW&page=1&limit=50"
```

### `GET /v1/feedback/:id` — карточка тикета

Возвращает тикет со всей цепочкой комментариев.

### `PATCH /v1/feedback/:id` — обновление тикета

Меняет статус и резолюцию тикета.

### `POST /v1/feedback/:id/comments` — комментарий к тикету

Добавляет комментарий команды в цепочку и одновременно меняет статус. Используется AI-моделями для ответа пользователю.

#### Статусы тикетов

| Статус | Когда применяется |
|--------|-------------------|
| `NEW` | Пользователь только что отправил тикет, никто его ещё не смотрел |
| `REVIEWING` | Команда взяла тикет в работу, пользователь пока не получает обновлений |
| `AWAITING_USER` | Команда задала пользователю уточняющий вопрос — ждём ответа (пользователь получает письмо) |
| `NEEDS_REVIEW` | Пользователь ответил на уточнение — команда читает новый комментарий и решает следующий шаг |
| `RESOLVED` | Исправление опубликовано в продуктовой среде, пользователь получил уведомление |
| `ARCHIVED` | Закрыт без правки кода (дубликат, вне темы, не воспроизводится) |
| `WITHDRAWN` | Автор отозвал тикет сам, разбор не требуется |

Ответ пользователя переводит тикет из `AWAITING_USER` в `NEEDS_REVIEW`. Решённый тикет (`RESOLVED`) ответ автора возвращает в работу — статус тоже становится `NEEDS_REVIEW`, а отметка о закрытии (`resolvedAt`, `resolvedBy`) снимается, текст решения при этом сохраняется. На `NEW`, `REVIEWING` и `NEEDS_REVIEW` статус сохраняется, потому что мяч и без того на стороне команды. Поле `updatedAt` при этом обновляется всегда, поэтому очередь, отсортированная по нему, показывает новые ответы независимо от статуса.

#### Категории тикетов

`BUG`, `SUGGESTION`, `DOCS`, `CHAT`, `BOTS`, `OTHER`.

#### Фильтры списка

`?status=NEW&category=BUG&portalId=<uuid>&page=1&limit=50`. Параметр `limit` ограничен значением 100.

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

1. Создайте менеджмент-ключ в личном кабинете (раздел «Менеджмент-ключи»)
2. Получите список порталов: `GET /v1/portals`
3. Посмотрите существующие ключи на нужном портале: `GET /v1/keys?portalId=<id>`
4. Создайте API-ключ с нужными скоупами: `POST /v1/keys { portalId, name, scopes }`
5. Используйте полученный API-ключ (`vibe_api_…`) для работы с данными Битрикс24

## Ограничения

- Менеджмент-ключи не могут обращаться к эндпоинтам сущностей Битрикс24 (`/v1/deals`, `/v1/tasks` и другим)
- Для работы с данными используйте API-ключ (`vibe_api_`) или ключ авторизации (`vibe_app_`)
- При попытке обратиться к неподдерживаемому эндпоинту возвращается `403 MANAGEMENT_KEY_NO_ENTITY_ACCESS`

## Смотрите также

- [Ключи и авторизация](./keys-auth.md)
- [Скоупы](./scopes.md)
- [Быстрый старт](./quickstart.md)
- [Оптимизация и batch](./optimization.md)
- [Коды ошибок](./errors.md)
- [Восстановление доступа к боту](./bots/ownership-recovery.md)