pachca-users

https://api.pachca.com/api/shared/v1

Authorization: Bearer <ACCESS_TOKEN>

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

• найти сотрудника
• создать пользователя
• список сотрудников
• создать тег
• управлять тегами
• назначить тег
• приостановить сотрудника
• онбординг
• 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 — перебери страницы и отфильтруй на клиенте

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

   ) — получить всех участников

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

insufficient_scope

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

Новый тег

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

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

• limit

  : максимум 50

• user.role

  : допустимые значения —

  admin

  (Администратор),

  user

  (Сотрудник),

  multi_guest

  (Мульти-гость)
• Пагинация: cursor-based (limit + cursor), НЕ page-based

Подробнее