[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-infra\u002Faccess\u002Fb24-users":3,"docs-tabs-infra\u002Faccess\u002Fb24-users":6},{"content":4,"lastmod":5},"\n## Поиск пользователей Битрикс24\n\n`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Fb24-users`\n\nИщет пользователей на портале Битрикс24 по имени, фамилии или email — возвращает `userId`, имя, должность и фото для каждого совпадения. Используется для заполнения списка `NAMED_USERS` через [`POST \u002Faccess`](.\u002Faccess-add.md), когда известно имя человека, но не его ID на портале. Работает через веб-хук-ключ из [apiKey.webhookUrl](\u002Fdocs\u002Fkeys-auth). Если у текущего API-ключа `webhookUrl` отсутствует (например, OAuth-ключ без связанного вебхука), эндпоинт вернёт пустой массив.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n| `search` | query | string | **да** | Строка поиска, минимум 2 символа. Ищет по имени, фамилии и email |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fb24-users?search=Иван\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Fb24-users?search=Иван\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst q = encodeURIComponent('Иван')\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fb24-users?search=${q}`,\n  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst { data: users } = await res.json()\nusers.forEach(u => console.log(`${u.id}: ${u.name} — ${u.position ?? 'без должности'}`))\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Fb24-users?search=${q}`,\n  {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив найденных пользователей |\n| `data[].id` | string | ID пользователя Битрикс24 — передавайте в `userId` при [`POST \u002Faccess`](.\u002Faccess-add.md) |\n| `data[].name` | string | Полное имя (имя + фамилия) |\n| `data[].photo` | string \\| null | URL аватарки (может быть `null`) |\n| `data[].position` | string \\| null | Должность (может быть `null`) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"243\",\n      \"name\": \"Катя Иванова\",\n      \"photo\": null,\n      \"position\": null\n    }\n  ]\n}\n```\n\n## Пример ответа при ошибке\n\n400 — строка поиска короче 2 символов:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"search query required (min 2 chars)\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 400 | `VALIDATION_ERROR` | `search` отсутствует или короче 2 символов |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Почему пустой массив при отсутствии `webhookUrl`.** Это сделано специально — клиент может работать одинаково с любым типом ключа: при отсутствии вебхука получает пустой результат (без ошибки) и переключается на альтернативный инструмент поиска.\n- **Поиск выполняется через метод `user.search` на портале Битрикс24.** То есть логика совпадения с UI портала — те же правила по имени\u002Fфамилии\u002Femail.\n- **Кириллица в URL — через `encodeURIComponent`.** На JS: `encodeURIComponent('Иван')`. На curl: `?search=%D0%98%D0%B2%D0%B0%D0%BD`.\n- **Не зависит от режима сервера.** Поиск работает для любого сервера — и BLACKHOLE, и OPEN. Логически он нужен для `NAMED_USERS`, но эндпоинт не ограничивает вызов по `mode`.\n\n## Смотрите также\n\n- [Добавить пользователя\u002Fотдел](.\u002Faccess-add.md) — добавить найденного пользователя в список доступа.\n- [Список доступа](.\u002Faccess-list.md) — увидеть уже добавленных пользователей и отделов.\n- [Политика доступа](.\u002Faccess-policy.md) — переключиться на `NAMED_USERS`.\n","2026-07-07",{}]