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

Карточки оценки коллегами

GET /v1/performan/review/peer-reviews

Возвращает карточки этапа оценки коллегами по кампании, где владелец ключа выступает оценивающим. Параметр с идентификатором кампании обязателен, навигация по выдаче курсорная.

Параметры

Параметр Тип Обяз. По умолч. Описание
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/peer-reviews?campaignId=1&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/performan/review/peer-reviews?campaignId=1&limit=20" \
  -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/peer-reviews?campaignId=1&limit=20', {
  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) {
  console.log(card.id, card.revieweeUserName, card.status)
}

console.log(body.meta.nextCursor)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/performan/review/peer-reviews?campaignId=1&limit=20', {
  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 Идентификатор карточки
data[].campaignId number Кампания карточки. Список — GET /v1/performan/review/campaigns
data[].campaignStageId number Этап кампании, к которому относится карточка
data[].stageType string Тип этапа. У этого метода — peerReview
data[].revieweeUserId number Оцениваемый сотрудник. Карточка сотрудника — GET /v1/users/:id
data[].revieweeUserName string Имя оцениваемого сотрудника
data[].reviewerUserId number Оценивающий сотрудник. Карточка сотрудника — GET /v1/users/:id
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 Идентификатор вопроса
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 следующего запроса

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "campaignId": 1,
      "campaignStageId": 4,
      "stageType": "peerReview",
      "revieweeUserId": 42,
      "revieweeUserName": "Мария Иванова",
      "reviewerUserId": 7,
      "reviewerUserName": "Иван Петров",
      "managerUserId": 7,
      "managerUserName": "Иван Петров",
      "status": "new",
      "rate": 0,
      "comment": "",
      "answers": [],
      "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 или 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 сужает выдачу только у карточек менеджерского ревью — на остальных списках он молча отбрасывается.

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

Записи ответов на этом этапе через API нет. Раздел даёт метод записи только для менеджерского этапа — POST /v1/performan/review/manager/answers. Карточки оценки коллегами доступны на чтение.

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