# Задачи

Управление задачами портала: создание, чтение, обновление, удаление, фильтрация, агрегация. Задача — единица работы с ответственным, постановщиком, сроком и статусом. У одной задачи могут быть комментарии и записи учёта времени — это отдельные вложенные ресурсы.

Битрикс24 API: `tasks.task.*`
Скоуп: `tasks`

## Операции

- [Создать задачу](./tasks/create.md) — `POST /v1/tasks`
- [Список задач](./tasks/list.md) — `GET /v1/tasks`
- [Получить задачу](./tasks/get.md) — `GET /v1/tasks/:id`
- [Обновить задачу](./tasks/update.md) — `PATCH /v1/tasks/:id`
- [Удалить задачу](./tasks/delete.md) — `DELETE /v1/tasks/:id`
- [Поиск задач](./tasks/search.md) — `POST /v1/tasks/search`
- [Поля задачи](./tasks/fields.md) — `GET /v1/tasks/fields`
- [Агрегация задач](./tasks/aggregate.md) — `POST /v1/tasks/aggregate`
- [Добавить в избранное](./tasks/favorite.md) — `POST /v1/tasks/:taskId/favorite`
- [Убрать из избранного](./tasks/unfavorite.md) — `DELETE /v1/tasks/:taskId/favorite`
- [Закрепить задачу](./tasks/pin.md) — `POST /v1/tasks/:taskId/pin`
- [Открепить задачу](./tasks/unpin.md) — `DELETE /v1/tasks/:taskId/pin`

У задачи есть вложенные ресурсы со своими CRUD-операциями: [Комментарии задач](./task-comments.md) (`/v1/tasks/:taskId/comments`), [Учёт времени задач](./tasks/time.md) (`/v1/tasks/:taskId/time`) и [Чат задачи](./tasks/chat.md) (`GET /v1/tasks/:taskId/chat/messages`). Скрам-размещение задачи (бэклог/спринт, эпик, story points) — отдельный раздел [Scrum API](/docs/scrum).

История изменений задачи и текущие стадии канбана доступны отдельными эндпоинтами для чтения: [История изменений задачи](/docs/task-history) (`GET /v1/tasks/:taskId/history`) и [Стадии канбана задач](/docs/task-stages) (`GET /v1/tasks/stages/:entityId`).

## Ключевые поля

| Поле | Описание |
|------|---------|
| `title` | Название задачи |
| `description` | Текст задачи (поддерживает BB-код, флаг `descriptionInBbcode`) |
| `responsibleId` | Ответственный. Список сотрудников: `GET /v1/users` |
| `createdBy` | Постановщик. По умолчанию — пользователь ключа. Можно передать и при создании, и при обновлении, в пределах прав пользователя Битрикс24. Список сотрудников: `GET /v1/users` |
| `status` | Статус задачи (число). Расшифровка значений: `GET /v1/tasks/fields` → `fields.status.enum` |
| `priority` | Приоритет (число). Расшифровка значений: `GET /v1/tasks/fields` → `fields.priority.enum` |
| `deadline` | Крайний срок (ISO 8601) |
| `groupId` | Рабочая группа. Список: `GET /v1/workgroups` |

Полный список полей — [`GET /v1/tasks/fields`](./tasks/fields.md).

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

1. **Минимум для создания:** `title` и `responsibleId`. Если ответственный не указан, портал возвращает ошибку «Не указан исполнитель».
2. **Статус и приоритет — числовые коды**, а не строки. Полная таблица соответствий приходит в ответе `GET /v1/tasks/fields` в поле `fields.status.enum` / `fields.priority.enum`. Например, `status: 2` — задача ждёт выполнения, `status: 5` — завершена.
3. **Поле `status` в ответе и отбор `filter[status]` — разные величины.** В ответе `status` — фактический статус задачи, всегда `1..7`, и в списке, и в карточке. Отбор `filter[status]` идёт по виртуальной оси Битрикс24: `-1` — просроченные, `-2` — непросмотренные, `-3` — почти просроченные. Каждой задаче ось присваивает ровно одно значение, поэтому просроченная задача с `status: 2` под условие `filter[status]=2` не попадает, а перебор `filter[status]` по значениям `1..7` возвращает не все задачи портала. Виртуальное значение приходит отдельным полем `subStatus` и только в [списке](./tasks/list.md) — карточка `GET /v1/tasks/:id` его не возвращает. Для отбора и сортировки по фактическому статусу служит имя `realStatus`: оно работает в `filter` и `sort`, ключа `realStatus` в ответе нет. Рецепты по сценариям:
   - «Активные без просроченных, непросмотренных и почти просроченных»: `?filter[status][]=2&filter[status][]=3&filter[status][]=4`.
   - «Активные включая просроченные»: `?filter[realStatus][]=2&filter[realStatus][]=3&filter[realStatus][]=4`.
   - «Только просроченные»: `?filter[status]=-1`.
   - «Все задачи по статусам»: перебирать `filter[realStatus]` от `1` до `7` — сумма совпадает с общим числом задач.
4. **Числа приходят числами.** Поля-идентификаторы `id`, `responsibleId`, `createdBy`, `groupId` и числовые перечисления `status`, `priority` приходят числами JSON — `"id": 289`, `"status": 2`. Приводить их через `Number(...)` не нужно. Строкой остаётся `subStatus`, а признаки «да/нет» приходят значениями `true` и `false`.
5. **Даты ответа — UTC.** Поля `createdDate`, `changedDate`, `closedDate`, `deadline` и остальные даты задачи приходят в UTC с суффиксом `Z` — `2026-05-12T08:46:12.000Z`. Часовой пояс портала на ответ не влияет, поэтому календарный день считайте после перевода в нужный пояс, а не срезом первых десяти символов строки. В запросе дату можно передавать со смещением — разбор такого значения описан в [обновлении задачи](./tasks/update.md).
6. **Пользователи внутри задачи.** Поля `creator` и `responsible` приходят встроенно как объекты вида `{ id, name, link, icon, workPosition }` — отдельный запрос на профили не нужен.
7. **`accomplices` и `auditors` — массивы строковых идентификаторов** пользователей (соисполнители и наблюдатели). Если задача только что создана и в ней нет соисполнителей и наблюдателей, поля приходят пустыми массивами.

## Типичный сценарий

1. Найти ответственного: [`GET /v1/users`](/docs/entities/users) (или фильтрованный поиск с нужным именем).
2. Создать задачу: [`POST /v1/tasks`](./tasks/create.md) с `title` и `responsibleId`.
3. Дополнить детали: [`PATCH /v1/tasks/:id`](./tasks/update.md) — `deadline`, `priority`, `description`, `auditors`.
4. Зафиксировать прогресс — комментарий: [`POST /v1/tasks/:taskId/comments`](./task-comments/create.md).
5. Учесть время: [`POST /v1/tasks/:taskId/time`](./tasks/time/create.md).
6. Закрыть задачу: [`PATCH /v1/tasks/:id`](./tasks/update.md) → `status: 5`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Разбиение по временны́м окнам для больших выборок | `POST /v1/tasks/search` с `autoWindow: true` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Комментарии задач](./task-comments.md)
- [Учёт времени задач](./tasks/time.md)
- [Чек-лист задачи](./tasks/checklist.md)
- [Связи задач](./tasks/dependencies.md)
- [История изменений задачи](/docs/task-history)
- [Стадии канбана задач](/docs/task-stages)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)