# Рабочие группы

Управление рабочими группами и проектами портала: создание, получение, обновление, удаление, поиск. Рабочая группа объединяет сотрудников вокруг общей темы или проекта — у неё есть владелец, тема, флаги открытости и архивирования, а также счётчик участников.

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

## Операции

- [Создать рабочую группу](./workgroups/create.md) — `POST /v1/workgroups`
- [Список рабочих групп](./workgroups/list.md) — `GET /v1/workgroups`
- [Получить рабочую группу](./workgroups/get.md) — `GET /v1/workgroups/:id`
- [Обновить рабочую группу](./workgroups/update.md) — `PATCH /v1/workgroups/:id`
- [Удалить рабочую группу](./workgroups/delete.md) — `DELETE /v1/workgroups/:id`
- [Поиск рабочих групп](./workgroups/search.md) — `POST /v1/workgroups/search`
- [Поля рабочей группы](./workgroups/fields.md) — `GET /v1/workgroups/fields`
- [Агрегация рабочих групп](./workgroups/aggregate.md) — `POST /v1/workgroups/aggregate`
- [Участники рабочей группы](./workgroups/users.md) — `GET /v1/workgroups/:groupId/users`

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

| Поле | Описание |
|------|---------|
| `name` | Название рабочей группы |
| `ownerId` | Идентификатор владельца. Источник: [`GET /v1/users`](/docs/entities/users) |
| `subjectId` | Идентификатор темы. Список допустимых значений отдаётся в ответах [`GET /v1/workgroups`](./workgroups/list.md) в поле `subjectName` рядом с `subjectId` |
| `opened` | Признак открытости — может ли вступить любой сотрудник портала |
| `isProject` | Признак проекта — у проектов отдельная семантика в задачах и отчётах |
| `archived` | Признак архива — группа скрыта из активных списков, но сохранена |
| `membersCount` | Текущее количество участников группы |

Полный список полей — [`GET /v1/workgroups/fields`](./workgroups/fields.md).

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

1. **Булевы поля имеют разный формат на входе и в ответе.** В URL-фильтрах (`?filter[active]=...`) булевы поля передаются как `Y` или `N`. В теле запросов `POST` / `PATCH` и в body `POST /v1/workgroups/search` работают и `Y` / `N`, и нативные JSON `true` / `false`. В ответах всех эндпоинтов — всегда `true` / `false`.
2. **`archived` и `active` — разные признаки.** `archived: true` означает, что группа перенесена в архив и не отображается в активных списках. `active: false` означает, что группа выключена. Это два независимых состояния.
3. **`isProject: true` — отдельная семантика.** Проектные группы по-другому ведут себя в задачах и отчётах Битрикс24. Чтобы создать обычную рабочую группу без проектной логики, оставьте `isProject` пустым или передайте `false`.
4. **Темы задаются на стороне портала.** Перечень допустимых `subjectId` настраивается администратором Битрикс24 и не редактируется через API рабочих групп. Сопоставление `subjectId` ↔ `subjectName` возвращается в каждом элементе списка рабочих групп.

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

1. Найти будущего владельца группы: [`GET /v1/users?filter[name]=Иван`](/docs/entities/users).
2. Создать рабочую группу: [`POST /v1/workgroups`](./workgroups/create.md) с `name`, `ownerId`, `subjectId`, `opened`.
3. Получить список рабочих групп сотрудника: [`GET /v1/workgroups?filter[ownerId]=15`](./workgroups/list.md).
4. Обновить параметры: [`PATCH /v1/workgroups/:id`](./workgroups/update.md) — например, переключить `opened` или изменить `description`.
5. Перенести группу в архив: [`PATCH /v1/workgroups/:id`](./workgroups/update.md) с `archived: true`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Ограничение частоты запросов | общее для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Справочник API](/docs/api-reference)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Сотрудники](/docs/entities/users)
- [Отделы](/docs/entities/departments)