Для 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 предыдущего ответа. В первом запросе не передаётся

Навигация

  1. Первый запрос идёт без afterCursorId — приходит первая страница.
  2. Значение meta.nextCursor.id из ответа передаётся параметром afterCursorId следующего запроса. Курсор копируется целиком, собирать его из полей записи нельзя.
  3. Ответ, у которого meta.nextCursor равен null, означает конец выдачи. Параметра offset и общего количества записей у метода нет.

Примеры

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/performan/review/manager/questions?campaignId=1" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
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 — личный ключ

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-приложение

javascript
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 следующего запроса

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

JSON
{
  "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 — не передан обязательный параметр:

JSON
{
  "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 по возрастанию на своей стороне.

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