pachca-users

Base URL: https://api.pachca.com/api/shared/v1 Авторизация: Authorization: Bearer <ACCESS_TOKEN> Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API). Если токен неизвестен — спроси у пользователя перед выполнением запросов.

Когда использовать

• найти сотрудника
• создать пользователя
• список сотрудников
• создать тег
• управлять тегами
• назначить тег
• приостановить сотрудника
• онбординг
• offboarding
• уволить сотрудника
• участники тега
• статус сотрудника
• установить статус сотруднику

Когда НЕ использовать

• получить профиль, мой профиль, установить статус → pachca-profile
• создать канал, создать беседу, создать чат → pachca-chats
• отправить сообщение, ответить в тред, прикрепить файл → pachca-messages
• настроить бота, вебхук, webhook → pachca-bots
• показать форму, интерактивная форма, модальное окно → pachca-forms
• создать задачу, список задач, напоминание → pachca-tasks
• поиск сообщений, найти сообщение, полнотекстовый поиск → pachca-search
• аудит, журнал событий, безопасность → 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 — перебери страницы и отфильтруй на клиенте

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, away_message: "текст" — установить статус
3. DELETE /users/{user_id}/status — удалить статус сотрудника

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,"away_message":"Я в отпуске до 15 апреля"}}'

Для установки режима «Нет на месте» передай is_away: true. away_message — сообщение, отображаемое в профиле и при личных сообщениях/упоминаниях (макс 1024 символа). Скоупы: user_status:read для чтения, user_status:write для записи/удаления.

Обработка ошибок

Доступные операции

Новый тег

POST /group_tags

скоуп: group_tags:write

{
  "group_tag": {
    "name": "Новое название тега"
  }
}

Список тегов сотрудников

GET /group_tags

скоуп: group_tags:read

Информация о теге

GET /group_tags/{id}

скоуп: group_tags:read

Редактирование тега

PUT /group_tags/{id}

скоуп: group_tags:write

{
  "group_tag": {
    "name": "Новое название тега"
  }
}

Удаление тега

DELETE /group_tags/{id}

скоуп: group_tags:write

Список сотрудников тега

GET /group_tags/{id}/users

скоуп: group_tags:read

Создать сотрудника

POST /users

скоуп: users:create

{
  "user": {
    "email": "olegp@example.com"
  }
}

Список сотрудников

GET /users

скоуп: users:read

Информация о сотруднике

GET /users/{id}

скоуп: users:read

Редактирование сотрудника

PUT /users/{id}

скоуп: users:update

{
  "user": {}
}

Удаление сотрудника

DELETE /users/{id}

скоуп: users:delete

Статус сотрудника

GET /users/{user_id}/status

скоуп: user_status:read

Новый статус сотрудника

PUT /users/{user_id}/status

скоуп: user_status:write

{
  "status": {
    "emoji": "",
    "title": ""
  }
}

Удаление статуса сотрудника

DELETE /users/{user_id}/status

скоуп: user_status:write

Ограничения и gotchas

• user.role: допустимые значения — admin (Администратор), user (Сотрудник), multi_guest (Мульти-гость), guest (Гость)
• status.away_message: максимум 1024 символов
• limit: максимум 50
• Пагинация: cursor-based (limit + cursor), НЕ page-based

Подробнее

см. references/endpoints.md