## Добавить участников

`POST /v1/workgroups/:groupId/users`

Добавляет пользователей в рабочую группу сразу, без приглашения и подтверждения с их стороны. Добавленные получают роль участника.

## Параметры

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

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `userIds` | number[] | да | Непустой массив идентификаторов пользователей — положительных целых чисел. Строки вида `"93"` не принимаются. Список: [`GET /v1/users`](/docs/entities/users/list) |

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93]}'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups/157/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93]}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/157/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93] }),
})

const body = await res.json()
if (!body.success && body.error.code === 'BITRIX_ERROR') {
  if (Array.isArray(body.error.processedUserIds)) {
    // Часть пользователей могла добавиться — изменения не откатываются
    console.log('Добавлены:', body.error.processedUserIds)
    console.log('Не добавлены:', body.error.skippedUserIds)
  } else {
    // Второй вариант 422: Битрикс24 отказал в вызове, массивов в ответе нет
    console.log('Битрикс24 отказал:', body.error.message)
  }
}
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/157/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93] }),
})

const body = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true`, когда добавлены все запрошенные пользователи |
| `data.groupId` | number | Идентификатор рабочей группы |
| `data.processedUserIds` | number[] | Идентификаторы добавленных пользователей. Повторы из `userIds` схлопываются в один |
| `data.skippedUserIds` | number[] | В успешном ответе всегда пустой массив. Если добавить удалось не всех, приходит `422 BITRIX_ERROR`, а оба массива переезжают в `error`. Это единственный ответ с массивами: у второго `422 BITRIX_ERROR` — когда Битрикс24 отказал в вызове — в `error` только его собственный текст, без `processedUserIds` и `skippedUserIds` |

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

```json
{
  "success": true,
  "data": {
    "groupId": 157,
    "processedUserIds": [93],
    "skippedUserIds": []
  }
}
```

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

422 — пользователь уже состоит в группе, добавлять некого:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Bitrix24 did not change every requested user: existing membership or role, owner, scrum master, missing user or permissions may prevent the action. Do not blindly retry invitations.",
    "processedUserIds": [],
    "skippedUserIds": [93]
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `groupId` не является положительным целым числом, например `15.7` |
| 400 | `MISSING_REQUIRED_FIELDS` | `userIds` не передан, пустой или содержит что-то кроме положительных целых чисел |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 401 | `TOKEN_MISSING` | У ключа нет токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `sonet_group` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя, от имени которого действует ключ, нет прав менять состав этой группы |
| 404 | `ENTITY_NOT_FOUND` | Группы нет либо она не видна пользователю, от имени которого действует ключ |
| 422 | `BITRIX_ERROR` | Добавлены не все пользователи. Кто добавлен и кто нет — в `error.processedUserIds` и `error.skippedUserIds`. Причины пропуска: пользователь уже в группе, приглашён в неё или такого пользователя нет |
| 422 | `BITRIX_ERROR` | Битрикс24 отказал в вызове и вернул свою причину в `error.message`. Массивов `error.processedUserIds` и `error.skippedUserIds` в этом ответе нет — проверяйте их наличие, прежде чем читать, и перечитайте состав группы перед повтором |
| 429 | `RATE_LIMITED` | Превышен лимит запросов. Пауза — в заголовке `Retry-After` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ответ, который эндпоинт не может разобрать |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял вызов, но не ответил вовремя. Есть заголовок `Retry-After`. Перед повтором перечитайте состав группы: добавление могло пройти |

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

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

- **Частичный результат не откатывается.** Если в `userIds` несколько пользователей и часть из них пропущена, ответ — `422`, но тех, кто попал в `error.processedUserIds`, уже добавили. Перед повтором перечитайте состав через [`GET /v1/workgroups/:groupId/users`](/docs/entities/workgroups/users) и отправьте только недостающих.
- **Приглашённого пользователя так не добавить.** Пока приглашение из [`POST /v1/workgroups/:groupId/invitations`](./invite.md) не принято, пользователь попадает в `skippedUserIds`. Чтобы добавить его сразу, сначала отмените приглашение через [`DELETE /v1/workgroups/:groupId/users`](./remove.md).
- **Каждое добавление видно в чате группы.** На каждого добавленного пользователя в чат группы приходит системное сообщение о его вступлении.
- **`422` не называет причину пропуска по каждому пользователю.** Пропуски при повторном добавлении, при неотвеченном приглашении и при несуществующем идентификаторе выглядят одинаково. Причину выясняйте по составу группы и по [`GET /v1/users/:id`](/docs/entities/users/get).

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

- [Удалить участников](./remove.md)
- [Изменить роль](./role.md)
- [Пригласить участников](./invite.md)
- [Участники рабочей группы](/docs/entities/workgroups/users)
- [Участники рабочих групп](/docs/workgroups/members)