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

Обновить этап

PATCH /v1/scrum/stages/:stageId

Переименовывает, перекрашивает и переставляет колонку. Частичное обновление — передавайте только то, что меняется.

Адрес без спринта в пути: Битрикс24 опознаёт колонку по одному stageId.

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

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

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

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

Нужно хотя бы одно поле. Поле sprintId отклоняется.

Примеры

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/scrum/stages/641 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "На ревью", "color": "47D1E2" }'

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/scrum/stages/641 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "На ревью", "color": "47D1E2" }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/stages/641', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'На ревью', color: '47D1E2' }),
})

const { data } = await res.json()
console.log(data.updated)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/stages/641', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'На ревью', color: '47D1E2' }),
})

const { data } = await res.json()
console.log(data.updated)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном обновлении
Полеdata.updated Типboolean ОписаниеВсегда true в успешном ответе

Ответ не содержит саму колонку. Актуальные значения — список этапов.

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

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

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

404 — этапа нет либо он в недоступном скрам-проекте:

JSON 
{
  "success": false,
  "error": {
    "code": "STAGE_NOT_FOUND_OR_NO_ACCESS",
    "message": "Stage 999999 does not exist, or it belongs to a scrum project you cannot access."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеПустое тело, stageId не положительное целое, передан sprintId или значение не прошло проверку
HTTP404 КодSTAGE_NOT_FOUND_OR_NO_ACCESS ОписаниеЭтапа не существует либо он в скрам-проекте, к которому нет доступа
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа task
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает только на чтение
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет настроенных токенов

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

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

  • STAGE_NOT_FOUND_OR_NO_ACCESS объединяет две причины намеренно. Битрикс24 отвечает на «этапа нет» и «этап есть, но он не ваш» одинаково, различить их невозможно. Отдельный код для второго случая подтверждал бы существование чужой колонки.
  • Перенос в другой спринт не выставлен. Битрикс24 такой перенос умеет, но колонка при этом молча исчезает с живой доски. Создайте колонку в нужном спринте.

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