Для 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/23/stages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "На проверке", "type": "WORK", "sort": 250 }'

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

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/sprints/23/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)

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

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

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном создании, HTTP-статус 201
Полеdata.id Типnumber ОписаниеID созданной колонки
Полеdata.name Типstring ОписаниеНазвание колонки
Полеdata.sort Типnumber ОписаниеПорядок колонки
Полеdata.type Типstring ОписаниеNEW, WORK или FINISH
Полеdata.sprintId Типnumber ОписаниеID спринта из пути запроса
Полеdata.color Типstring ОписаниеШесть шестнадцатеричных символов без #. Если color не передан — 00C4FB

Если перечитать колонку не удалось, data содержит только id — сама колонка при этом создана.

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

Цвет в запросе не передан, поэтому в ответе значение по умолчанию:

JSON 
{
  "success": true,
  "data": {
    "id": 641,
    "name": "На проверке",
    "sort": 250,
    "type": "WORK",
    "sprintId": 23,
    "color": "00C4FB"
  }
}

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

404 — спринта с таким ID нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Sprint not found"
  }
}

Ошибки

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

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

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

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

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