Для AI-агентов: markdown этой страницы — /docs-content/performan/manager-reviews.md индекс документации — /llms.txt

Карточки менеджерского ревью

GET /v1/performan/review/manager/reviews

Возвращает карточки менеджерского этапа кампании, где владелец ключа выступает оценивающим: ответы, статус, итоговую оценку и шкалу. Идентификатор карточки из ответа — это relationId для записи ответа.

Параметры

Параметр Тип Обяз. По умолч. Описание
campaignId (query) number да — Идентификатор кампании. Список кампаний — GET /v1/performan/review/campaigns
revieweeUserId (query) number нет — Сузить выдачу до одного оцениваемого сотрудника. Список сотрудников — GET /v1/users
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/reviews?campaignId=1&revieweeUserId=42" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/performan/review/manager/reviews?campaignId=1&revieweeUserId=42" \
  -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/reviews?campaignId=1&revieweeUserId=42', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const body = await res.json()

if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

for (const card of body.data) {
  // id карточки — это relationId в теле записи ответа
  console.log(card.id, card.revieweeUserName, card.status, card.rate)
}

console.log(body.meta.nextCursor)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/performan/review/manager/reviews?campaignId=1&revieweeUserId=42', {
  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 Идентификатор карточки. Он же relationId в теле записи ответа — в адресе метода его нет
data[].campaignId number Кампания карточки. Список — GET /v1/performan/review/campaigns
data[].campaignStageId number Этап кампании, к которому относится карточка
data[].stageType string Тип этапа. У этого метода — managersReview
data[].revieweeUserId number Оцениваемый сотрудник. Карточка сотрудника — GET /v1/users/:id
data[].revieweeUserName string Имя оцениваемого сотрудника
data[].reviewerUserId number Оценивающий сотрудник. На менеджерском этапе совпадает с managerUserId
data[].reviewerUserName string Имя оценивающего сотрудника
data[].managerUserId number Руководитель оцениваемого. Карточка сотрудника — GET /v1/users/:id
data[].managerUserName string Имя руководителя
data[].status string Состояние карточки: new — не заполнена, completed — завершена, rejected — отклонена, published — опубликована
data[].rate number Итоговая оценка по рейтинговому вопросу. 0 — оценка не выставлена
data[].comment string Комментарий к карточке
data[].answers array Ответы по вопросам этапа. У незаполненной карточки массив пустой
data[].answers[].questionId number Идентификатор вопроса. Список вопросов — GET /v1/performan/review/manager/questions
data[].answers[].questionTitle string Формулировка вопроса
data[].answers[].questionDescription string Пояснение к вопросу
data[].answers[].questionType string Тип вопроса строкой: 1 — одиночный выбор, 2 — множественный выбор, 3 — текстовый ответ
data[].answers[].questionTypeLabel string Название типа вопроса на языке портала
data[].answers[].isRating boolean Формирует ли ответ итоговую оценку карточки
data[].answers[].answerText string Текст ответа. У вопроса с выбором варианта пустой
data[].answers[].selectedOptions array Выбранные варианты. У текстового вопроса массив пустой
data[].answers[].selectedOptions[].id number Идентификатор варианта
data[].answers[].selectedOptions[].text string Текст варианта
data[].answers[].selectedOptions[].value number Числовое значение варианта, по нему считается rate
data[].ratingScale array Шкала оценки этапа
data[].ratingScale[].value number Значение шкалы
data[].ratingScale[].label string Подпись значения
meta.nextCursor object | null Курсор следующей страницы. null — записей больше нет
meta.nextCursor.id number Значение для параметра afterCursorId следующего запроса

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

Завершённая карточка: заполнены текстовые ответы и рейтинговый вопрос, rate выведен из значения выбранного варианта.

JSON 
{
  "success": true,
  "data": [
    {
      "id": 4,
      "campaignId": 1,
      "campaignStageId": 5,
      "stageType": "managersReview",
      "revieweeUserId": 42,
      "revieweeUserName": "Мария Иванова",
      "reviewerUserId": 7,
      "reviewerUserName": "Иван Петров",
      "managerUserId": 7,
      "managerUserName": "Иван Петров",
      "status": "completed",
      "rate": 4,
      "comment": "",
      "answers": [
        {
          "questionId": 15,
          "questionTitle": "Ключевые результаты и выполнение целей",
          "questionDescription": "",
          "questionType": "3",
          "questionTypeLabel": "Текстовый ответ",
          "isRating": false,
          "answerText": "Закрыл цели квартала",
          "selectedOptions": []
        },
        {
          "questionId": 21,
          "questionTitle": "Итоговая оценка",
          "questionDescription": "",
          "questionType": "1",
          "questionTypeLabel": "Одиночный выбор",
          "isRating": true,
          "answerText": "",
          "selectedOptions": [
            { "id": 18, "text": "Выше ожиданий", "value": 4 }
          ]
        }
      ],
      "ratingScale": [
        { "value": 1, "label": "Значительно ниже ожиданий" },
        { "value": 2, "label": "Ниже ожиданий" },
        { "value": 3, "label": "Соответствует ожиданиям" },
        { "value": 4, "label": "Выше ожиданий" },
        { "value": 5, "label": "Значительно выше ожиданий" }
      ]
    }
  ],
  "meta": { "nextCursor": null }
}

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

400 — не передан обязательный параметр:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`campaignId` is required and must be a positive integer"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Не передан campaignId либо значение campaignId, revieweeUserId или 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, revieweeUserId, limit и afterCursorId, остальные отбрасывает без ошибки: запрос с опечаткой в имени параметра отвечает 200 и несуженным списком.

Только карточки подчинённых, которых оцениваете вы. Метод отдаёт карточки, где владелец ключа записан в reviewerUserId. Оценки, которые ставят ему самому, в ответ не попадают. Пустой массив data означает, что оценивать в этой кампании ему некого.

Фильтр по оцениваемому не проверяет, существует ли сотрудник. Значение revieweeUserId, по которому у владельца ключа нет карточки, даёт 200 с пустым data, а не отказ.

Хэш состояния карточки метод не возвращает. Значение expectedStateHash для оптимистичной блокировки приходит только в ответе на запись, поэтому первый вызов POST /v1/performan/review/manager/answers по карточке идёт без него.

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