## Участники рабочей группы

`GET /v1/workgroups/:groupId/users`

Возвращает участников рабочей группы вместе с их ролью в ней — владелец, модератор или участник.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `groupId` (path) | number | ★ да | — | Идентификатор рабочей группы. Список: [`GET /v1/workgroups`](../workgroups.md) |

Параметров постраничной выдачи у операции нет: состав возвращается целиком.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workgroups/85/users" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workgroups/85/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

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

const { success, data } = await res.json()
const moderators = data.filter(m => m.role === 'A' || m.role === 'E')
console.log('Руководителей и модераторов:', moderators.length)
```

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

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

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data[].userId` | number | Идентификатор пользователя. Карточка: [`GET /v1/users`](/docs/entities/users) |
| `data[].role` | string | Роль пользователя в группе: `A` — владелец, `E` — модератор, `K` — участник |
| `meta.total` | number | Число участников. Всегда равно длине `data` |
| `meta.warnings[]` | object | Присутствует только в двух особых случаях — см. «Известные особенности» |

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

```json
{
  "success": true,
  "data": [
    { "userId": 1269, "role": "A" },
    { "userId": 1271, "role": "E" },
    { "userId": 779, "role": "K" }
  ],
  "meta": {
    "total": 3
  }
}
```

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

404 — группы с таким `groupId` нет либо она не видна этому ключу:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Workgroup not found, or not visible to the identity this key acts as"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `groupId` не является каноническим положительным целым числом |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 401 | `TOKEN_MISSING` | У ключа нет токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `sonet_group` |
| 404 | `ENTITY_NOT_FOUND` | Группы нет либо она не видна учётной записи, от имени которой действует ключ |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 вернул ответ или строку участника, которые эндпоинт не может разобрать |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял вызов, но не ответил вовремя. Есть заголовок `Retry-After` |

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

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

- **Роль приходит буквой Битрикс24 как есть.** Незнакомая буква проходит насквозь, а не приводится к известной и не отбрасывается: так контракт переживёт появление новой роли. Проверяйте те значения, которые знаете, а всё остальное трактуйте как отсутствие прав — не подставляйте «участник» по умолчанию.
- **Владелец группы не обязательно есть среди строк.** Его идентификатор отдаёт поле `ownerId` в [`GET /v1/workgroups/:id`](./get.md); выводить владельца из наличия строки с ролью `A` нельзя.
- **Пустой состав — обычный ответ, а не ошибка.** У существующей группы участников может не быть вовсе, тогда приходит `200` с пустым `data`.
- **`404` не означает «группы не существует».** Битрикс24 одинаково отказывает и для несуществующей, и для невидимой этому ключу группы, поэтому различить их на стороне API невозможно.
- **Это данные о составе, а не решение о доступе.** Что именно покажет эндпоинт, зависит от личности за ключом: личный ключ и вебхук читают от имени своего владельца, а OAuth-ключ с проброшенной пользовательской сессией — от имени этого пользователя. Признак администратора портала сюда не входит: его отдаёт [`GET /v1/users/me`](/docs/entities/users/me). Гейт «руководитель, модератор или админ портала» собирается из двух источников.
- **Нечисловой или дробный `groupId` возвращает `400`, а не данные другой группы.** Битрикс24 округляет такой идентификатор вниз и ответил бы составом другой группы — платформа отбивает такой запрос до вызова.
- **Постраничной выдачи нет:** `limit` и `offset` не принимаются и игнорируются, состав возвращается целиком, `meta.total` всегда равен длине `data`.
- **`meta.warnings` появляется только в двух случаях:** `DUPLICATE_MEMBER_ROW` — Битрикс24 вернул больше одной строки на одного пользователя (строки отдаются как есть; если роли в них расходятся, считайте членство неоднозначным), и `MEMBER_ROSTER_PAGE_BOUNDARY` — вернулось ровно 50 строк, что неотличимо от усечённой первой страницы; сверьте с полем `membersCount` в [`GET /v1/workgroups/:id`](./get.md), если важен точный состав.
- **Через [`POST /v1/batch`](/docs/batch) операция недоступна** — вложенные ресурсы там не адресуются.

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

- [Получить рабочую группу](./get.md)
- [Список рабочих групп](./list.md)
- [Поля рабочей группы](./fields.md)