Идентификаторы

Каждый идентификатор ресурса — это строка вида <prefix>_<value>. Префикс указывает тип ресурса, поэтому передача идентификатора неверного типа отклоняется с ошибкой 422 validation_error (invalid_request), а не приводит к тихому обращению не к тому ресурсу.

Префиксы

Префикс	Ресурс	Пример
`task_`	задача	`task_6594a1b2c3d4e5f6a7b8c9d0`
`subtask_`	сабтаск	составной — см. ниже
`time_log_`	time log	составной — см. ниже
`event_`	запланированное событие	`event_6594a1b2c3d4e5f6a7b8c9e0`
`proj_`	проект	`proj_6594a1b2c3d4e5f6a7b8c9a0`
`user_`	участник воркспейса	`user_6594a1b2c3d4e5f6a7b8c9b0`
`tag_`	тег	`tag_6594a1b2c3d4e5f6a7b8c9c0`
`task_status_`	статус задачи	`task_status_6594a1b2c3d4e5f6a7b8c9d2`
`task_type_`	тип задачи	`task_type_6594a1b2c3d4e5f6a7b8c9d3`
`event_type_`	тип события	`event_type_6594a1b2c3d4e5f6a7b8c9d4`
`proj_status_`	статус проекта	`proj_status_6594a1b2c3d4e5f6a7b8c9d5`
`cf_`	кастомное поле	`cf_6594a1b2c3d4e5f6a7b8c9d6`
`cf_option_`	вариант кастомного поля	`cf_option_6594a1b2c3d4e5f6a7b8c9d7`
`attachment_`	вложение	`attachment_6594a1b2c3d4e5f6a7b8c9d8`
`chat_message_`	сообщение чата	`chat_message_6594a1b2c3d4e5f6a7b8c9d9`

Большинство ресурсов используют простую форму <prefix>_<value>. Дополнительные части добавляют две вещи: сабтаски/time logs (которые кодируют свою родительскую задачу) и вхождения рекуррентных задач (которые добавляют дату).

Составные идентификаторы: сабтаски и time logs

Сабтаск или time log всегда адресуется вместе со своей родительской задачей, поэтому его идентификатор несёт оба — сначала дочерний элемент, затем родительскую задачу:

subtask_<child>_<parent task>
time_log_<child>_<parent task>

Для задачи task_6594a1b2c3d4e5f6a7b8c9d0:

Ресурс	Пример идентификатора
сабтаск	`subtask_6594a1b2c3d4e5f6a7b8c9d1_6594a1b2c3d4e5f6a7b8c9d0`
time log	`time_log_6594a1b2c3d4e5f6a7b8c9d2_6594a1b2c3d4e5f6a7b8c9d0`

Хвостовая часть 6594a1b2c3d4e5f6a7b8c9d0 — это значение родительской задачи. Это по-прежнему единая непрозрачная строка — вы передаёте её целиком как один идентификатор, а не собираете из частей.

Рекуррентные задачи и события

Рекуррентная серия имеет обычный идентификатор — task_<value> или event_<value> — который адресует всю серию (прочитать её, изменить правило, удалить каждое вхождение).

Отдельное вхождение этой серии адресуется добавлением времени начала вхождения (UTC, YYYYMMDDTHHMMSSZ):

task_<series>_<date>          e.g. task_6594a1b2c3d4e5f6a7b8c9d0_20260113T090000Z
event_<series>_<date>         e.g. event_6594a1b2c3d4e5f6a7b8c9e0_20260113T090000Z

Когда вы редактируете это вхождение и все последующие, API может вернуть идентификатор серии, помеченный символом R перед датой — это отдельная серия «отсюда и далее», по-прежнему непрозрачная:

task_6594a1b2c3d4e5f6a7b8c9d0_R20260113T090000Z

Всё, что принадлежит вхождению, несёт тот же суффикс с датой после составной части — поэтому сабтаск или time log вхождения выглядит так:

subtask_6594a1b2c3d4e5f6a7b8c9d1_6594a1b2c3d4e5f6a7b8c9d0_20260113T090000Z
time_log_6594a1b2c3d4e5f6a7b8c9d2_6594a1b2c3d4e5f6a7b8c9d0_20260113T090000Z

Какой идентификатор использовать

Вы хотите…	Использовать
Прочитать/обновить/удалить всю серию	обычный идентификатор серии — `task_<series>`
Действовать на одно вхождение	идентификатор вхождения — `task_<series>_<date>`
Действовать на одно вхождение и все последующие	`R`-помеченный идентификатор, который вернул API

Почему это важно на практике

Поскольку вы считаете каждый идентификатор непрозрачным, одни и те же эндпоинты работают независимо от формы. GET /tasks/{id} принимает обычный идентификатор задачи, идентификатор вхождения или R-помеченный идентификатор серии — вам не нужно делать особую обработку формата и не нужно знать, какой именно у вас на руках. Читайте идентификаторы из ответов, храните их целиком и отправляйте обратно ровно в том виде, в каком получили.