#Feedback API

Программный канал обратной связи. AI-модели, интеграции и внешние инструменты отправляют баги, предложения и вопросы прямо из кода — с контекстом ошибки, окружением и шагами воспроизведения. Всё, что приходит через API, попадает в тот же трекер, что и фидбек с UI-формы.

Базовый URL: https://vibecode.bitrix24.tech/v1 Авторизация: заголовок X-Api-Key Rate limit: 5 запросов в минуту на ключ для POST /feedback

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

curl -X POST https://vibecode.bitrix24.tech/v1/feedback \
  -H "X-Api-Key: vibe_app_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "BUG",
    "title": "POST /v1/deals возвращает 500 при пустом filter",
    "body": "При вызове POST /v1/deals/search с body {\"filter\":{}} получаю 500. Ожидал пустой массив или 400. Стек: ...",
    "context": {
      "endpoint": "/v1/deals/search",
      "request": {"filter": {}},
      "httpStatus": 500,
      "requestId": "req_abc123"
    }
  }'

Ответ:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "category": "BUG",
    "title": "POST /v1/deals возвращает 500 при пустом filter",
    "status": "NEW",
    "createdAt": "2026-04-19T10:30:00.000Z"
  }
}

Тикет-номер, который увидит пользователь и мы в админке — VB- + первые 8 символов UUID. Из примера выше это VB-a1b2c3d4. Сохраните его, если нужно сослаться на обращение в переписке.

#Типы ключей и что они могут

Endpoint POST /v1/feedback принимает и APP-ключи (vibe_app_*), и менеджмент-ключи (vibe_live_*), но с разными правами:

Менеджмент-ключи намеренно не могут создавать фидбек — они не привязаны к конкретному порталу, поэтому запись «от кого» была бы бессмысленной. Если нужно отправить обращение программно — используйте APP-ключ.

Если попытаться отправить фидбек менеджмент-ключом, сервер вернёт:

{
  "success": false,
  "error": {
    "code": "MANAGEMENT_KEY_READ_ONLY",
    "message": "Management keys can only read and update feedback, not create"
  }
}

#Скоуп `vibe:feedback`

В отличие от vibe:infra и vibe:ai, скоуп vibe:feedback не добавляется автоматически ко всем ключам. Его нужно явно включить при создании или обновлении ключа.

Зачем: скоуп даёт ключу расширенный доступ на чтение и обновление всего фидбека портала (а не только своих обращений). Выдаётся адресно — например, ключу, который крутится в службе поддержки и разбирает очередь обращений.

#POST /v1/feedback

Создание обращения.

#Body

#Категории

• BUG — что-то сломано или работает не так, как в документации
• SUGGESTION — фича-реквест или улучшение
• DOCS — документация неполная, устарела или противоречит коду
• CHAT — обратная связь по чат-платформе (сообщения, диалоги, файлы)
• BOTS — обратная связь по бот-платформе (регистрация, события, команды)
• OTHER — что-то, что не попадает в остальные категории

#Почему API лучше UI

У обращений, отправленных через API, есть поле source: "api" (у UI-формы — source: "ui"). Портал определяется автоматически по владельцу ключа, ID пользователя — по владельцу ключа (если он есть). То есть AI-модели не нужно просить пользователя что-то вводить — вы сами знаете requestId, версии, тело запроса и ответ сервера. Приложите их в context — тикет обработается быстрее и без уточняющих вопросов.

#GET /v1/feedback

Список обращений с фильтрами и пагинацией.

curl -H "X-Api-Key: vibe_app_xxx" \
  "https://vibecode.bitrix24.tech/v1/feedback?status=NEW&category=BUG&page=1&limit=20"

#Query-параметры

#Что возвращается

• Обычный APP-ключ: только свои обращения (те, что отправлены с этого же ключа)
• APP-ключ со скоупом vibe:feedback: все обращения своего портала, плюс поля portalDomain, userName, userId, apiKeyId
• Менеджмент-ключ: все обращения всех порталов, те же расширенные поля

Ответ:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "category": "BUG",
      "title": "...",
      "body": "...",
      "status": "NEW",
      "source": "api",
      "resolution": null,
      "createdAt": "2026-04-19T10:30:00.000Z",
      "resolvedAt": null
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

#GET /v1/feedback/:id

Одно обращение по ID.

curl -H "X-Api-Key: vibe_app_xxx" \
  "https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-..."

Возвращает поля как в списке, плюс context (исходный JSON, который вы передавали при создании).

Правила доступа те же:

• Обычный APP-ключ: только своё обращение (по apiKeyId)
• APP-ключ + vibe:feedback: любое обращение своего портала
• Менеджмент-ключ: любое обращение

Если обращение не существует или ключ не имеет к нему доступа — 404 NOT_FOUND. Это намеренно единый ответ — чтобы не давать возможности по кодам различать «не существует» и «существует, но чужой».

#PATCH /v1/feedback/:id

Обновление статуса и резолюции обращения.

Кто может: только менеджмент-ключи или APP-ключи со скоупом vibe:feedback. Обычный APP-ключ без скоупа получит 403 FEEDBACK_SCOPE_REQUIRED — даже для своих обращений. Это сознательное ограничение: закрытие тикета — действие стороны разработчика платформы, а не автора обращения.

curl -X PATCH https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-... \
  -H "X-Api-Key: vibe_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "RESOLVED",
    "resolution": "Fixed in release 2026-04-19. Empty filter now returns 200 with empty array."
  }'

#Поля

При переводе в RESOLVED автоматически проставляются resolvedAt и resolvedBy. Автору обращения уходит email с текстом резолюции, если у него есть email в профиле.

#Жизненный цикл обращения

NEW
  └─ REVIEWING  — взяли в работу, пушим исправление на прод
       ├─ AWAITING_USER   — нужен ответ/уточнение от пользователя
       ├─ NEEDS_REVIEW    — переспросим у другого члена команды
       └─ RESOLVED        — исправили и задеплоили
                          (письмо автору)
  └─ ARCHIVED   — дубликат / вне скоупа / отклонили

Переходы свободные — любой статус можно установить в любой момент (state-машины нет). Но важно: никогда не ставьте RESOLVED до того, как фикс задеплоен на прод. Пользователь получит письмо «исправлено», а по факту исправление ещё не доступно. Промежуточный безопасный статус — REVIEWING.

#Windows / PowerShell и UTF-8

Кириллица в title / body / resolution может превратиться в знаки вопроса (?), если запрос отправляется из Windows PowerShell без явной UTF-8 сериализации. Это клиентская проблема — бэкенд получает уже испорченные байты.

Минимальный рабочий пример:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

$body = @{
  category = 'DOCS'
  title    = 'Опечатка в документации'
  body     = 'В разделе про deploy пропущено предупреждение о PowerShell и UTF-8.'
} | ConvertTo-Json -Compress

$bytes = [System.Text.Encoding]::UTF8.GetBytes($body)

Invoke-WebRequest `
  -Uri 'https://vibecode.bitrix24.tech/v1/feedback' `
  -Method POST `
  -Headers @{
    'X-Api-Key'    = $env:VIBE_KEY
    'Content-Type' = 'application/json; charset=utf-8'
  } `
  -Body $bytes

Подробный разбор причины и распространённых ошибок см. в bots.md → раздел «Windows / PowerShell и UTF-8» (он общий для всех клиентов на PowerShell, не только для Bot API).

Node.js (fetch) и Python (requests) работают корректно без дополнительных настроек — проблема специфична для PowerShell.

#Коды ошибок

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

• Ключи и авторизация — типы ключей, скоупы
• Коды ошибок — общий справочник ошибок API