## Добавить комментарий

`POST /v1/feedback/:id/comments`

Добавляет комментарий к обращению. Требует скоуп `vibe:feedback`. К комментарию можно приложить вложения. Не больше 20 комментариев в минуту на владельца ключа.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string | да | UUID обращения |

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `body` | string | да | Текст комментария, 2–20000 символов |
| `status` | string | нет | Новый статус обращения, применяется вместе с комментарием. Значения — как в [обновлении](./update.md) |
| `attachmentIds` | array | нет | До 5 идентификаторов заранее загруженных вложений. Как загрузить — [Загрузить вложение](./attachments.md) |

## Примеры

### curl — личный ключ

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/comments \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Воспроизвёл на пустом filter, приложил лог запроса." }'
```

### curl — OAuth-приложение

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/comments \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Воспроизвёл на пустом filter, приложил лог запроса." }'
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/comments',
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ body: 'Воспроизвёл на пустом filter, приложил лог запроса.' }),
  },
)
const { data } = await res.json()
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/comments',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ body: 'Воспроизвёл на пустом filter, приложил лог запроса.' }),
  },
)
const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string | UUID комментария |
| `data.authorType` | string | Кто оставил комментарий: `USER` или `PLATFORM` |
| `data.body` | string | Текст комментария |
| `data.createdAt` | string | Дата создания (ISO 8601) |
| `data.feedbackStatus` | string | Статус обращения после комментария |
| `data.previousStatus` | string | Статус обращения до комментария |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "id": "61ae2a00-a7ac-416f-85cc-99873c767d3b",
    "authorType": "USER",
    "body": "Воспроизвёл на пустом filter, приложил лог запроса.",
    "createdAt": "2026-04-19T11:00:00.000Z",
    "feedbackStatus": "AWAITING_USER",
    "previousStatus": "NEW"
  }
}
```

## Пример ответа при ошибке

403 — комментарий без скоупа `vibe:feedback`:

```json
{
  "success": false,
  "error": {
    "code": "FEEDBACK_SCOPE_REQUIRED",
    "message": "Requires management key or vibe:feedback scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | `body` короче 2 или длиннее 20000 символов, либо `attachmentIds` длиннее 5 |
| 403 | `FEEDBACK_SCOPE_REQUIRED` | Комментарий к чужому обращению без скоупа `vibe:feedback`. Автор своего обращения проходит без скоупа — см. «Известные особенности» |
| 404 | `NOT_FOUND` | Обращение не существует или недоступно ключу |
| 409 | `FEEDBACK_CLOSED` | Комментарий автора к обращению, закрытому окончательно (`ARCHIVED` или `WITHDRAWN`). Обращение в статусе `RESOLVED` комментарий автора ПЕРЕОТКРЫВАЕТ — см. «Известные особенности» |
| 429 | `RATE_LIMITED` | Больше 20 комментариев в минуту. Счётчик общий на владельца ключа, а не на ключ. Заголовок `Retry-After` — через сколько секунд повторять |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Комментарий может изменить статус.** По умолчанию комментарий переводит обращение в `AWAITING_USER`. Чтобы задать другой статус, передайте `status` в теле — значения как в [обновлении](./update.md). Поля `feedbackStatus` и `previousStatus` в ответе показывают статус после и до комментария.

**Автор комментирует своё обращение без скоупа.** Если запрос идёт тем же ключом, которым создано обращение, комментарий проходит без скоупа `vibe:feedback`: проверка на автора выполняется до проверки скоупа. Скоуп нужен только для комментариев к чужим обращениям.

**Автором считается человек, а не ключ.** Обращение, созданное другим вашим ключом или заведённое из кабинета, для вас тоже своё: комментарий записывается как сообщение пользователя (`authorType: USER`), поле `resolution` не переписывается, а переданный `status` игнорируется — статус меняют через [обновление](./update.md). Одно условие: такому ключу нужен скоуп `vibe:feedback` — без скоупа своим считается только тот ключ, которым обращение и создано. Ключ приложения и управляющий ключ под это правило не подпадают вовсе: у них владелец ключа и тот, кто пишет, — разные лица.

**Комментарий автора возвращает решённое обращение в работу.** Если обращение в статусе `RESOLVED`, ваш комментарий переводит его в `NEEDS_REVIEW` и снимает отметку о закрытии (`resolvedAt`, `resolvedBy`); текст решения при этом сохраняется. Статусы `ARCHIVED` и `WITHDRAWN` остаются закрытыми — на них по-прежнему приходит `409 FEEDBACK_CLOSED`.

**Поле `resolution` заполняет только закрывающий комментарий.** Комментарий с целевым статусом `RESOLVED` или `ARCHIVED` записывает своё тело в `resolution`; при любом другом статусе поле не меняется. Текст такого комментария всё равно доходит до автора письмом и виден в ленте.

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

- [Получить обращение](/docs/feedback/get)
- [Обновить обращение](/docs/feedback/update)
- [Загрузить вложение](/docs/feedback/attachments)
- [Обратная связь](/docs/feedback)