## Пригласить участников

`POST /v1/workgroups/:groupId/invitations`

Отправляет пользователям приглашение вступить в рабочую группу. Участниками они становятся, только когда сами примут приглашение в Битрикс24.

## Параметры

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

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

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

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups/157/invitations" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "message": "Присоединяйтесь к группе проекта"}'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups/157/invitations" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userIds": [93], "message": "Присоединяйтесь к группе проекта"}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/157/invitations', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93], message: 'Присоединяйтесь к группе проекта' }),
})

const body = await res.json()
if (!body.success && body.error.code === 'BITRIX_ERROR') {
  if (Array.isArray(body.error.processedUserIds)) {
    // Приглашения из 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/invitations', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [93], message: 'Присоединяйтесь к группе проекта' }),
})

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 | `INVALID_PARAMS` | `message` передан, но это не строка |
| 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).

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

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

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

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