# Потоки и задачи потоков

Девять маршрутов `/v1/tasks/flows` вызывают одноимённые методы `tasks.flow.*` через REST Bitrix24. Нужен API-ключ со scope `task` (или `tasks`). Чтение доступно READONLY-ключу; создание, изменение, удаление и переключение активности требуют права записи.

`GET /v1/tasks/flows`

`POST /v1/tasks/flows`

`GET /v1/tasks/flows/:flowId`

`PATCH /v1/tasks/flows/:flowId`

`DELETE /v1/tasks/flows/:flowId`

`POST /v1/tasks/flows/:flowId/activate`

`GET /v1/tasks/flows/:flowId/tasks/completed`

`GET /v1/tasks/flows/:flowId/tasks/pending`

`GET /v1/tasks/flows/:flowId/tasks/progress`

| HTTP | Маршрут | Метод Bitrix24 | Передаваемые параметры |
| --- | --- | --- | --- |
| `GET` | `/v1/tasks/flows` | `tasks.flow.Flow.list` | `select`, `filter`, `order`, `group`, `start` из query |
| `POST` | `/v1/tasks/flows` | `tasks.flow.Flow.create` | `flowData`, необязательный `analyticsParams` из JSON-тела |
| `GET` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.get` | `flowId` |
| `PATCH` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.update` | `flowData` с `id` из пути, необязательный `analyticsParams` |
| `DELETE` | `/v1/tasks/flows/:flowId` | `tasks.flow.Flow.delete` | `flowData: { id: flowId }` |
| `POST` | `/v1/tasks/flows/:flowId/activate` | `tasks.flow.Flow.activate` | `flowId` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/completed?days=7` | `tasks.flow.Task.Completed.list` | `flowData: { id: flowId }`, `ago: { days: 7 }`, необязательный `start` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/pending` | `tasks.flow.Task.Pending.list` | `flowData: { id: flowId }`, необязательный `start` |
| `GET` | `/v1/tasks/flows/:flowId/tasks/progress` | `tasks.flow.Task.Progress.list` | `flowData: { id: flowId }`, необязательный `start` |

`flowId` — положительное целое число. Для создания и обновления передавайте объект `flowData` с полями [FlowDto](https://apidocs.bitrix24.com/api-reference/tasks/flow/tasks-flow-flow-create.html): например, `name`, `plannedCompletionTime`, `distributionType`, `responsibleList`. `PATCH` берёт идентификатор из пути; указанный в теле `flowData.id` должен ему совпадать. `activate` **переключает** текущее состояние, а не устанавливает заданное значение. Повторный вызов переключит его снова.

В `GET /v1/tasks/flows` массивы `select` и `group`, объекты `filter` и `order` передаются как JSON-строки query-параметров. Пример: `?select=%5B%22ID%22%2C%22NAME%22%5D&filter=%7B%22ACTIVE%22%3A%22Y%22%7D&start=50`. Эти структуры проходят в Bitrix24 без преобразования имён полей. `start` — нативное смещение REST-пагинации. Вайбкод делает один вызов и не объединяет страницы. `completed` требует неотрицательное `days`; оно передаётся как `ago.days`. Три списка раздельны: Битрикс24 сам определяет статус, сортировку и возвращает `{ tasks, totalCount }`.

Успешный ответ имеет форму `{ "success": true, "data": <result Bitrix24> }`. `Flow.list` возвращает массив, `Flow.get/create/update` — объект, `Flow.delete` — `{ "deleted": true }`, `Flow.activate` — `true`; список задач возвращает `{ "tasks": [...], "totalCount": N }`. Пустой и `null` результат не подменяются. Фактические поля объектов определяет Битрикс24.

Неверный путь, query или тело даёт `400 INVALID_PARAMS`; неверный или отсутствующий ключ — `401`; нехватка scope и попытка записи READONLY-ключом — `403`. Отказы Bitrix24 проходят через общий обработчик `/v1`: `422 BITRIX_ERROR`, `429 RATE_LIMITED`, `502 BITRIX_UNAVAILABLE`, `503 BITRIX_TIMEOUT`.