Связи задач

Связи задачи — это её предшественники: задачи, от которых она зависит. В карточке Битрикс24 они показаны блоком «Связанные задачи». Ресурс только для чтения.

Битрикс24 API: tasks.task.get (поле RELATED_TASKS) Скоуп: task

Операции

• GET /v1/tasks/:taskId/dependencies — связи одной задачи
• POST /v1/tasks/dependencies/bulk — связи до 50 задач одним вызовом

Что нужно знать до интеграции

Отдаются только предшественники. Обратного ребра — «кто зависит от этой задачи» — REST Битрикс24 не отдаёт ни одним методом. Дашборд, которому нужен граф целиком, строит обратные рёбра сам, инверсией собранных пар. Ради этого и существует пакетный вызов: собрать пары по сотне задач одним запросом дешевле, чем сотней.

Тип связи не читается. У связи в Битрикс24 есть тип (например, «финиш-старт»), но ни один метод REST его не возвращает. Поэтому поле типа здесь не публикуется вовсе: пустое или угаданное значение в контракте хуже, чем его отсутствие.

Связи, созданные «гантт-методом», не видны. Битрикс24 хранит связи в двух местах. Штатные — те, что записаны при создании или изменении задачи, — читаются. Связи, добавленные методом task.dependence.add, физически существуют, но не возвращаются ни одним методом чтения, включая task.item.getdependson. Отличить «связей нет» от «связи есть, но в невидимом хранилище» невозможно — ни через это API, ни через сырой REST.

В списке задач связей нет. GET /v1/tasks и POST /v1/tasks/search поля связей не отдают: Битрикс24 молча выбрасывает его из ответа списка при любом select. Отсюда отдельный ресурс.

Задача может ссылаться сама на себя. Если это так, самопетля приезжает как есть — это факт из портала, а не ошибка ответа. Дашборд, строящий граф инверсией пар, должен быть к ней готов.

Связи одной задачи — `GET /v1/tasks/:taskId/dependencies`

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/tasks/4029/dependencies"

{
  "success": true,
  "data": [
    { "id": 4023, "title": "Подготовить смету" },
    { "id": 4027, "title": "Согласовать бюджет" }
  ],
  "meta": { "total": 2, "hasMore": false, "direction": "predecessors", "source": "RELATED_TASKS" }
}

Записи отсортированы по id по возрастанию. title может быть null — тогда название задачи портал не отдал. meta.total всегда равен длине data.

Транзиентный отказ портала — превышение лимита запросов, недоступность Битрикс24, протухший токен — приходит своим кодом, а не подменяется на TASK_NOT_FOUND.

Пакетный вызов — `POST /v1/tasks/dependencies/bulk`

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"taskIds": [4029, 4033, 4041]}' \
  "https://vibecode.bitrix24.tech/v1/tasks/dependencies/bulk"

{
  "success": true,
  "data": {
    "results": { "4029": [ { "id": 4023, "title": "Подготовить смету" } ], "4033": [] },
    "errors":  { "4041": { "code": "TASK_NOT_FOUND", "message": "Task not found." } }
  },
  "meta": { "requested": 3, "succeeded": 2, "failed": 1, "direction": "predecessors", "source": "RELATED_TASKS" }
}

taskIds принимает и числа, и десятичные строки: ["4029"] эквивалентно [4029].

Ответ приходит с кодом 200 даже тогда, когда отказали все подвызовы. Частичный отказ — это смысл пакетного вызова, поэтому проверять надо errors, а не только results.

Дубли схлопываются молча, и meta.requested считает уникальные идентификаторы. Поэтому requested всегда равен succeeded + failed. А вот позиция в сообщении об ошибке INVALID_PARAMS считается по исходному массиву — это две разные системы координат в одном ответе, и обе названы намеренно.

Коды в errors — закрытый набор:

Отказы всего запроса:

Пакетный вызов ограничен по частоте на портал, а не на ключ: два ключа одного портала делят одно ведро, и разогнать выдачу вторым ключом не получится. При превышении приходит 429, актуальное число и Retry-After — в теле ответа.

Заголовок Content-Type: application/json обязателен, если тело непустое. Пустое тело и запрос без заголовка обрабатываются штатно и отвечают INVALID_REQUEST.

Запись связей

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

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

• Задачи
• Чек-лист задачи
• Учёт времени задач