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

Чтение данных раздела «Перформанс ревью» Битрикс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` у этих методов нет, общего количества записей они не возвращают.

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

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

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

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

```json
{
  "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 }
}
```

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

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

```bash
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` следующей записи по этой карточке. Ни один метод чтения его не возвращает, поэтому первый вызов записи всегда идёт без него.

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| GET | [`/v1/performan/review/campaigns`](/docs/performan/campaigns) | performan.review.campaign.list | Кампании, в которых участвует сотрудник |
| GET | [`/v1/performan/review/self-reviews`](/docs/performan/self-reviews) | performan.review.selfreview.list | Карточки самооценки по кампании |
| GET | [`/v1/performan/review/peer-reviews`](/docs/performan/peer-reviews) | performan.review.peer.list | Карточки оценки коллегами по кампании |
| GET | [`/v1/performan/review/manager/questions`](/docs/performan/manager-questions) | performan.review.manager.questions.list | Вопросы менеджерского этапа кампании |
| GET | [`/v1/performan/review/manager/reviews`](/docs/performan/manager-reviews) | performan.review.manager.review.list | Карточки менеджерского ревью, где сотрудник оценивающий |
| POST | [`/v1/performan/review/manager/answers`](/docs/performan/manager-answer) | performan.review.manager.answer.send | Черновик ответа менеджера или завершение оценки |

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

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

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

## Коды ошибок

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

| HTTP | Код | Когда |
|------|-----|-------|
| 400 | `INVALID_PARAMS` | Параметр запроса не прошёл проверку на стороне API: `campaignId`, `revieweeUserId`, `limit`, `afterCursorId`, `relationId` или структура тела записи |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе. Так отвечает запись по чужой карточке и по несуществующей, а также вызов ключом, у которого на портале нет права `performan` |
| 404 | `ROUTE_NOT_FOUND` | Раздел «Перформанс ревью» порталу не включён. Ответ неотличим от ответа на любой несуществующий адрес |
| 404 | `ENTITY_NOT_FOUND` | Раздел включён, но модуля «Перформанс ревью» на портале нет: Битрикс24 отвечает «Метод `performan.review.*` не найден» |
| 409 | `PERFORMAN_SCOPE_JUST_GRANTED` | Ключу Коворка выдан скоуп `performan` этим же запросом. Повторите тот же запрос — он пройдёт |
| 409 | `PERFORMAN_STATE_CONFLICT` | Карточка изменилась с момента чтения — переданный `expectedStateHash` устарел. Перечитайте карточку и повторите запись со свежим значением |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос: неизвестный вопрос, незаполненные обязательные ответы при завершении оценки. Причина — в `error.message`, машинный код Битрикс24 — в `error.b24Code`, разбор по полям — в массиве `error.validation` |

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

| HTTP | Код | Когда | Повтор |
|------|-----|-------|--------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | нет |
| 401 | `TOKEN_MISSING` | У ключа нет токенов портала. Ключ OAuth-приложения требует заголовок `Authorization: Bearer` | нет |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `performan` | нет |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме только для чтения вызвал метод записи | нет |
| 429 | `RATE_LIMITED` | Превышена частота запросов на стороне Битрикс24 | да, с задержкой |
| 429 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | Очередь запросов портала переполнена или запрос не дождался очереди. Заголовок `Retry-After` подсказывает задержку | да, после `Retry-After` |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил за отведённое время | чтение — да, запись — только после перечитывания карточки |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен; исход вызова неизвестен | чтение — да, запись — только после проверки состояния |

Полный список общих ошибок API — [Ошибки](/docs/errors). Подробная политика по чтениям и записям — [Что безопасно повторять](/docs/errors/retry-safety).

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

- [Операции перформанс-ревью](/docs/performan/endpoints)
- [Оргструктура](/docs/humanresources)
- [Сотрудники](/docs/entities/users)
- [Ошибки](/docs/errors)