## Поля записи учёта времени

`GET /v1/task-time/fields`

Возвращает справочник полей записи учёта времени. Схема одна на все задачи, поэтому путь плоский и идентификатор задачи в нём не участвует.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/task-time/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/task-time/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/task-time/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/task-time/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.fields` | object | Справочник полей записи. Ключ — имя поля в camelCase, значение — его описание |
| `data.fields.<имя>.type` | string | Тип значения поля: `number`, `string` или `datetime` |
| `data.fields.<имя>.readonly` | boolean | `true` — поле заполняется системой и на запись не принимается |
| `data.fields.<имя>.createOnly` | boolean | Присутствует у полей, которые принимаются только при создании записи. В запросе на обновление такое поле отклоняется с `400 READONLY_FIELD` |
| `data.fields.<имя>.label` | string | Короткое название поля |
| `data.fields.<имя>.description` | string | Пояснение к полю, включая имя ключа в теле запроса, если оно отличается от имени в ответе |

Справочник описывает десять полей:

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

## Пример ответа

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор",
        "description": "Идентификатор записи. Сериализуется числом."
      },
      "taskId": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор задачи",
        "description": "Числовой идентификатор родительской задачи. Берётся из пути запроса на вложенных маршрутах — в теле не задаётся."
      },
      "userId": {
        "type": "number",
        "readonly": false,
        "label": "Идентификатор автора",
        "description": "Числовой идентификатор сотрудника, на которого записано время, — из GET /v1/users. Необязателен при создании (по умолчанию — владелец ключа); в PATCH отклоняется с 400 READONLY_FIELD: Битрикс24 не умеет менять автора записи.",
        "createOnly": true
      },
      "seconds": {
        "type": "number",
        "readonly": false,
        "label": "Секунды",
        "description": "Учтённая длительность в секундах. Обязательна при создании, необязательна при обновлении. Ключ тела запроса: seconds."
      },
      "minutes": {
        "type": "number",
        "readonly": true,
        "label": "Минуты",
        "description": "Длительность в минутах, Битрикс24 считает её из seconds. Через это API только для чтения — маршрут Вайбкод её не отправляет."
      },
      "commentText": {
        "type": "string",
        "readonly": false,
        "label": "Комментарий",
        "description": "Комментарий к записи. При записи передавайте его как comment в теле — commentText это имя в ответе. Пустой комментарий приходит как \"\", а не null."
      },
      "source": {
        "type": "string",
        "readonly": true,
        "label": "Источник",
        "description": "Источник записи, проставляет Битрикс24: «2» — создана через REST API."
      },
      "createdDate": {
        "type": "datetime",
        "readonly": false,
        "label": "Дата создания",
        "description": "Дата создания, ISO 8601 со смещением портала (например 2026-05-13T16:15:41+03:00). Доступна для записи при создании и обновлении — передайте createdDate, чтобы поставить запись задним числом."
      },
      "dateStart": {
        "type": "datetime",
        "readonly": true,
        "label": "Начало интервала",
        "description": "Начало учтённого интервала, ISO 8601 со смещением портала. Заполняется Битрикс24 автоматически, через это API не редактируется."
      },
      "dateStop": {
        "type": "datetime",
        "readonly": true,
        "label": "Конец интервала",
        "description": "Конец учтённого интервала, ISO 8601 со смещением портала. Заполняется Битрикс24 автоматически, через это API не редактируется."
      }
    }
  }
}
```

## Пример ответа при ошибке

403 — нет скоупа:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'task' scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `WRONG_PATH` | Запрос отправлен на вложенный путь `GET /v1/tasks/:taskId/time/fields`. Правильный плоский путь назван в тексте ошибки |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `task` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Справочник не зависит от портала.** Ответ собирается на стороне платформы Вайбкод, обращения к Битрикс24 при этом не происходит. Поэтому запросу достаточно скоупа `task` — настроенные токены портала для него не нужны.

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

- [Учёт времени задач](/docs/entities/tasks/time)
- [Добавить запись](/docs/entities/tasks/time/create)
- [Обновить запись](/docs/entities/tasks/time/update)
- [Список по всему порталу](/docs/entities/tasks/time/global-list)