## Список пунктов чек-листа

`GET /v1/tasks/:taskId/checklist`

Возвращает все пункты чек-листа задачи, включая вложенные (дочерние) пункты.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `taskId` (path) | integer | да | ID задачи |
| `sort` (query) | string | нет | Сортировка в формате `поле:направление`, например `sortIndex:asc`. Поля: `id`, `parentId`, `createdBy`, `title`, `sortIndex`, `isComplete`, `isImportant`, `toggledBy`, `toggledDate`. Направление — `asc` / `desc` (по умолчанию `asc`). Без параметра Битрикс24 сортирует по `id` по убыванию |
| `start` (query) | integer | нет | Смещение в выборке. Битрикс24 отдаёт страницами по 50 пунктов — для следующей страницы передайте `start=50`, затем `100` и так далее |

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  "https://vibecode.bitrix24.tech/v1/tasks/3943/checklist?sort=sortIndex:asc",
  {
    headers: {
      "X-Api-Key": "YOUR_APP_KEY",
      "Authorization": "Bearer USER_SESSION_TOKEN",
    },
  }
);
const { data } = await res.json();
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив пунктов чек-листа |
| `data[].id` | string | ID пункта |
| `data[].taskId` | string | ID родительской задачи |
| `data[].parentId` | integer / string | ID родительского пункта. `0` — пункт верхнего уровня (сам является чек-листом) |
| `data[].title` | string | Текст пункта |
| `data[].sortIndex` | string | Индекс сортировки |
| `data[].isComplete` | string | Статус выполнения — `"Y"` / `"N"` |
| `data[].isImportant` | string | Признак важности — `"Y"` / `"N"` |
| `data[].createdBy` | string | Автор пункта |
| `data[].toggledBy` | string \| null | Кто последним менял статус выполнения |
| `data[].toggledDate` | string | Когда статус менялся последний раз. Пустая строка, если не менялся |
| `data[].members` | array | Участники пункта — объекты `{ id, type, name, personalPhoto, personalGender, image, isCollaber }` |
| `data[].attachments` | array | Прикреплённые файлы |
| `meta.total` | number | Общее число пунктов в выборке |

## Пример ответа

```json
{
  "success": true,
  "data": [
    {
      "id": "211",
      "taskId": "3943",
      "parentId": 0,
      "createdBy": "1317",
      "title": "Документы",
      "sortIndex": "1",
      "isComplete": "N",
      "isImportant": "N",
      "toggledBy": null,
      "toggledDate": "",
      "members": [],
      "attachments": []
    },
    {
      "id": "213",
      "taskId": "3943",
      "parentId": "211",
      "createdBy": "1317",
      "title": "Собрать и проверить документы",
      "sortIndex": "100",
      "isComplete": "N",
      "isImportant": "Y",
      "toggledBy": null,
      "toggledDate": "",
      "members": [
        {
          "id": "1317",
          "type": "A",
          "name": "Иван Петров",
          "personalPhoto": "35959",
          "personalGender": "",
          "image": "https://example.bitrix24.ru/...",
          "isCollaber": false
        }
      ],
      "attachments": []
    }
  ],
  "meta": { "total": 2 }
}
```

## Пример ответа при ошибке

`422` — задача не найдена или недоступна:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "TASKS_ERROR_EXCEPTION_#8; Action failed; 8/TE/ACTION_FAILED_TO_BE_PROCESSED",
    "b24Code": "ERROR_CORE"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `taskId` не положительное целое, либо неизвестное поле сортировки |
| 422 | `BITRIX_ERROR` | Задача с указанным `taskId` не существует или недоступна ключу — Битрикс24 бросил исключение. Существующая задача без пунктов отвечает `200` с пустым массивом |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `task` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

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

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

- **`parentId: 0` — пункт верхнего уровня, сам являющийся чек-листом.** Дочерние пункты ссылаются на его `id` через свой `parentId`.
- **Числовые значения и флаги — строки.** `id`, `taskId`, `sortIndex` приходят строками. `isComplete` / `isImportant` — строками `"Y"`/`"N"`, не булевыми значениями.

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

- [Получить пункт](./get.md)
- [Добавить пункт](./create.md)
- [Задачи](/docs/entities/tasks)