Для AI-агентов: markdown этой страницы — /docs-content/tasks.md индекс документации — /llms.txt
Задачи: канбан, «Мой план» и план дня
Стадии канбана рабочей группы и личного «Моего плана», перенос задач между стадиями с порядком и чтение плана дня. Сами задачи читаются и меняются в разделе Задачи.
Скоуп: task | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key
Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок
У задачи три независимых места, и у каждого свой способ чтения:
| Что | Чей | Как задаётся | Как читается |
|---|---|---|---|
| Канбан группы | общий для всех участников группы | entityId — ID группы |
поле stageId задачи, GET /v1/tasks/stages/:entityId |
| «Мой план» | личный канбан владельца ключа | entityId равен 0 |
фильтр filter[stagesId] в списке задач |
| План дня | личный список владельца ключа на день | вручную в виджете рабочего дня | GET /v1/tasks/day-plan |
Перенос по «Моему плану» не меняет stageId задачи в группе, а план дня не связан ни с одной из досок.
Быстрый старт
Прочитать стадии «Моего плана» владельца ключа:
curl "https://vibecode.bitrix24.tech/v1/tasks/stages/0" \
-H "X-Api-Key: YOUR_API_KEY"
{
"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.
Полный пример: новая стадия и перенос задач
Сценарий добавляет в канбан группы стадию, переносит на неё две задачи в нужном порядке, читает доску и убирает стадию. Подставьте ID своей группы и двух её задач.
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. Её нельзя удалить, а смена первой стадии закрепляет задачи без стадии за прежней первой. Подробности — на страницах изменения и удаления стадии.
Справочник эндпоинтов
| Метод | Путь | Bitrix24 метод | Описание |
|---|---|---|---|
| GET | /v1/tasks/stages/:entityId |
task.stages.get | Стадии канбана группы или «Моего плана» |
| POST | /v1/tasks/stages/:entityId |
task.stages.add | Создать стадию |
| PATCH | /v1/task-stages/:stageId |
task.stages.update | Изменить стадию |
| DELETE | /v1/task-stages/:stageId |
task.stages.delete | Удалить пустую стадию |
| POST | /v1/tasks/:taskId/move-stage |
task.stages.movetask | Перенести задачу с порядком |
| GET | /v1/tasks/stages/:entityId/can-move |
task.stages.canmovetask | Право сортировать канбан группы |
| GET | /v1/tasks/day-plan |
task.planner.getlist | План дня владельца ключа |
Стадию задачи в канбане группы меняет и обновление задачи полем 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 — Ошибки.