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

Создать этап

POST /v1/scrum/sprints/:sprintId/stages

Добавляет колонку на доску спринта. sprintId берётся из пути; в теле запроса он отклоняется.

Битрикс24 возвращает только идентификатор, поэтому платформа перечитывает созданную колонку и отдаёт её целиком — вместе со значениями, которые Битрикс24 подставил по умолчанию.

Параметры пути

Параметр Тип Обяз. Описание
sprintId number да ID спринта. Получить: GET /v1/scrum/sprints?groupId=N

Поля запроса (body)

Поле Тип Обяз. Описание
name string да Название колонки. До 255 символов
type string нет NEW, WORK или FINISH. По умолчанию WORK
sort number нет Порядок колонки. По умолчанию 100
color string нет Шесть шестнадцатеричных символов, например "00C4FB". Ведущий # принимается и срезается

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/scrum/sprints/11/stages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "На проверке",
    "type": "WORK",
    "sort": 250,
    "color": "FFAA00"
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/scrum/sprints/11/stages \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "На проверке", "type": "WORK" }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/sprints/11/stages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'На проверке', type: 'WORK', sort: 250 }),
})

const { data } = await res.json()
console.log('Stage ID:', data.id)

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

JSON 
{
    "success": true,
    "data": {
        "id": 561,
        "name": "На проверке",
        "type": "WORK",
        "sort": 250,
        "color": "FFAA00",
        "sprintId": 11
    }
}

Если перечитывание не удалось, ответ вырождается до { "id": 561 } — сама колонка при этом создана.

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Не передан name; имя длиннее 255 символов; type вне набора; цвет длиннее шести символов; sprintId в теле
404 ENTITY_NOT_FOUND Спринта с таким ID не существует
422 BITRIX_ERROR Битрикс24 вернул ошибку, которую платформа не отнесла ни к одному из остальных кодов этой таблицы; отказ по правам сюда НЕ попадает — он приходит как 403 BITRIX_ACCESS_DENIED
403 BITRIX_ACCESS_DENIED У пользователя Битрикс24, от имени которого работает ключ, нет доступа к скрам-проекту спринта
403 SCOPE_DENIED Ключу не хватает скоупа task
403 WRITE_BLOCKED_READONLY_KEY Ключ работает только на чтение
401 TOKEN_MISSING У ключа нет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Проверки строже, чем у Битрикс24, и намеренно. Портал принимает имя длиннее 255 символов, цвет длиннее шести и любое значение type, отвечает успехом, но сохраняет обрезанное или подменённое значение. Платформа отказывает заранее, чтобы вы не получили колонку, которую не заказывали.
  • Добавление в завершённый спринт разрешено — Битрикс24 это не запрещает.

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