Перформанс-ревью

Чтение данных раздела «Перформанс ревью» Битрикс24: кампании оценки, карточки самооценки и оценки коллег, вопросы и карточки менеджерского этапа. Один метод записи сохраняет черновик ответа менеджера или завершает оценку.

Скоуп: performan | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Доступность раздела

Раздел доступен не на каждом портале: нужен и модуль «Перформанс ревью», и включённая для портала поверхность. Порталу, которому раздел не включён, все шесть адресов отвечают 404 ROUTE_NOT_FOUND — тем же ответом, что и любой несуществующий адрес, — и в спецификации GET /v1/openapi.json такого портала этих путей нет. Если раздел включён, а модуля на портале нет, ответ тоже 404, но с кодом ENTITY_NOT_FOUND и сообщением Битрикс24 «Метод performan.review.campaign.list не найден». Скоуп performan по той же причине не выдаётся ключу по умолчанию: он появляется в списке прав только у портала, где раздел включён.

Ключ Коворка получает право на месте: первый запрос ключом без скоупа performan отвечает 409 PERFORMAN_SCOPE_JUST_GRANTED и выдаёт скоуп, повторный тот же запрос проходит. Выдача срабатывает не всегда: ключу нужны действующий вебхук и портал, а список прав ключа не должен быть зафиксирован владельцем. Не сработала выдача — ответ 403 SCOPE_DENIED, и право добавляет владелец ключа в кабинете. Ключу в режиме только для чтения право так не достаётся ни при каких условиях: выдача скоупа сама по себе запись.

Как устроено перформанс-ревью

Кампания — это цикл оценки с датами начала и окончания. Внутри кампании идут этапы: самооценка, оценка коллегами, менеджерский этап. На каждом этапе у сотрудника есть карточка, в контракте Битрикс24 — relation: кто кого оценивает, в каком статусе, с какими ответами и итоговой оценкой.

Вопросы задаются на уровне этапа кампании, а не карточки. Поэтому список вопросов менеджерского этапа читается отдельным методом, а ответы приходят внутри карточки.

Каждый список ограничен вызывающим сотрудником. Методы отдают его кампании, его карточки и те менеджерские связи, где он оценивающий. Пустой ответ означает «у этого сотрудника ничего нет», а не «на портале ничего нет». Администратор портала здесь дополнительных прав не получает.

Постраничная навигация

Списки обходятся курсором, а не смещением. Параметр limit задаёт размер страницы, максимум 200, по умолчанию 50. Значение meta.nextCursor.id из ответа передаётся в параметр afterCursorId следующего запроса. Когда meta.nextCursor приходит со значением null, записей больше нет.

Параметра offset у этих методов нет, общего количества записей они не возвращают.

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

Кампании, в которых участвует владелец ключа:

curl "https://vibecode.bitrix24.tech/v1/performan/review/campaigns" \
  -H "X-Api-Key: YOUR_API_KEY"

Ответ содержит массив кампаний в data и курсор следующей страницы в meta.nextCursor:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Оценка за третий квартал",
      "status": "created",
      "startDate": "2026-09-01T12:29:34+00:00",
      "endDate": "2026-10-31T12:29:34+00:00",
      "createdAt": "2026-09-01T12:29:34+00:00"
    }
  ],
  "meta": { "nextCursor": null }
}

Полный пример

Менеджер сохраняет черновик оценки подчинённого: находит кампанию, берёт свою карточку по сотруднику, читает вопросы этапа и записывает текстовый ответ.

BASE='https://vibecode.bitrix24.tech/v1'
KEY='YOUR_API_KEY'

# 1. Кампании сотрудника → берём идентификатор первой
CAMPAIGN_ID=$(curl -s "$BASE/performan/review/campaigns?limit=1" \
  -H "X-Api-Key: $KEY" | jq -r '.data[0].id')

# 2. Вопросы менеджерского этапа этой кампании
curl -s "$BASE/performan/review/manager/questions?campaignId=$CAMPAIGN_ID" \
  -H "X-Api-Key: $KEY" | jq '.data[] | {id, title, type, required}'

# 3. Карточка менеджерского ревью по конкретному сотруднику
RELATION_ID=$(curl -s "$BASE/performan/review/manager/reviews?campaignId=$CAMPAIGN_ID&revieweeUserId=42" \
  -H "X-Api-Key: $KEY" | jq -r '.data[0].id')

# 4. Черновик ответа на текстовый вопрос. Статус карточки остаётся new
curl -s -X POST "$BASE/performan/review/manager/answers" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"relationId\":$RELATION_ID,\"answers\":[{\"questionId\":15,\"answerText\":\"Закрыл цели квартала\"}]}" \
  | jq '{status: .data.status, stateHash: .data.stateHash}'

Значение stateHash из шага 4 передаётся в поле expectedStateHash следующей записи по этой карточке. Ни один метод чтения его не возвращает, поэтому первый вызов записи всегда идёт без него.

Справочник эндпоинтов

Ограничения раздела

Ответить на вопрос с выбором варианта через API нельзя. Идентификаторы вариантов не отдаёт ни один метод чтения: список вопросов приходит без вариантов, а в карточке в поле answers[].selectedOptions попадают только уже выбранные. Пока вариант не выбран в интерфейсе Битрикс24, его идентификатор взять неоткуда. Из-за этого через API нельзя заполнить обязательный вопрос с итоговой оценкой, а значит и завершить менеджерскую оценку.

Модуль установлен не на каждом портале. Если модуля «Перформанс ревью» на портале нет, вызов возвращает 404 ENTITY_NOT_FOUND с сообщением «Метод performan.review.campaign.list не найден». Это признак отсутствия модуля, а не ошибка интеграции. Порталу, которому раздел не включён вовсе, ответ приходит раньше и другой — 404 ROUTE_NOT_FOUND, как на несуществующий адрес.

Коды ошибок

Ошибки раздела

Системные ошибки

Полный список общих ошибок API — Ошибки. Подробная политика по чтениям и записям — Что безопасно повторять.

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

• Операции перформанс-ревью
• Оргструктура
• Сотрудники
• Ошибки