## Поиск пользователей Битрикс24

`GET /v1/infra/servers/:id/b24-users`

Ищет активных сотрудников на портале Битрикс24 по имени, фамилии или email — возвращает `userId`, имя, должность и фото для каждого совпадения. Неактивные пользователи и пользователи других типов в результат не попадают. Используется для заполнения списка `NAMED_USERS` через [`POST /access`](./access-add.md), когда известно имя человека, но не его ID на портале. Работает через B24-креды сервера: веб-хук-ключ из [apiKey.webhookUrl](/docs/keys-auth), а если ключ сервера — OAuth-приложение без пользовательского токена, применяется автоматический фоллбэк: сначала personal-ключ связанного приложения, затем личные ключи владельца сервера — от свежего к старому, до первого, который действительно даёт доступ к Битрикс24. Если ни один источник не даёт креды (приложение ещё не авторизовано на портале, ключ отозван или управляющий ключ не имеет доступа к Битрикс24 — например, нет webhook или нужного скоупа), эндпоинт возвращает пустой `data` вместе с полем `hint`, которое объясняет причину.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID сервера |
| `search` | query | string | **да** | Строка поиска, минимум 2 символа. Ищет по имени, фамилии и email |

## Примеры

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

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-users?search=Иван"
```

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

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/b24-users?search=Иван"
```

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

```javascript
const q = encodeURIComponent('Иван')
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: users } = await res.json()
users.forEach(u => console.log(`${u.id}: ${u.name} — ${u.position ?? 'без должности'}`))
```

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

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив найденных активных сотрудников |
| `data[].id` | string | ID пользователя Битрикс24 — передавайте в `userId` при [`POST /access`](./access-add.md) |
| `data[].name` | string | Полное имя (имя + фамилия) |
| `data[].photo` | string \| null | URL аватарки (может быть `null`) |
| `data[].position` | string \| null | Должность (может быть `null`) |
| `hint` | string | Необязательное. Присутствует только когда `data` пуст из-за отсутствия B24-кредов (приложение не авторизовано на портале, ключ отозван или управляющий ключ не имеет webhook/нужного скоупа). При непустой выдаче отсутствует |

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

```json
{
  "success": true,
  "data": [
    {
      "id": "243",
      "name": "Катя Иванова",
      "photo": null,
      "position": null
    }
  ]
}
```

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

400 — строка поиска короче 2 символов:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "search query required (min 2 chars)"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | `search` отсутствует или короче 2 символов |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |
| 403 | `SERVER_ROLE_FORBIDDEN` | Вы состоите в команде разработки этого сервера с ролью «Разработчик», а операция открыта роли «Администратор». В `error.hint` придут ваша роль, требуемый порог и перечень открытых вам вызовов. Разбор ролей — [Список серверов](/docs/infra/servers/list) |
| 404 | `NOT_FOUND` | Сервер не существует, удалён или привязан к другому API-ключу, и вы не состоите в его команде разработки |
| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |

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

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

- **Пустой `data` с полем `hint`, когда B24-кредов нет.** Если ключ сервера — OAuth-приложение без пользовательского токена, платформа сначала пробует personal-ключ связанного приложения, а затем перебирает личные ключи владельца сервера от свежего к старому. Если доступа не даёт ни один (приложения нет, ключи отозваны/истекли, владелец заблокирован или ни у одного ключа нет webhook/нужного скоупа), эндпоинт возвращает `data: []` и строку `hint` с причиной — вместо немого пустого массива. Клиент может отобразить `hint` пользователю или переключиться на альтернативный инструмент.
- **Поиск выполняется через метод `user.search` на портале Битрикс24.** То есть логика совпадения с UI портала — те же правила по имени/фамилии/email.
- **Кириллица в URL — через `encodeURIComponent`.** На JS: `encodeURIComponent('Иван')`. На curl: `?search=%D0%98%D0%B2%D0%B0%D0%BD`.
- **Не зависит от режима сервера.** Поиск работает для любого сервера — и BLACKHOLE, и OPEN. Логически он нужен для `NAMED_USERS`, но эндпоинт не ограничивает вызов по `mode`.

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

- [Добавить пользователя/отдел](./access-add.md)
- [Список доступа](./access-list.md)
- [Политика доступа](./access-policy.md)