Для AI-агентов: markdown этой страницы — /docs-content/performan/manager-questions.md индекс документации — /llms.txt
Вопросы менеджерского этапа
GET /v1/performan/review/manager/questions
Возвращает вопросы менеджерского этапа кампании: формулировку, тип, обязательность и порядок. Параметр с идентификатором кампании обязателен, навигация по выдаче курсорная.
Параметры
| Параметр | Тип | Обяз. | По умолч. | Описание |
|---|---|---|---|---|
campaignId (query) |
number | да | — | Идентификатор кампании. Список кампаний — GET /v1/performan/review/campaigns |
limit (query) |
number | нет | 50 | Записей на страницу, максимум 200 |
afterCursorId (query) |
number | нет | — | Курсор следующей страницы. Значение берётся из meta.nextCursor.id предыдущего ответа. В первом запросе не передаётся |
Навигация
- Первый запрос идёт без
afterCursorId— приходит первая страница. - Значение
meta.nextCursor.idиз ответа передаётся параметромafterCursorIdследующего запроса. Курсор копируется целиком, собирать его из полей записи нельзя. - Ответ, у которого
meta.nextCursorравенnull, означает конец выдачи. Параметраoffsetи общего количества записей у метода нет.
Примеры
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/performan/review/manager/questions?campaignId=1" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/performan/review/manager/questions?campaignId=1" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/performan/review/manager/questions?campaignId=1', {
headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const body = await res.json()
if (!body.success) {
throw new Error(`${body.error.code}: ${body.error.message}`)
}
// Текстовые вопросы заполняются через API, вопросы с выбором варианта — нет
const answerable = body.data.filter((q) => q.type === '3')
console.log(answerable.map((q) => [q.id, q.title, q.required]))
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/performan/review/manager/questions?campaignId=1', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const body = await res.json()
if (!body.success) {
throw new Error(`${body.error.code}: ${body.error.message}`)
}
console.log(body.data, body.meta.nextCursor)
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
success |
boolean | Всегда true при успехе |
data |
array | Массив вопросов менеджерского этапа |
data[].id |
number | Идентификатор вопроса. Передаётся в поле answers[].questionId при записи ответа |
data[].campaignId |
number | Кампания вопроса. Список — GET /v1/performan/review/campaigns |
data[].campaignStageId |
number | Этап кампании, которому принадлежит вопрос |
data[].title |
string | Формулировка вопроса |
data[].description |
string | Пояснение к вопросу |
data[].type |
string | Тип вопроса строкой: 1 — одиночный выбор, 2 — множественный выбор, 3 — текстовый ответ |
data[].typeLabel |
string | Название типа вопроса на языке портала |
data[].required |
boolean | Нужно ли ответить на вопрос, чтобы завершить оценку |
data[].isRating |
boolean | Формирует ли ответ итоговую оценку карточки |
data[].sort |
number | Порядок вопроса на этапе |
meta.nextCursor |
object | null | Курсор следующей страницы. null — записей больше нет |
meta.nextCursor.id |
number | Значение для параметра afterCursorId следующего запроса |
Пример ответа
{
"success": true,
"data": [
{
"id": 23,
"campaignId": 1,
"campaignStageId": 5,
"title": "Комментарий",
"description": "",
"type": "3",
"typeLabel": "Текстовый ответ",
"required": false,
"isRating": false,
"sort": 90
},
{
"id": 22,
"campaignId": 1,
"campaignStageId": 5,
"title": "Итоговые решения",
"description": "Отметьте применимые пункты — появятся поля для заполнения.",
"type": "2",
"typeLabel": "Множественный выбор",
"required": false,
"isRating": false,
"sort": 80
},
{
"id": 21,
"campaignId": 1,
"campaignStageId": 5,
"title": "Итоговая оценка",
"description": "",
"type": "1",
"typeLabel": "Одиночный выбор",
"required": true,
"isRating": true,
"sort": 70
}
],
"meta": { "nextCursor": { "id": 21 } }
}
Пример ответа при ошибке
400 — не передан обязательный параметр:
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "`campaignId` is required and must be a positive integer"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| 400 | INVALID_PARAMS |
Не передан campaignId либо значение campaignId или afterCursorId не является положительным целым числом либо limit выходит за диапазон 1–200 |
| 401 | MISSING_API_KEY |
Не передан заголовок X-Api-Key |
| 401 | TOKEN_MISSING |
У ключа нет токенов портала. Ключ OAuth-приложения требует заголовок Authorization: Bearer |
| 403 | SCOPE_DENIED |
У ключа нет скоупа performan |
| 404 | ROUTE_NOT_FOUND |
Раздел «Перформанс ревью» порталу не включён. Ответ неотличим от ответа на любой несуществующий адрес |
| 404 | ENTITY_NOT_FOUND |
Раздел включён, но модуля «Перформанс ревью» на портале нет: Битрикс24 отвечает «Метод performan.review.* не найден» |
| 403 | BITRIX_ACCESS_DENIED |
Битрикс24 отказал в доступе. Набор прав, с которым ключ обращается к порталу, не содержит performan |
| 409 | PERFORMAN_SCOPE_JUST_GRANTED |
Ключу Коворка выдан скоуп performan этим же запросом. Повторите запрос — он пройдёт |
| 422 | BITRIX_ERROR |
Битрикс24 отклонил запрос. Причина — в error.message, машинный код Битрикс24 — в error.b24Code |
| 429 | RATE_LIMITED |
Превышена частота запросов на стороне Битрикс24 |
| 429 | QUEUE_OVERFLOW, QUEUE_TIMEOUT |
Очередь запросов портала переполнена или запрос не дождался очереди. Заголовок Retry-After подсказывает задержку |
| 503 | BITRIX_TIMEOUT |
Битрикс24 принял запрос, но не ответил за отведённое время. Для чтения повтор безопасен |
| 502 | BITRIX_UNAVAILABLE |
Битрикс24 недоступен |
Полный список общих ошибок API — Ошибки.
Известные особенности
Неизвестные параметры строки запроса игнорируются. Метод читает campaignId, limit и afterCursorId, остальные отбрасывает без ошибки: запрос с опечаткой в имени параметра отвечает 200 и несуженным списком. Так, revieweeUserId сужает выдачу только у карточек менеджерского ревью — на остальных списках он молча отбрасывается.
Варианты ответа метод не возвращает. У вопроса с типом 1 или 2 есть список вариантов, но их идентификаторы не отдаёт ни этот метод, ни карточка ревью: в поле answers[].selectedOptions попадают только уже выбранные варианты. Пока вариант не выбран в интерфейсе Битрикс24, взять его идентификатор неоткуда, поэтому через API заполняются только текстовые вопросы с типом 3.
Обязательный рейтинговый вопрос закрывает завершение оценки. Вопрос с required: true и isRating: true имеет тип 1 — одиночный выбор. Из-за предыдущего ограничения ответить на него через API нельзя, поэтому завершение менеджерской оценки вызовом POST /v1/performan/review/manager/answers с isAutosave: false вернёт 422 BITRIX_ERROR с сообщением о незаполненных обязательных полях.
Порядок выдачи задан убыванием id, а не полем sort. Поле sort определяет, в каком порядке вопросы стоят на этапе в интерфейсе Битрикс24, и на порядок записей в ответе не влияет. Чтобы показать вопросы так же, как их видит сотрудник, соберите весь список и отсортируйте его по sort по возрастанию на своей стороне.