# Задачи: канбан, «Мой план» и план дня

Стадии канбана рабочей группы и личного «Моего плана», перенос задач между стадиями с порядком и чтение плана дня. Сами задачи читаются и меняются в разделе [Задачи](/docs/entities/tasks).

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

[Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример-новая-стадия-и-перенос-задач) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)

У задачи три независимых места, и у каждого свой способ чтения:

| Что | Чей | Как задаётся | Как читается |
|-----|-----|--------------|--------------|
| Канбан группы | общий для всех участников группы | `entityId` — ID группы | поле `stageId` задачи, [`GET /v1/tasks/stages/:entityId`](/docs/task-stages/list) |
| «Мой план» | личный канбан владельца ключа | `entityId` равен `0` | фильтр `filter[stagesId]` в [списке задач](/docs/entities/tasks/list) |
| План дня | личный список владельца ключа на день | вручную в виджете рабочего дня | [`GET /v1/tasks/day-plan`](/docs/tasks/day-plan) |

Перенос по «Моему плану» не меняет `stageId` задачи в группе, а план дня не связан ни с одной из досок.

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

Прочитать стадии «Моего плана» владельца ключа:

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/stages/0" \
  -H "X-Api-Key: YOUR_API_KEY"
```

```json
{
  "success": true,
  "data": [
    {
      "id": 489,
      "title": "Не спланированы",
      "sort": 100,
      "color": "00C4FB",
      "systemType": "NEW",
      "entityId": 1317,
      "entityType": "U"
    },
    {
      "id": 491,
      "title": "Сделаю на неделе",
      "sort": 200,
      "color": "47D1E2",
      "systemType": null,
      "entityId": 1317,
      "entityType": "U"
    }
  ]
}
```

Для канбана группы вместо `0` подставьте ID группы из [`GET /v1/workgroups`](/docs/entities/workgroups/list).

## Полный пример: новая стадия и перенос задач

Сценарий добавляет в канбан группы стадию, переносит на неё две задачи в нужном порядке, читает доску и убирает стадию. Подставьте ID своей группы и двух её задач.

```javascript
const VIBE_URL = 'https://vibecode.bitrix24.tech'
const VIBE_API_KEY = process.env.VIBE_API_KEY
const GROUP_ID = 155    // ID рабочей группы, GET /v1/workgroups
const TASK_ID = 4127    // переносимая задача этой группы
const ANCHOR_ID = 4125  // задача, перед которой она встанет

async function api(method, path, body) {
  const res = await fetch(`${VIBE_URL}/v1${path}`, {
    method,
    headers: { 'X-Api-Key': VIBE_API_KEY, 'Content-Type': 'application/json' },
    body: body ? JSON.stringify(body) : undefined,
  })
  const json = res.status === 204 ? null : await res.json()
  if (!res.ok) throw new Error(`${method} ${path}: ${json?.error?.code} ${json?.error?.message}`)
  return json?.data
}

// Шаг 1. Убедиться, что пользователь ключа может сортировать канбан группы.
const { canMove } = await api('GET', `/tasks/stages/${GROUP_ID}/can-move`)
if (!canMove) throw new Error('Нет права переносить задачи в канбане этой группы')

// Шаг 2. Добавить стадию в конец канбана.
const stage = await api('POST', `/tasks/stages/${GROUP_ID}`, { title: 'На согласовании', color: 'FF8800' })
console.log('Новая стадия:', stage.id, stage.title)

// Шаг 3. Перенести задачи на новую стадию. Задача для порядка должна стоять
// на той же доске, поэтому сначала переносим её, потом ставим вторую перед ней.
await api('POST', `/tasks/${ANCHOR_ID}/move-stage`, { stageId: stage.id })
await api('POST', `/tasks/${TASK_ID}/move-stage`, { stageId: stage.id, beforeTaskId: ANCHOR_ID })

// Шаг 4. Перечитать доску: стадии приходят по возрастанию sort.
const stages = await api('GET', `/tasks/stages/${GROUP_ID}`)
for (const s of stages) console.log(s.sort, s.id, s.title, s.systemType ?? '')

// Шаг 5. Убрать стадию. Удаляется только пустая, поэтому задачи сначала
// уводим на первую стадию доски.
const first = stages[0]
await api('POST', `/tasks/${TASK_ID}/move-stage`, { stageId: first.id })
await api('POST', `/tasks/${ANCHOR_ID}/move-stage`, { stageId: first.id })
await api('DELETE', `/task-stages/${stage.id}`)
console.log('Стадия удалена')
```

Первая стадия доски — стадия по умолчанию с `systemType: NEW`. Её нельзя удалить, а смена первой стадии закрепляет задачи без стадии за прежней первой. Подробности — на страницах [изменения](/docs/task-stages/update) и [удаления](/docs/task-stages/delete) стадии.

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| GET | [`/v1/tasks/stages/:entityId`](/docs/task-stages/list) | task.stages.get | Стадии канбана группы или «Моего плана» |
| POST | [`/v1/tasks/stages/:entityId`](/docs/tasks/stages) | task.stages.add | Создать стадию |
| PATCH | [`/v1/task-stages/:stageId`](/docs/task-stages/update) | task.stages.update | Изменить стадию |
| DELETE | [`/v1/task-stages/:stageId`](/docs/task-stages/delete) | task.stages.delete | Удалить пустую стадию |
| POST | [`/v1/tasks/:taskId/move-stage`](/docs/tasks/move-stage) | task.stages.movetask | Перенести задачу с порядком |
| GET | [`/v1/tasks/stages/:entityId/can-move`](/docs/tasks/stages-can-move) | task.stages.canmovetask | Право сортировать канбан группы |
| GET | [`/v1/tasks/day-plan`](/docs/tasks/day-plan) | task.planner.getlist | План дня владельца ключа |

Стадию задачи в канбане группы меняет и [обновление задачи](/docs/entities/tasks/update) полем `stageId`, но без порядка и только в пределах группы задачи.

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

### Ошибки раздела

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Нарушена проверка параметров или тела. Условия перечислены на странице каждого метода |
| 404 | `ENTITY_NOT_FOUND` | Нет задачи или стадии с таким ID |
| 409 | `TASK_NOT_IN_PLAN` | Перенос по «Моему плану», а задачи в плане владельца ключа нет |
| 409 | `STAGE_NOT_EMPTY` | Удаление стадии, в которой есть задачи |
| 409 | `STAGE_IS_SYSTEM` | Удаление первой стадии доски |

### Системные ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `UNSUPPORTED_FILTER` | В запрос стадий передан `filter`: список стадий приходит целиком |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У ключа нет действующего токена Битрикс24 |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `task` или `tasks` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения вызвал создание, изменение, удаление или перенос |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя ключа нет прав на группу или задачу |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос или не подтвердил изменение |
| 502 | `BITRIX_ERROR` | Битрикс24 вернул ответ неожиданной структуры на проверку права или чтение плана дня |

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

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

- [Задачи](/docs/entities/tasks)
- [История изменений задачи](/docs/task-history)
- [Этапы Scrum-канбана](/docs/scrum/stages)
- [Рабочие группы](/docs/entities/workgroups)
- [Рабочий день](/docs/workday)