Для 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/561 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "На ревью", "color": "47D1E2" }'

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

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

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

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

Ответ не содержит саму колонку: метод Битрикс24 не сообщает, какому спринту она принадлежит, поэтому перечитать её без лишнего запроса нельзя. Актуальные значения — список этапов.

Ошибки

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

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

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

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

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