# Scrum: эпики и размещение задач

Управление скрамом в проектах Битрикс24: создание и переименование эпиков, привязка задач к эпикам, размещение в бэклоге, story points. Работает поверх обычных [Задач](/docs/entities/tasks) — сначала задача создаётся через `POST /v1/tasks`, затем размещается в скраме.

**Скоуп:** `task` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

## Разделы документации

- [Эпики скрама](/docs/scrum/epics) — создание, чтение, переименование и перекраска эпиков
- [Размещение задач в скраме](/docs/scrum/tasks) — чтение и изменение скрам-строки задачи: бэклог или спринт, эпик, story points

## Быстрый старт

### 1. Создать эпик

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/scrum/epics" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Папки в чатах", "groupId": 7 }'
```

### 2. Привязать задачу к эпику

Задача уже создана через [`POST /v1/tasks`](/docs/entities/tasks/create) и находится в скрам-проекте `groupId`. Привязка автоматически помещает её в бэклог проекта:

```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": 87 }'
```

## Полный пример: зеркалирование внешнего трекера

Создать эпик, завести задачу в скрам-проекте, привязать её к эпику и проверить размещение. Бэклог определяется автоматически.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'
const GROUP_ID = 7 // скрам-проект, список: GET /v1/workgroups

// ── 1. Создать эпик ─────────────────────────────────────────────
const epicRes = await fetch(`${BASE}/scrum/epics`, {
  method: 'POST',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Папки в чатах', groupId: GROUP_ID })
})
const { data: epic } = await epicRes.json()
console.log(`Эпик создан, ID: ${epic.id}`)

// ── 2. Создать задачу в том же скрам-проекте ────────────────────
const taskRes = await fetch(`${BASE}/tasks`, {
  method: 'POST',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Сверстать список папок', groupId: GROUP_ID, responsibleId: 1 })
})
const { data: task } = await taskRes.json()
console.log(`Задача создана, ID: ${task.id}`)

// ── 3. Привязать задачу к эпику ─────────────────────────────────
//     entityId опущен → задача автоматически попадает в бэклог проекта
await fetch(`${BASE}/scrum/tasks/${task.id}`, {
  method: 'PATCH',
  headers: { 'X-Api-Key': VIBE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ epicId: epic.id, storyPoints: '3' })
})

// ── 4. Проверить фактическое размещение ─────────────────────────
const placeRes = await fetch(`${BASE}/scrum/tasks/${task.id}`, {
  headers: { 'X-Api-Key': VIBE_KEY }
})
const { data: placement } = await placeRes.json()
console.log('Размещение:', placement)
```

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| POST | [`/v1/scrum/epics`](/docs/scrum/epics/create) | tasks.api.scrum.epic.add | Создать эпик |
| GET | [`/v1/scrum/epics`](/docs/scrum/epics/list) | tasks.api.scrum.epic.list | Список эпиков |
| GET | [`/v1/scrum/epics/:id`](/docs/scrum/epics/get) | tasks.api.scrum.epic.get | Получить эпик |
| PATCH | [`/v1/scrum/epics/:id`](/docs/scrum/epics/update) | tasks.api.scrum.epic.update | Переименовать / изменить эпик |
| GET | [`/v1/scrum/tasks/:taskId`](/docs/scrum/tasks/get) | tasks.api.scrum.task.get | Получить размещение задачи в скраме |
| PATCH | [`/v1/scrum/tasks/:taskId`](/docs/scrum/tasks/update) | tasks.api.scrum.task.update | Разместить / переместить задачу |

## Коды ошибок

| HTTP | Код | Причина |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Нарушена валидация полей запроса |
| 400 | `TASK_NOT_IN_GROUP` | Задача без рабочей группы — авторазмещение в бэклог невозможно |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `task` |
| 422 | `BACKLOG_NOT_RESOLVED` | Группа задачи — не скрам-проект, бэклог не найден |
| 422 | `BITRIX_ERROR` | Задача не найдена или не размещена в скраме, прочие ошибки Битрикс24 |

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

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

- [Задачи](/docs/entities/tasks)
- [Чат задачи](/docs/entities/tasks/chat)
- [Рабочие группы](/docs/entities/workgroups)
- [Лимиты и оптимизация](/docs/optimization)