--- name: pachca-users description: > Управление сотрудниками и тегами (группами). Создание, обновление, удаление, поиск сотрудников. Онбординг и offboarding. Создание и управление тегами. Управление статусом сотрудника. Используй когда нужно: найти сотрудника, создать пользователя, онбординг/offboarding, управлять тегами, установить статус сотруднику. НЕ используй для: собственного профиля (→ pachca-profile). --- # pachca-users Base URL: `https://api.pachca.com/api/shared/v1` Авторизация: `Authorization: Bearer ` Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API). Если токен неизвестен — спроси у пользователя перед выполнением запросов. ## Когда использовать - найти сотрудника - создать пользователя - список сотрудников - создать тег - управлять тегами - назначить тег - приостановить сотрудника - онбординг - offboarding - уволить сотрудника - участники тега - статус сотрудника - установить статус сотруднику ## Когда НЕ использовать - получить профиль, мой профиль, установить статус → **pachca-profile** - создать канал, создать беседу, создать чат → **pachca-chats** - отправить сообщение, ответить в тред, прикрепить файл → **pachca-messages** - настроить бота, вебхук, webhook → **pachca-bots** - показать форму, интерактивная форма, модальное окно → **pachca-forms** - создать задачу, список задач, напоминание → **pachca-tasks** - аудит, журнал событий, безопасность → **pachca-security** ## Пошаговые сценарии ### Массовое создание сотрудников с тегами 1. Создай тег (если нужен): POST /group_tags с `{"group_tag": {"name": ...}}` 2. Для каждого сотрудника: POST /users — теги назначаются через поле `list_tags` в теле запроса 3. Или обнови существующего: PUT /users/{id} с `list_tags` > Создание сотрудников доступно только администраторам и владельцам (не ботам). Нет отдельного эндпоинта "добавить юзера в тег" — теги назначаются через `list_tags` при создании (POST /users) или обновлении (PUT /users/{id}). ### Найти сотрудника по имени или email 1. GET /users?query=Иван — поиск по имени/email (частичное совпадение) 2. Если нужен точный поиск по email — перебери страницы и отфильтруй на клиенте ```bash curl "https://api.pachca.com/api/shared/v1/users?query=Иван&limit=50" \ -H "Authorization: Bearer $TOKEN" # Ответ: {"data":[{"id":186,"first_name":"Иван","last_name":"Петров","email":"ivan@example.com",...}]} ``` > GET /users поддерживает параметр `query` для поиска. Пагинация cursor-based: используй `limit` и `cursor` из `meta`. ### Онбординг нового сотрудника 1. POST /users с `email`, именем, тегами (`list_tags`) — создать аккаунт 2. POST /chats/{id}/members с `member_ids` — добавить в нужные каналы (онбординг, общий, тематические) 3. POST /messages с `"entity_type": "user"`, `"entity_id": user.id` — отправить welcome-сообщение в личные сообщения > Шаг 1 требует токена администратора/владельца. Шаги 2-3 можно делать ботом. ### Offboarding сотрудника 1. PUT /users/{id} с `"suspended": true` — заблокировать доступ 2. Опционально: DELETE /users/{id} — удалить аккаунт полностью > Приостановка (`suspended`) сохраняет данные, удаление — необратимо. Уточняй политику перед удалением. ### Получить всех сотрудников тега/департамента 1. GET /group_tags?names[]=Backend — найти тег по названию 2. Из ответа взять `id` тега 3. GET /group_tags/{id}/users с пагинацией (`limit` + `cursor`) — получить всех участников ### Управление статусом сотрудника 1. GET /users/{user_id}/status — получить текущий статус сотрудника 2. PUT /users/{user_id}/status с `emoji`, `title` и опционально `is_away: true` — установить статус 3. DELETE /users/{user_id}/status — удалить статус сотрудника ```bash curl -X PUT "https://api.pachca.com/api/shared/v1/users/13/status" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"status":{"emoji":"🏖️","title":"В отпуске","is_away":true}}' ``` > Для установки режима «Нет на месте» передай `is_away: true`. Скоупы: `user_status:read` для чтения, `user_status:write` для записи/удаления. ## Обработка ошибок | Код | Причина | Что делать | |-----|---------|------------| | 422 | Неверные параметры | Проверь обязательные поля, типы данных, допустимые значения enum | | 429 | Rate limit | Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec | | 403 | Нет доступа | Недостаточно скоупов (`insufficient_scope`), бот не в чате, или endpoint только для админов/владельцев | | 404 | Не найдено | Неверный id. Проверь что сущность существует | | 401 | Не авторизован | Проверь токен в заголовке Authorization | ## Доступные операции ### Новый тег `POST /group_tags` > скоуп: `group_tags:write` ```json { "group_tag": { "name": "Новое название тега" } } ``` ### Список тегов сотрудников `GET /group_tags` > скоуп: `group_tags:read` ### Информация о теге `GET /group_tags/{id}` > скоуп: `group_tags:read` ### Редактирование тега `PUT /group_tags/{id}` > скоуп: `group_tags:write` ```json { "group_tag": { "name": "Новое название тега" } } ``` ### Удаление тега `DELETE /group_tags/{id}` > скоуп: `group_tags:write` ### Список сотрудников тега `GET /group_tags/{id}/users` > скоуп: `group_tags:read` ### Создать сотрудника `POST /users` > скоуп: `users:create` ```json { "user": { "email": "olegp@example.com" } } ``` ### Список сотрудников `GET /users` > скоуп: `users:read` ### Информация о сотруднике `GET /users/{id}` > скоуп: `users:read` ### Редактирование сотрудника `PUT /users/{id}` > скоуп: `users:update` ```json { "user": {} } ``` ### Удаление сотрудника `DELETE /users/{id}` > скоуп: `users:delete` ### Статус сотрудника `GET /users/{user_id}/status` > скоуп: `user_status:read` ### Новый статус сотрудника `PUT /users/{user_id}/status` > скоуп: `user_status:write` ```json { "status": { "emoji": "", "title": "" } } ``` ### Удаление статуса сотрудника `DELETE /users/{user_id}/status` > скоуп: `user_status:write` ## Ограничения и gotchas - `limit`: максимум 50 - `user.role`: допустимые значения — `admin` (Администратор), `user` (Сотрудник), `multi_guest` (Мульти-гость) - Пагинация: cursor-based (limit + cursor), НЕ page-based ## Подробнее см. [references/endpoints.md](references/endpoints.md)