# Чек-лист задачи

Пункты чек-листа задачи — вложенный ресурс задачи. У каждого пункта есть название, статус выполнения, признак важности, порядок сортировки, участники и (опционально) родительский пункт для вложенных чек-листов. Базовый путь — `/v1/tasks/:taskId/checklist`. Все операции адресуются идентификатором задачи `:taskId`.

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

> **Почему отдельный ресурс.** Битрикс24 **не принимает** поле `CHECKLIST` внутри `POST /v1/tasks` (`tasks.task.add`) — чек-лист нельзя создать вместе с задачей. Единственный поддерживаемый способ управлять пунктами — это методы семейства `task.checklistitem.*`, которые и оборачивает данный ресурс. Сначала создайте задачу, затем добавляйте пункты по одному.

## Операции

- [Список пунктов](./checklist/list.md) — `GET /v1/tasks/:taskId/checklist`
- [Получить пункт](./checklist/get.md) — `GET /v1/tasks/:taskId/checklist/:itemId`
- [Добавить пункт](./checklist/create.md) — `POST /v1/tasks/:taskId/checklist`
- [Обновить пункт](./checklist/update.md) — `PATCH /v1/tasks/:taskId/checklist/:itemId`
- [Удалить пункт](./checklist/delete.md) — `DELETE /v1/tasks/:taskId/checklist/:itemId`
- [Отметить выполненным](./checklist/complete.md) — `POST /v1/tasks/:taskId/checklist/:itemId/complete`
- [Вернуть в работу](./checklist/renew.md) — `POST /v1/tasks/:taskId/checklist/:itemId/renew`

## Поля пункта

| Поле | Тип | Только чтение | Описание |
|------|-----|:---:|---------|
| `title` | string | | Текст пункта. **Обязателен при создании.** Если `parentId = 0`, то `title` — название нового чек-листа |
| `sortIndex` | integer | | Индекс сортировки. Чем меньше значение, тем выше пункт в списке |
| `isComplete` | boolean / `Y`,`N` | | Статус выполнения. При записи принимает `true`/`false` или `"Y"`/`"N"`. В ответе — `"Y"`/`"N"` |
| `isImportant` | boolean / `Y`,`N` | | Признак важности. Формат — как у `isComplete` |
| `parentId` | integer | | ID родительского пункта для вложенных чек-листов. **`0` создаёт новый чек-лист** в задаче |
| `members` | object (запрос) / array (ответ) | | Участники пункта — разный формат на запись и на чтение, см. «Известные особенности» ниже |
| `id` | string | да | ID пункта |
| `taskId` | string | да | ID родительской задачи |
| `createdBy` | string | да | Автор пункта |
| `toggledBy` | string | да | Кто последним менял статус выполнения |
| `toggledDate` | string | да | Когда статус менялся последний раз |
| `attachments` | array | да | Прикреплённые файлы (заполняются в UI Битрикс24) |

## Известные особенности

- **Отсутствие задачи проверяется не на всех операциях.** Список пунктов и получение одного пункта отвечают `422`, когда задачи `:taskId` на портале нет. Обновление, отметка выполнения, возврат в работу и удаление в этом случае отвечают успехом и ничего не меняют, поэтому успешный статус этих четырёх операций не подтверждает, что задача и пункт существуют.
- **Регистр и типы в ответе.** Ответы приходят в camelCase (`id`, `taskId`, `sortIndex`, `isComplete`). Числовые значения Битрикс24 сериализует **строками** (`"id": "477"`, `"sortIndex": "2"`) — для арифметики приводите через `Number(value)`. Флаги `isComplete` / `isImportant` — это строки `"Y"` / `"N"`, а не булевы значения.
- **`members` — разные форматы на запись и на чтение.** При создании/обновлении пункта `members` — объект вида `{ "<userId>": { "type": "A" | "U" } }` (`A` — соисполнитель, `U` — наблюдатель, список сотрудников — [`GET /v1/users`](/docs/entities/users)). В ответе (список, получение) `members` — **массив** обогащённых объектов участников: `[{ "id", "type", "name", "personalPhoto", "personalGender", "image", "isCollaber" }]`. Код, который читает участников из ответа, не должен ожидать формат запроса.
- **Пункт без указанного `parentId` может лечь в существующий чек-лист автоматически.** Если в задаче уже есть чек-лист-контейнер (пункт с `parentId: 0`), Битрикс24 подставляет его пунктам, созданным без явного `parentId`, вместо того чтобы оставить их на верхнем уровне.

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

1. Создать задачу: [`POST /v1/tasks`](../tasks/create.md).
2. (Опционально) создать чек-лист-контейнер: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) с `parentId: 0`.
3. Добавить пункты: [`POST /v1/tasks/:taskId/checklist`](./checklist/create.md) (по одному).
4. Отметить пункт выполненным: [`POST /v1/tasks/:taskId/checklist/:itemId/complete`](./checklist/complete.md).
5. Посмотреть прогресс: [`GET /v1/tasks/:taskId/checklist`](./checklist/list.md).

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

- [Задачи](../tasks.md)
- [Учёт времени](./time.md)
- [Комментарии задач](/docs/entities/task-comments)
- [Сотрудники](/docs/entities/users)
- [Лимиты и оптимизация](/docs/optimization)