## Отчёты подчинённых `GET /v1/workday/work-reports/subordinates` Возвращает сданные рабочие отчёты владельца учётных данных и сотрудников, чей учёт рабочего времени он может читать. Подходит руководителю для просмотра отчётов команды. Требуется скоуп `timeman` и право владельца учётных данных в Битрикс24 читать учёт рабочего времени подчинённых или всех сотрудников. С правом на всех сотрудников приходят отчёты всей компании. Ключ READONLY может читать отчёты. ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|----------| | `userId` (query) | integer | нет | — | ID сотрудника — вернуть только его отчёты. Список: [`GET /v1/users`](/docs/entities/users/list) | | `userIds` (query) | string | нет | — | ID сотрудников через запятую, например `103,105`. Вместе с `userId` приходят отчёты всех перечисленных сотрудников. Список: [`GET /v1/users`](/docs/entities/users/list) | | `activeOnly` (query) | boolean | нет | — | Принимается, но выдачу не меняет: приходят только сданные отчёты | | `dateFrom` (query) | string | нет | — | Начало периода в формате ISO 8601 с часовым поясом. В выдачу попадают отчёты, чей период пересекается с заданным, границы включаются | | `dateTo` (query) | string | нет | — | Конец периода в том же формате | | `limit` (query) | integer | нет | `5` | Сколько сотрудников вернуть, от 1 до 50 | | `offset` (query) | integer | нет | `0` | Сколько сотрудников пропустить. Нельзя передавать вместе с `page` | | `page` (query) | integer | нет | `1` | Номер страницы размером `limit` сотрудников. Нельзя передавать вместе с `offset` | ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/workday/work-reports/subordinates?userIds=103,105" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/workday/work-reports/subordinates?userIds=103,105" \ -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/subordinates?userIds=103,105', { 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/subordinates?userIds=103,105', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data, meta } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|----------| | `success` | boolean | `true` при успешном запросе | | `data` | array | Сотрудники со сданными отчётами. Сотрудник без подходящих отчётов в массив не попадает. Первым идёт сам владелец учётных данных, если у него есть подходящие отчёты | | `data[].userId` | integer | ID сотрудника. Список: [`GET /v1/users`](/docs/entities/users/list) | | `data[].user` | object \| null | Сотрудник | | `data[].user.id` | integer | ID сотрудника, совпадает с `userId` | | `data[].user.name` | string | Имя и фамилия сотрудника | | `data[].user.photo` | string \| null | Адрес фотографии профиля | | `data[].reports` | array | Сданные отчёты сотрудника по убыванию `id`. Состав отчёта — [Поля отчёта](/docs/workday/work-reports/fields) | | `meta.offset` | integer | Сколько сотрудников пропущено | | `meta.limit` | integer | Сколько сотрудников на странице | | `meta.hasMore` | boolean | `true`, если за этой страницей есть ещё сотрудники | | `meta.nextOffset` | integer \| null | Значение `offset` для следующей страницы или `null`, если страниц больше нет | | `meta.paginationUnit` | string | Всегда `users`: `limit` и `offset` считают сотрудников, а не отчёты | ## Пример ответа Показаны основные поля отчёта. Полный список — [Поля отчёта](/docs/workday/work-reports/fields): ```json { "success": true, "data": [ { "userId": 103, "user": { "id": 103, "name": "Anna Smith", "photo": null }, "reports": [ { "id": 79, "userId": 103, "active": true, "reportType": "week", "reportDate": "2023-03-02T10:39:37.000Z", "dateFrom": "2023-01-15T21:00:00.000Z", "dateTo": "2023-01-21T21:00:00.000Z", "report": "Hi :)", "type": "REPORT", "mark": "G", "approve": "Y" } ] }, { "userId": 105, "user": { "id": 105, "name": "John Brown", "photo": null }, "reports": [ { "id": 115, "userId": 105, "active": true, "reportType": "week", "reportDate": "2024-02-14T11:34:24.000Z", "dateFrom": "2024-02-04T21:00:00.000Z", "dateTo": "2024-02-10T21:00:00.000Z", "report": "", "type": "REPORT", "mark": "X", "approve": "N" }, { "id": 111, "userId": 105, "active": true, "reportType": "week", "reportDate": "2024-01-26T14:20:50.000Z", "dateFrom": "2024-01-21T21:00:00.000Z", "dateTo": "2024-01-27T21:00:00.000Z", "report": "", "type": "REPORT", "mark": "X", "approve": "N" } ] } ], "meta": { "offset": 0, "limit": 5, "hasMore": false, "nextOffset": null, "paginationUnit": "users" } } ``` ## Пример ответа при ошибке 400 — `limit` больше 50: ```json { "success": false, "error": { "code": "WORKDAY_REPORT_LIMIT_EXCEEDED", "message": "Report list limit must be between 1 and 50" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|----------| | 400 | `WORKDAY_REPORT_LIMIT_EXCEEDED` | `limit` больше 50 | | 400 | `INVALID_PARAMS` | В `userId`, `limit` или `page` не положительное целое число; в `userIds` не положительные целые числа через запятую; в `offset` не целое неотрицательное число; переданы одновременно `offset` и `page`; в `activeOnly` не `true`, `false`, `1` или `0`; дата без часового пояса, несуществующая или не позже `1970-01-01T00:00:00Z`; неизвестный параметр, например `order` или `select`; один параметр передан дважды | | 403 | `BITRIX_ACCESS_DENIED` | У владельца учётных данных нет права читать учёт рабочего времени подчинённых или всех сотрудников | | 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` | Превышен лимит чтения отчётов — 30 запросов в минуту на пару ключ–пользователь. Действующее значение — в заголовке `x-ratelimit-limit`, потолок делится между репликами. Или превышен общий лимит запросов | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Смотрите также - [Список рабочих отчётов](/docs/workday/work-reports/list) - [Поля отчёта](/docs/workday/work-reports/fields) - [Рабочие отчёты](/docs/workday/work-reports) - [Дневные отчёты](/docs/workday/daily-reports) - [Рабочий день](/docs/workday)