# Учёт времени задач

Записи о потраченном на задачу времени — вложенный ресурс задачи. У каждой записи есть длительность, автор, комментарий и время создания. Базовый путь — `/v1/tasks/:taskId/time`, эти операции требуют существующей задачи `:taskId` на портале. Записи со всех задач сразу отдаёт отдельный путь `/v1/task-time`.

Битрикс24 API: `task.elapseditem.*`
Скоуп: `task`

## Операции

- [Добавить запись](./time/create.md) — `POST /v1/tasks/:taskId/time`
- [Список записей](./time/list.md) — `GET /v1/tasks/:taskId/time`
- [Получить запись](./time/get.md) — `GET /v1/tasks/:taskId/time/:itemId`
- [Обновить запись](./time/update.md) — `PATCH /v1/tasks/:taskId/time/:itemId`
- [Удалить запись](./time/delete.md) — `DELETE /v1/tasks/:taskId/time/:itemId`
- [Список по всему порталу](./time/global-list.md) — `GET /v1/task-time`
- [Поля записи](./time/fields.md) — `GET /v1/task-time/fields`

## Ключевые поля

Эти же поля отдаёт программный справочник [`GET /v1/task-time/fields`](./time/fields.md) — тип, признак «только чтение», подпись и описание у каждого.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор записи |
| `taskId` | number | ID родительской задачи |
| `userId` | number | Автор. Список сотрудников: `GET /v1/users` |
| `seconds` | number | Длительность в секундах. Основное поле, задаётся при создании |
| `minutes` | number | Длительность в минутах, производное от `seconds`, заполняется системой |
| `commentText` | string | Комментарий к записи. Если комментарий пуст, приходит `""`, а не `null` |
| `source` | string | Источник: `2` — запись создана через REST API |
| `createdDate` | datetime | Дата создания записи |
| `dateStart`, `dateStop` | datetime | Начало и окончание учтённого интервала. Заполняются автоматически и через текущий API не редактируются |

## Что нужно знать перед работой

1. **Поля ответа — в camelCase.** Записи учёта времени возвращаются в camelCase — `id`, `taskId`, `userId`, `seconds`, `minutes`, `commentText`, `source`, `createdDate`, `dateStart`, `dateStop`, — как и комментарии задач и остальная часть API.
2. **Числовые значения приходят числами, `source` — строкой.** `id`, `taskId`, `userId`, `seconds` и `minutes` сериализуются числами — например `"seconds": 900`. Это верно во всех ответах — и в списках, и в карточке одной записи, — поэтому приводить их через `Number(value)` не нужно. Поле `source` остаётся строкой: `"source": "2"`.
3. **`seconds` — единственная единица измерения при записи.** Параметр `seconds` обязателен. Значение `minutes` система пересчитывает сама.
4. **Записи удаляются вместе с задачей.** Если родительская задача удалена ([`DELETE /v1/tasks/:id`](./delete.md)), её записи учёта времени становятся недоступны — отдельный `DELETE` для каждой не требуется. Попытка обратиться к ним по прежнему ID вернёт `422`.
5. **`dateStart` и `dateStop` через API не редактируются.** Их значения заполняются Битрикс24 автоматически в момент создания записи. Чтобы зафиксировать конкретный интервал, передавайте суммарное время через `seconds` в `POST` или `PATCH`. Битрикс24 систематически проставляет интервал примерно на час впереди `createdDate` — это его собственное автозаполнение, API Вайбкод даты не меняет.
6. **Список может показывать записи, недоступные карточке.** Списки — и глобальный, и по одной задаче — иногда возвращают чужие записи. Обращение к такой записи по её `itemId` отдаёт `422 ITEM_NOT_FOUND_OR_NOT_ACCESSIBLE`. Это рассогласование прав доступа на стороне Битрикс24.
7. **Справочник полей лежит на плоском пути.** Состав полей отдаёт `GET /v1/task-time/fields`. Вложенный `GET /v1/tasks/:taskId/time/fields` возвращает `400 WRONG_PATH` и называет в тексте ошибки правильный путь: схема одинакова для всех задач, поэтому она не повторяется под каждым `:taskId`. Запрос требует скоуп `task` и не обращается к Битрикс24.
8. **`userId` задаётся только при создании.** В `POST` его можно передать, в `PATCH` он возвращает `400 READONLY_FIELD` — Битрикс24 не умеет переносить запись на другого сотрудника. В справочнике полей это поле помечено `createOnly`.
9. **Имя поля в ответе и в теле запроса различается у комментария.** В ответе он приходит как `commentText`, а передаётся при записи как `comment`.

## Типичный сценарий

1. Найти или создать задачу: [`GET /v1/tasks`](./list.md) / [`POST /v1/tasks`](./create.md).
2. Добавить запись: [`POST /v1/tasks/:taskId/time`](./time/create.md) с `seconds` и при необходимости `comment` и `userId`.
3. Посмотреть историю учёта: [`GET /v1/tasks/:taskId/time`](./time/list.md).
4. Скорректировать длительность или комментарий: [`PATCH /v1/tasks/:taskId/time/:itemId`](./time/update.md).
5. Удалить ошибочную запись: [`DELETE /v1/tasks/:taskId/time/:itemId`](./time/delete.md).
6. Собрать отчёт за период по сотруднику, не перебирая задачи: [`GET /v1/task-time`](./time/global-list.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Количество записей на странице | 1..500, по умолчанию 50 |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Задачи](../tasks.md)
- [Комментарии задач](../task-comments.md)
- [Сотрудники](/docs/entities/users)
- [Лимиты и оптимизация](/docs/optimization)