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

`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 — личный ключ

```bash
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 не сообщает, какому спринту она принадлежит, поэтому перечитать её без лишнего запроса нельзя. Актуальные значения — [список этапов](/docs/scrum/stages/list).

## Ошибки

| 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 — [Ошибки](/docs/errors).

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

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

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

- [Список этапов](/docs/scrum/stages/list)
- [Создать этап](/docs/scrum/stages/create)
- [Этапы Scrum-канбана](/docs/scrum/stages)