## Создать этап

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

```bash
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-приложение

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

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

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

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

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