## Разместить или переместить задачу в скраме

`PATCH /v1/scrum/tasks/:taskId`

Размещает задачу в скраме и перемещает её между бэклогом, спринтом и эпиком, задаёт стори-поинты и порядок сортировки. Передавайте только изменяемые поля.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `taskId` | number | да | ID задачи (path-параметр). Источник: [`GET /v1/tasks`](/docs/entities/tasks/list) |

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

Хотя бы одно поле обязательно.

| Поле | Тип | Описание |
|------|-----|---------|
| `epicId` | number | Привязка к эпику. `0` — отвязать от эпика. Источник: [`GET /v1/scrum/epics`](/docs/scrum/epics/list) |
| `entityId` | number | ID бэклога или спринта. Определяется автоматически — передавайте явно только чтобы положить задачу в конкретный спринт |
| `storyPoints` | string \| number | Стори-поинты, например `"3"` или `"0.5"`. Пустая строка очищает |
| `sort` | number | Позиция в списке |
| `sortFloat` | number | Позиция в списке. Приоритетнее `sort` |
| `modifiedBy` | number | ID автора изменения. Источник: [`GET /v1/users`](/docs/entities/users/list). `createdBy` размещения не изменяется |

## Примеры

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

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/scrum/tasks/59 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "epicId": 11, "storyPoints": "3" }'
```

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

```bash
curl -X PATCH https://vibecode.bitrix24.tech/v1/scrum/tasks/59 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "epicId": 11, "storyPoints": "3" }'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/tasks/59', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ epicId: 11, storyPoints: '3' }),
})
const { data } = await res.json()
console.log('Размещение:', data)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/scrum/tasks/59', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ epicId: 11, storyPoints: '3' }),
})
const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.entityId` | number | ID бэклога или спринта, в котором лежит задача |
| `data.epicId` | number | ID эпика. `0` — задача не привязана к эпику |
| `data.storyPoints` | string | Стори-поинты, например `"3"`. Пустая строка — не заданы |
| `data.sort` | number | Позиция в списке |
| `data.sortFloat` | number | Позиция в списке. Приоритетнее `sort` |
| `data.createdBy` | number | ID автора размещения |
| `data.modifiedBy` | number | ID автора последнего изменения |

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

```json
{
  "success": true,
  "data": {
    "entityId": 1,
    "storyPoints": "3",
    "epicId": 11,
    "sort": 255,
    "sortFloat": 512,
    "createdBy": 1,
    "modifiedBy": 1
  }
}
```

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

400 — у задачи нет рабочей группы, авторазмещение в бэклог невозможно:

```json
{
  "success": false,
  "error": {
    "code": "TASK_NOT_IN_GROUP",
    "message": "Task 289 has no workgroup (GROUP_ID), so it cannot be placed in scrum. Move the task into a scrum project first (PATCH /v1/tasks/:id { \"groupId\": N }) or pass entityId explicitly."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Пустое тело, нечисловое поле или попытка задать `createdBy` |
| 400 | `TASK_NOT_IN_GROUP` | У задачи нет рабочей группы — авторазмещение в бэклог невозможно. Перенесите задачу в скрам-проект через `PATCH /v1/tasks/:id { "groupId": N }` или передайте `entityId` явно |
| 422 | `BACKLOG_NOT_RESOLVED` | Рабочая группа задачи — не скрам-проект, бэклог не найден |
| 422 | `BITRIX_ERROR` | Задача не найдена или прочая ошибка Битрикс24, например `groupId` эпика и задачи не совпадают |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `task` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме «только чтение» |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- **Бэклог определяется автоматически.** Если `entityId` опущен и задача ещё не в скраме, API находит бэклог скрам-проекта задачи по её рабочей группе и кладёт задачу туда. Задача, уже размещённая в скраме, сохраняет текущий бэклог или спринт.
- **Доступ.** Размещать задачи может только пользователь Битрикс24, от имени которого работает ключ, с доступом к скрам-проекту задачи. Иначе портал вернёт `422 BITRIX_ERROR` с сообщением «Access denied».

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

- [Получить размещение задачи в скраме](/docs/scrum/tasks/get)
- [Список эпиков](/docs/scrum/epics/list)
- [Scrum](/docs/scrum)
- [Задачи](/docs/entities/tasks)