§ 7.2

Задачи

Получить, создать, изменить, выполнить и удалить задачу.

обновлено 22 сентября 202611 мин чтениятолько на тарифахКомандаБизнес

Задача — главный объект DoneBy. Через API её можно получить, создать, изменить, отметить выполненной, вернуть в работу и удалить. Для чтения нужен скоуп tasks:read, для изменений — tasks:write.

Объект задачи

ПолеТипОписание
idstringИдентификатор вида tsk_8Kd2Lq. Только чтение.
titlestringНазвание, до 500 символов. Обязательно при создании.
notesstring | nullОписание в Markdown, до 20 000 символов.
list_idstring | nullСписок. Если не указать при создании, задача попадёт во «Входящие» владельца токена.
section_idstring | nullРаздел внутри списка. Должен принадлежать тому же list_id.
parent_idstring | nullДля подзадачи — id родительской задачи. Задаётся только при создании.
due_datestring | nullДата срока: YYYY-MM-DD.
due_timestring | nullВремя срока: HH:MM. null — срок на весь день. Без due_date не задаётся.
timezonestringЧасовой пояс срока в формате IANA, например Europe/Moscow. По умолчанию — пояс пространства.
priorityinteger0 — без приоритета, 1 — P1 (самый высокий), 2 — P2, 3 — P3.
assignee_idsstring[]Исполнители — id участников из списка участников. Пустой массив — без исполнителя.
repeatstring | nullПравило повтора в стиле RRULE, например FREQ=WEEKLY;BYDAY=FR. См. ниже.
subtasksobject[]Краткие карточки подзадач: id, title, completed, due_date, assignee_ids. Только чтение. До 100 у задачи.
checklistobject[]Пункты чек-листа: id, text, checked. До 200 пунктов.
completedbooleanВыполнена ли задача. Только чтение — меняется методами /complete и /reopen.
completed_atstring | nullКогда задачу выполнили. ISO 8601, UTC.
created_atstringКогда задачу создали. ISO 8601, UTC.
updated_atstringКогда задачу меняли последний раз. По этому полю удобно синхронизироваться.
urlstringСсылка на задачу в веб-приложении.
Задача целиком
{
  "id": "tsk_8Kd2Lq",
  "title": "Подготовить отчёт за сентябрь",
  "notes": "Выручка по каталогу, возвраты, план на октябрь.",
  "list_id": "lst_Ka7Tp3",
  "section_id": "sec_Rp4Ze8",
  "parent_id": null,
  "due_date": "2026-09-30",
  "due_time": "15:00",
  "timezone": "Europe/Moscow",
  "priority": 2,
  "assignee_ids": ["usr_Ol3gD7"],
  "repeat": null,
  "subtasks": [
    {
      "id": "tsk_9Lm3Wr",
      "title": "Выгрузить продажи",
      "completed": true,
      "due_date": "2026-09-28",
      "assignee_ids": ["usr_Ol3gD7"]
    },
    {
      "id": "tsk_9Lm3Ws",
      "title": "Свести возвраты",
      "completed": false,
      "due_date": null,
      "assignee_ids": []
    }
  ],
  "checklist": [
    { "id": "chk_1Qa7", "text": "Сверить цифры с бухгалтерией", "checked": false },
    { "id": "chk_1Qa8", "text": "Отправить клиенту PDF", "checked": false }
  ],
  "completed": false,
  "completed_at": null,
  "created_at": "2026-09-14T07:12:40Z",
  "updated_at": "2026-09-16T10:05:11Z",
  "url": "https://doneby.app/app/list/lst_Ka7Tp3?task=tsk_8Kd2Lq"
}

Правило повтора

Поле repeat — строка вида КЛЮЧ=значение;КЛЮЧ=значение, похожая на RRULE из календарей. Поддерживаются FREQ (DAILY, WEEKLY, MONTHLY, YEARLY), INTERVAL, BYDAY, BYMONTHDAY, COUNT, UNTIL и FROM=COMPLETION — повтор от даты выполнения, а не по расписанию. Повтору нужен due_date: от него считается первое повторение.

СтрокаЧто означает
FREQ=DAILYКаждый день
FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FRПо будням
FREQ=WEEKLY;INTERVAL=2;BYDAY=MOКаждый второй понедельник
FREQ=MONTHLY;BYMONTHDAY=-1В последний день месяца
FREQ=MONTHLY;BYDAY=1MOВ первый понедельник месяца
FREQ=MONTHLY;COUNT=6Каждый месяц, шесть раз
FREQ=WEEKLY;FROM=COMPLETIONЧерез неделю после того, как выполнили предыдущую

Те же правила человеческим языком — в статье Правила повтора: примеры.

GET /tasks — список задач

Возвращает задачи, которые видит владелец токена, страницами по limit (см. пагинацию). Подзадачи тоже попадают в выдачу, если подходят под фильтр, — их легко узнать по parent_id.

ПараметрОписание
list_idТолько задачи из этого списка.
assignee_idЗадачи, где участник среди исполнителей. Значение me — владелец токена.
due_beforeСрок не позже указанного, включительно: 2026-09-30 или 2026-09-30T18:00:00+03:00.
due_afterСрок не раньше указанного, включительно. Формат тот же.
completedtrue — только выполненные, false — только открытые. Без параметра — все.
updated_sinceЗадачи, изменённые после метки времени (ISO 8601 с поясом). С этим параметром выдача сортируется по updated_at.
limit, cursorРазмер страницы (1–100, по умолчанию 50) и курсор следующей страницы.

По умолчанию задачи отсортированы по сроку (задачи без срока — в конце), затем по дате создания.

Мои открытые задачи со сроком до 20 сентября
curl -G https://doneby.app/api/v1/tasks \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  --data-urlencode "assignee_id=me" \
  --data-urlencode "completed=false" \
  --data-urlencode "due_before=2026-09-20" \
  -d limit=20
Ответ · поля сокращены
{
  "data": [
    {
      "id": "tsk_3Vn7Hs",
      "title": "Ревью PR: быстрые сроки в поле ввода",
      "list_id": "lst_R4m2Vx",
      "parent_id": null,
      "due_date": "2026-09-15",
      "due_time": "12:00",
      "timezone": "Europe/Moscow",
      "priority": 2,
      "assignee_ids": ["usr_Me0001", "usr_Ti4mB8"],
      "completed": false,
      "updated_at": "2026-09-14T16:41:09Z"
    },
    {
      "id": "tsk_6Pw0Ka",
      "title": "Обновить changelog и заметки к релизу",
      "list_id": "lst_R4m2Vx",
      "parent_id": null,
      "due_date": "2026-09-15",
      "due_time": "17:00",
      "timezone": "Europe/Moscow",
      "priority": 0,
      "assignee_ids": ["usr_Me0001"],
      "completed": false,
      "updated_at": "2026-09-12T09:03:27Z"
    }
  ],
  "next_cursor": null
}

Совет

Для синхронизации храните updated_at последней полученной задачи и в следующий раз запрашивайте updated_since — придут только изменения. Удалённые задачи так не увидеть: на них подпишитесь вебхуком task.deleted.

GET /tasks/{id} — одна задача

Возвращает задачу целиком, вместе с подзадачами и чек-листом. Если задачи нет или владелец токена её не видит, ответ — 404 not_found: API не различает эти случаи, чтобы не раскрывать чужие данные.

bash
curl https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
  -H "Authorization: Bearer $DONEBY_TOKEN"

POST /tasks — создать задачу

Обязательно только title. Остальные поля — как в объекте задачи, кроме полей только для чтения. Ответ — 201 Created и созданная задача. Передавайте Idempotency-Key, чтобы повтор запроса не создал дубль.

Запрос
curl -X POST https://doneby.app/api/v1/tasks \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c5d7a1e-9b0f-4f6e-8d3a-71c4e2b9f805" \
  -d '{
    "title": "Созвон по правкам карточек товара",
    "list_id": "lst_Ka7Tp3",
    "due_date": "2026-09-18",
    "due_time": "14:30",
    "timezone": "Europe/Moscow",
    "priority": 1,
    "assignee_ids": ["usr_Ol3gD7", "usr_Me0001"],
    "checklist": [
      { "text": "Собрать правки в один документ" },
      { "text": "Согласовать сроки переделки" }
    ]
  }'
Ответ · 201 Created
{
  "id": "tsk_4Gh8Np",
  "title": "Созвон по правкам карточек товара",
  "notes": null,
  "list_id": "lst_Ka7Tp3",
  "section_id": null,
  "parent_id": null,
  "due_date": "2026-09-18",
  "due_time": "14:30",
  "timezone": "Europe/Moscow",
  "priority": 1,
  "assignee_ids": ["usr_Ol3gD7", "usr_Me0001"],
  "repeat": null,
  "subtasks": [],
  "checklist": [
    { "id": "chk_7Tz2", "text": "Собрать правки в один документ", "checked": false },
    { "id": "chk_7Tz3", "text": "Согласовать сроки переделки", "checked": false }
  ],
  "completed": false,
  "completed_at": null,
  "created_at": "2026-09-15T08:20:14Z",
  "updated_at": "2026-09-15T08:20:14Z",
  "url": "https://doneby.app/app/list/lst_Ka7Tp3?task=tsk_4Gh8Np"
}

Важно

Быстрый ввод в API не разбирается: "title": "Отчёт пт 15:00 !1" создаст задачу ровно с таким названием. Срок, приоритет и список передавайте отдельными полями.

Подзадача

Подзадача — обычная задача с parent_id. Она живёт в списке родителя, поэтому list_id для неё не передаётся. Вложенность — один уровень: у подзадачи не может быть своих подзадач. Лимит — 100 подзадач у одной задачи.

bash
curl -X POST https://doneby.app/api/v1/tasks \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b3e6f9c-52a4-4d71-b8e0-9c1f7a2d4e36" \
  -d '{
    "title": "Свести возвраты",
    "parent_id": "tsk_8Kd2Lq",
    "due_date": "2026-09-29",
    "assignee_ids": ["usr_Ol3gD7"]
  }'

PATCH /tasks/{id} — изменить задачу

Меняет только переданные поля и возвращает задачу целиком. null очищает поле: "due_date": null снимает срок вместе со временем, "repeat": null — повтор. Если передать новый list_id без section_id, раздел сбросится.

checklist передаётся целиком: пункты с id сохраняются и обновляются, пункты без id добавляются, а пункты, которых нет в массиве, удаляются. Подзадачи через PATCH родителя не меняются — у каждой свой id и свой PATCH.

Перенести на 1 октября, на весь день, и добавить исполнителя
curl -X PATCH https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-10-01",
    "due_time": null,
    "priority": 1,
    "assignee_ids": ["usr_Ol3gD7", "usr_An9aK2"]
  }'
Что нужноТело запроса
Перенести срок{"due_date": "2026-10-01"}
Сделать срок на весь день{"due_time": null}
Снять срок{"due_date": null}
Убрать всех исполнителей{"assignee_ids": []}
Перенести в другой список{"list_id": "lst_R4m2Vx"}
Повторять каждую пятницу{"repeat": "FREQ=WEEKLY;BYDAY=FR"}
Отметить пункт чек-листа{"checklist": [{"id": "chk_1Qa7", "checked": true}, {"id": "chk_1Qa8"}]}

POST /tasks/{id}/complete — выполнить

Отмечает задачу выполненной, ставит completed_at и отправляет вебхук task.completed. Повторный вызов для уже выполненной задачи ничего не меняет и возвращает 200. Тело запроса не обязательно.

Открытые подзадачи остаются открытыми. Чтобы закрыть их вместе с родителем, передайте {"include_subtasks": true}.

bash
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/complete \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"include_subtasks": true}'

У повторяющейся задачи закрывается текущее повторение. В ответе задача остаётся открытой (completed: false), due_date переезжает на следующую дату по правилу, а completed_at хранит время последнего закрытого повторения.

Ответ для повторяющейся задачи · поля сокращены
{
  "id": "tsk_2Fd9Ue",
  "title": "Собрать дайджест обновлений",
  "repeat": "FREQ=WEEKLY;BYDAY=FR",
  "due_date": "2026-09-25",
  "due_time": "12:00",
  "completed": false,
  "completed_at": "2026-09-18T09:14:52Z"
}

POST /tasks/{id}/reopen — вернуть в работу

Снимает отметку: completed становится false, completed_at — null, уходит вебхук task.reopened. Срок не меняется: если он уже прошёл, задача сразу окажется просроченной — перенесите её через PATCH.

У повторяющейся задачи reopen не работает (422 unprocessable): следующее повторение уже назначено. Верните нужную дату через PATCH.

bash
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/reopen \
  -H "Authorization: Bearer $DONEBY_TOKEN"

DELETE /tasks/{id} — удалить

Удаляет задачу вместе с подзадачами, чек-листом и комментариями. Ответ — 204 No Content без тела, уходит вебхук task.deleted. Через API удаление необратимо.

bash
curl -X DELETE https://doneby.app/api/v1/tasks/tsk_8Kd2Lq \
  -H "Authorization: Bearer $DONEBY_TOKEN"

Важно

Если задача может понадобиться для истории или отчётов, не удаляйте её — выполните или перенесите в архивный список. Удалённую задачу не вернёт даже поддержка.

Комментарии

Комментарии читаются со скоупом comments:read и добавляются с comments:write — от имени владельца токена. GET /tasks/{id}/comments отдаёт их по времени, страницами, как все коллекции. Чтобы упомянуть участника, передайте его id в mentions: он получит уведомление так же, как при упоминании в приложении. Каждый новый комментарий отправляет вебхук comment.created.

Добавить комментарий
curl -X POST https://doneby.app/api/v1/tasks/tsk_8Kd2Lq/comments \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5e2b9d14-7c3a-4f80-a6d1-3b8e0f2c9a57" \
  -d '{
    "text": "Цифры сверили, отчёт можно отправлять.",
    "mentions": ["usr_Ol3gD7"]
  }'
Ответ · 201 Created
{
  "id": "cmt_4Rw8Yt",
  "task_id": "tsk_8Kd2Lq",
  "author_id": "usr_Me0001",
  "text": "Цифры сверили, отчёт можно отправлять.",
  "mentions": ["usr_Ol3gD7"],
  "created_at": "2026-09-29T11:42:08Z"
}

Ограничение

Комментарии через API не редактируются и не удаляются — это делается в приложении.

Типичные ошибки

ОтветКогда бывает
400 validation_errorНет title, дата в неверном формате, due_time без due_date, priority вне диапазона 0–3, метка времени без часового пояса.
403 forbiddenУ токена нет tasks:write, или роль владельца токена не позволяет менять задачи в этом списке.
404 not_foundЗадачи нет или владелец токена её не видит.
409 conflictIdempotency-Key уже использован с другим телом запроса.
422 unprocessableСписок в архиве, в списке уже 5 000 задач, исполнитель не состоит в списке, у подзадачи пытаются создать подзадачу.

Полный список кодов и что с ними делать — в разделе Коды ошибок.

см. также
Статья помогла?Отметьте галочкой — так мы понимаем, какие статьи дописать первыми.