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

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

Битрикс24 API: tasks.api.scrum.epic.*, tasks.api.scrum.task.*, tasks.api.scrum.backlog.get Скоуп: task

#Эндпоинты

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

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

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,
    "description": "Зеркало эпика из внешнего трекера",
    "color": "#5eead4"
  }'

Ответ 201:

{
  "success": true,
  "data": {
    "id": 87,
    "groupId": 7,
    "name": "Папки в чатах",
    "description": "Зеркало эпика из внешнего трекера",
    "createdBy": 1,
    "modifiedBy": 1,
    "color": "#5eead4"
  }
}

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

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 }'

Ответ — фактическое размещение задачи после изменения (API перечитывает его, чтобы вы могли убедиться, что привязка применилась):

{
  "success": true,
  "data": { "entityId": 1, "epicId": 87, "storyPoints": "" }
}

#Поля эпика (POST / PATCH)

#Поля размещения задачи (PATCH /v1/scrum/tasks/:taskId)

#Что нужно знать перед работой

1. entityId резолвится автоматически. Если задача уже в скраме — её текущее размещение (бэклог или спринт) сохраняется. Если ещё нет — API сам находит бэклог скрам-проекта задачи и помещает её туда. Передавайте entityId явно только когда нужно положить задачу в конкретный спринт.
2. Задача должна быть в группе. Авторазмещение работает через groupId задачи. Задача без рабочей группы вернёт 400 TASK_NOT_IN_GROUP — сначала перенесите её в скрам-проект (PATCH /v1/tasks/:id { "groupId": N }) или передайте entityId явно.
3. Группа должна быть скрам-проектом. Для обычной (не-скрам) группы Битрикс24 не находит бэклог — API вернёт 422 BACKLOG_NOT_RESOLVED.
4. groupId эпика и задачи должны совпадать. Битрикс24 отклоняет привязку задачи к эпику из другого проекта.
5. PATCH возвращает фактическое размещение. Нативный метод Битрикс24 возвращает только true — API дополнительно перечитывает скрам-строку задачи, чтобы ответ был проверяемым (никаких «тихих» неуспехов).
6. Права. Создание эпиков и перемещение задач требуют членства B24-пользователя ключа в скрам-проекте с правом на создание задач.
7. Список эпиков пагинируется автоматически. GET /v1/scrum/epics возвращает до limit эпиков (по умолчанию 200, максимум 1000) — API сам докачивает страницы Битрикс24 по 50 записей.

#Типичный сценарий: зеркалирование внешнего трекера

1. Создать эпик: POST /v1/scrum/epics { name, groupId } → запомнить data.id.
2. Создать задачу: `POST /v1/tasks` { title, groupId, responsibleId, tags }.
3. Привязать к эпику: PATCH /v1/scrum/tasks/:taskId { epicId } — задача автоматически попадёт в бэклог проекта.
4. При переименовании эпика во внешнем трекере: PATCH /v1/scrum/epics/:id { name }.
5. Проверить размещение: GET /v1/scrum/tasks/:taskId.

#Ошибки

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

• Задачи — создание и обновление самих задач
• Чат задачи — чтение сообщений чата задачи
• Рабочие группы — источник groupId
• Лимиты и оптимизация — rate limits