## Список рабочих отчётов

`GET /v1/workday/work-reports`

Возвращает рабочие отчёты сотрудника с отбором по периоду и постраничной выдачей.

Требуется скоуп `timeman`. Битрикс24 проверяет права владельца учётных данных. Ключ READONLY может читать отчёты, запись запрещена.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|----------|
| `userId` (query) | integer | да | — | ID сотрудника, чьи отчёты нужны. Список: [`GET /v1/users`](/docs/entities/users/list) |
| `activeOnly` (query) | boolean | нет | — | `true` — только сданные отчёты |
| `dateFrom` (query) | string | нет | — | Начало периода в формате ISO 8601 с часовым поясом. В выдачу попадают отчёты, чей период пересекается с заданным, границы включаются |
| `dateTo` (query) | string | нет | — | Конец периода в том же формате |
| `limit` (query) | integer | нет | `50` | Сколько отчётов вернуть, от 1 до 50 |
| `offset` (query) | integer | нет | `0` | Сколько отчётов пропустить. Нельзя передавать вместе с `page` |
| `page` (query) | integer | нет | `1` | Номер страницы размером `limit`. Нельзя передавать вместе с `offset` |
| `order` (query) | string | нет | `{"id":"desc"}` | Сортировка — JSON-объект с направлениями `asc` или `desc`, например `{"id":"asc"}` |
| `select` (query) | string | нет | — | Поля отчёта через запятую. Список — [Поля отчёта](/docs/workday/work-reports/fields) |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workday/work-reports?userId=101" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workday/work-reports?userId=101" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/work-reports?userId=101', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data, meta } = await res.json()
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/work-reports?userId=101', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном запросе |
| `data` | array | Массив отчётов. Состав отчёта — [Поля отчёта](/docs/workday/work-reports/fields) |
| `meta.limit` | integer | Размер страницы |
| `meta.offset` | integer | Сколько отчётов пропущено |
| `meta.hasMore` | boolean | `true`, когда на странице `limit` отчётов и за ней могут быть ещё |

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

Показаны основные поля отчёта. Полный список — [Поля отчёта](/docs/workday/work-reports/fields):

```json
{
  "success": true,
  "data": [
    {
      "id": 145,
      "userId": 101,
      "active": false,
      "reportType": "day",
      "reportDate": "2026-10-06T18:33:06.000Z",
      "dateFrom": "2026-10-06T21:00:00.000Z",
      "dateTo": "2026-10-06T21:00:00.000Z",
      "report": "Sprint summary",
      "type": "REPORT",
      "mark": "N",
      "approve": "N"
    },
    {
      "id": 143,
      "userId": 101,
      "active": false,
      "reportType": "day",
      "reportDate": "2026-10-06T18:22:40.000Z",
      "dateFrom": "2026-10-05T21:00:00.000Z",
      "dateTo": "2026-10-05T21:00:00.000Z",
      "report": "Weekly report",
      "type": "REPORT",
      "mark": "N",
      "approve": "N"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```

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

400 — не передан `userId`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Expected a positive integer"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `WORKDAY_REPORT_LIMIT_EXCEEDED` | `limit` больше 50 |
| 400 | `INVALID_PARAMS` | Не передан `userId`, переданы одновременно `offset` и `page`, неизвестное поле в `select`, неверная дата или неизвестный параметр |
| 403 | `BITRIX_ACCESS_DENIED` | У владельца учётных данных нет прав в Битрикс24 на отчёты этого сотрудника |
| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Учёт рабочего времени недоступен на портале |
| 422 | `BITRIX_ERROR` | Битрикс24 отказал в операции |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ответ неожиданной формы |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | Ключ приложения передан без токена сессии в `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | Токен сессии неверный или истёк |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `timeman` |
| 429 | `RATE_LIMITED` | Превышен лимит чтения отчётов или общий лимит запросов |

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

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

- **`select` оставляет в отчётах только перечисленные поля.** `id` приходит всегда, даже если его нет в списке.
- **Порядок задаёт только `id`.** Остальные поля в `order` применяются после `id`, поэтому порядок выдачи не меняют.
- **Даты в `dateFrom` и `dateTo` — строго позже `1970-01-01T00:00:00Z`.** Более ранняя дата и сама эта отметка возвращают `400 INVALID_PARAMS`.

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

- [Создать рабочий отчёт](/docs/workday/work-reports/create)
- [Сдать рабочий отчёт](/docs/workday/work-reports/submit)
- [Рабочие отчёты](/docs/workday/work-reports)
- [Дневные отчёты](/docs/workday/daily-reports)
- [Рабочий день](/docs/workday)