Для 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 задачи в группе, а план дня не связан ни с одной из досок.

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

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

Terminal
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.

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

Сценарий добавляет в канбан группы стадию, переносит на неё две задачи в нужном порядке, читает доску и убирает стадию. Подставьте 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. Её нельзя удалить, а смена первой стадии закрепляет задачи без стадии за прежней первой. Подробности — на страницах изменения и удаления стадии.

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

Метод Путь 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 — Ошибки.

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