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

Девять маршрутов /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: например, 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.